Reference: See Container Registries Compared to understand registry differences during migration, and How Enterprises Patch Containers to plan your patch management strategy.

Moving from Debian, Ubuntu, or Alpine base images to CleanStart takes one to four weeks depending on your application count and CI/CD maturity. The main work is Dockerfile changes and pipeline updates—your application code doesn't change.

The following diagram illustrates the migration decision tree and timeline:

graph TD    A["Current Setup<br/>Legacy Base Images"] -->|Assess| B{"Migration<br/>Complexity?"}     B -->|Low| C["Low Complexity<br/>1 Week"]    B -->|Medium| D["Medium Complexity<br/>2 Weeks"]    B -->|High| E["High Complexity<br/>3-4 Weeks"]     C -->|Service Types| C1["Node.js Apps<br/>Python Apps<br/>Go Services"]    D -->|Service Types| D1["Database Migrations<br/>Version Upgrades<br/>Config Changes"]    E -->|Service Types| E1["Custom Compiles<br/>Hardware Specific<br/>GPU Workloads"]     C1 -->|Phase 1| F["Inventory<br/>1 Week"]    D1 -->|Phase 1| F    E1 -->|Phase 1| F     F -->|Phase 2| G["Assessment<br/>2 Weeks"]    G -->|Create| H["Migration Matrix<br/>Service List<br/>Timeline"]     H -->|Phase 3| I["Plan & Schedule<br/>2-3 Weeks"]    I -->|Create| J["Implementation Plan<br/>Risk Assessment"]     J -->|Phase 4| K["Execute<br/>Per Timeline"]     K -->|Dev| L["Dev Environment<br/>Test Migration<br/>Validate Builds"]     L -->|Pass| M{Tests<br/>Pass?}     M -->|No| N["Debug<br/>Update Plan"]    N -->|Iterate| L     M -->|Yes| O["Staging<br/>Test Full Stack<br/>Performance Test"]     O -->|Pass| P{Production<br/>Ready?}     P -->|No| Q["Fix Issues<br/>Retest"]    Q -->|Iterate| O     P -->|Yes| R["Production<br/>Gradual Rollout<br/>Monitor"]     R -->|Stable| S["Decommission<br/>Old Base Images"]     S -->|Complete| T["Migration<br/>Complete<br/>Benefits Realized"]     style A fill:#ffcccc    style C fill:#ffffcc    style D fill:#ffffcc    style E fill:#ffffcc    style T fill:#99ff99

Why Migrate to CleanStart?

CleanStart delivers comprehensive security advantages over legacy base images through multiple mechanisms. Every image is pre-scanned for CVEs before release, ensuring no unpatched vulnerabilities reach your deployments. Images come with verifiable provenance and signatures proving their authenticity and origin. Security patches are applied automatically without waiting for upstream distributions to release them. For regulated industries, FIPS 140-3 variants are available for cryptographically-sensitive workloads.

CleanStart base images are optimized for container environments through multiple mechanisms including smaller sizes that enable faster startup times and come pre-configured with production-ready defaults that reduce configuration time. The minimal package set reduces your attack surface and requires less ongoing security maintenance. The optimized base images provide better resource utilization with lower memory footprints, allowing more efficient packing of containers across your cluster.

CleanStart images act as drop-in replacements for common base images, which significantly simplifies the migration process since your application code requires minimal changes. The consistent ecosystem means all CleanStart images follow the same patterns and conventions, reducing cognitive load as you work across different services. Better documentation with language and framework-specific guides accelerates adoption and enables faster onboarding. Active development and responsive support ensure your questions get answered promptly.

Migration Assessment

Phase 1: Inventory (1 week)

Begin by documenting your current state through a comprehensive listing of all container images currently in use. Find all Dockerfiles throughout your codebase and identify their base images. Categorize images by runtime language and deployment complexity to inform your migration planning.

# List all container images in usedocker imagesdocker ps -a --format "{{.Image}}" # Find Dockerfiles in your codebasefind . -name "Dockerfile*" -type f # Identify base imagesgrep "^FROM" $(find . -name "Dockerfile*")

Create an inventory spreadsheet tracking each service:

Phase 2: Assessment (2 weeks)

Evaluate complexity by considering your current setup and the full scope of the migration. Low-complexity migrations involve services using the same language version or a newer version with no custom build steps, standard framework dependencies, and no special requirements. Medium-complexity migrations require careful evaluation due to major version upgrades, custom build optimizations, or database schema changes. High-complexity migrations demand thorough planning because they involve custom compiled packages, specialized kernel modules, or hardware-specific optimizations.

Low-complexity services can migrate immediately because they use standard runtimes with minimal customization—for example, upgrading from node:16-alpine to cleanstart/node:20 requires only a Dockerfile change. Medium-complexity services require careful testing because they involve version changes or custom configurations—for example, migrating from postgres:14 to cleanstart/postgresql:16 demands integration testing before production deployment. High-complexity services require extensive planning because they depend on specialized infrastructure—for example, GPU-accelerated ML workloads may require additional configuration for hardware support.

Phase 3: Plan (2-3 weeks)

Create a migration timeline that staggers work to manage risk:

Week 1: Low-complexity services (Node.js, Python apps)Week 2: Medium-complexity services (Databases, caches)Week 3: High-complexity services and validationWeek 4: Production rollout and monitoring

Identify dependencies before migrating to understand the order in which services should be upgraded. For example, if the API service communicates with the database and cache, and the workers service depends on the same database, you should start by migrating leaf services that have no dependencies, then work upstream toward services that depend on others.

Migration Execution Phases

Phase 1: Testing (1 week per service)

Step 1: Create Test Environment

Clone your Dockerfile and update the base image for testing:

cp Dockerfile Dockerfile.test # Update base imagesed -i 's|FROM node:16|FROM cleanstart/node:20|g' Dockerfile.test # Build test imagedocker build -t myservice:test -f Dockerfile.test .

Step 2: Validate Build

Verify the test image builds correctly and is smaller than the original:

# Check image sizedocker inspect myservice:test | jq '.[0].Size' # Verify dependenciesdocker run --rm myservice:test npm list # Check file systemdocker run --rm myservice:test ls -la /app

Step 3: Functional Testing

Test that the application works correctly in the new image:

# Run unit testsdocker run --rm myservice:test npm test # Run integration tests (if applicable)docker-compose -f docker-compose.test.yml up --abort-on-container-exit # Load testingdocker run --rm -v $(pwd)/load-test.js:/load-test.js myservice:test \    node /load-test.js http://localhost:3000

Step 4: Security Verification

Scan the new image for vulnerabilities and verify hardening:

# Scan for vulnerabilitiesdocker run --rm aquasec/trivy image myservice:test # Check base imagedocker inspect myservice:test | jq '.[0].RootFS.Layers' # Verify user is non-rootdocker run --rm myservice:test id

Phase 2: Staging (1 week)

Deploy the test image to a staging environment that mirrors production:

# Tag image for stagingdocker tag myservice:test registry.example.com/myservice:staging # Push to registrydocker push registry.example.com/myservice:staging # Deploy to staging clusterkubectl set image deployment/myservice-staging \    myservice=registry.example.com/myservice:staging --record

Monitor the staging deployment:

# Check logskubectl logs -f deployment/myservice-staging # Monitor metricskubectl top pods -l app=myservice # Run smoke tests./smoke-tests.sh --environment staging --service myservice

Phase 3: Production Rollout (1 week)

Execute a controlled production deployment using blue-green deployment strategy:

# Blue-green deploymentkubectl set image deployment/myservice \    myservice=registry.example.com/myservice:production \    --record # Monitor rolloutkubectl rollout status deployment/myservice # Check metricskubectl get pods -l app=myservice

Rollback Plan

Keep the old image available for quick rollback:

# Quick rollback if issues occurkubectl set image deployment/myservice \    myservice=registry.example.com/myservice:old-stable

Phase 4: Validation (Ongoing)

Monitor the deployment continuously after production launch:

# Daily checks for first week./health-check.sh production myservice # Monitor error ratescurl metrics.example.com/api/myservice/error-rate # Check response timescurl metrics.example.com/api/myservice/p95-latency # Verify resource usagekubectl top nodeskubectl top pods

Common Pitfalls and Solutions

Pitfall 1: Skipping Testing

Deploying untested images to production inevitably causes outages and disrupts service for users. Always test in a staging environment that mirrors production before deploying to real users. Use a mandatory testing checklist to ensure comprehensive validation, verifying that unit tests pass, integration tests pass, the container starts without errors, health checks respond promptly, load tests show acceptable performance metrics, no security vulnerabilities are detected, and the application runs as a non-root user.

Pitfall 2: Version Incompatibility

Newer image versions may introduce breaking changes that affect application behavior. Test major version upgrades with extra care, as upgrading from python:3.9 to cleanstart/python:3.10 requires careful validation, and upgrading to cleanstart/python:3.12 requires even more thorough testing due to multiple major version jumps. Always check the changelog before upgrading to understand what has changed between versions.

Pitfall 3: Dependency Changes

New base images have different packages installed, which can affect application behavior. Document and test all dependencies thoroughly by comparing the base images before and after migration. Use command-line tools to list installed packages in each image, save the output to files, and review the differences to understand what was added or removed.

Pitfall 4: Configuration Drift

Environment variables or configuration files that are not updated for new images cause runtime failures. Audit all configuration thoroughly by verifying environment variables, checking mounted volumes, and validating that configuration files are present and correct in the new image. Configuration drift can introduce subtle bugs that only appear under production load.

Migration Checklist

Pre-Migration

Before beginning any migration, you should inventory all services and images in your environment, assess complexity for each service, identify dependencies and the optimal migration order, create a rollback plan in case issues arise, allocate sufficient testing time and resources, and notify all stakeholders of the migration timeline.

Per-Service Migration

For each service being migrated, create a Dockerfile with the new base image, build and run it locally to verify basic functionality, execute unit and integration tests to ensure behavior hasn't changed, run security scans to verify no new vulnerabilities were introduced, verify performance metrics like latency, memory, and CPU match or improve over the old image, load test the new image if applicable to your workload, deploy to staging to validate in a production-like environment, run smoke tests in staging, document any configuration changes needed, and get approval for production deployment from the appropriate stakeholders.

Production Deployment

Tag the image with a production version, push it to your registry, execute a blue-green deployment to enable instant rollback if needed, monitor health metrics for at least 24 hours after deployment, verify error rates remain acceptable, check resource utilization patterns, confirm no security alerts were triggered, document lessons learned for future migrations, and update runbooks and operational documentation for the new image.

Post-Migration

After successful migration, archive old images but keep them for 30 days in case you need to rollback, update all documentation to reflect the new base images, update CI/CD pipelines to use the new images, review monitoring and alerting rules to ensure they still function correctly, conduct a lessons-learned session with your team, and plan the next phases of migration for remaining services.

Rollback Procedures

Quick Rollback (Minutes)

Perform immediate rollback if critical issues occur:

# Kuberneteskubectl set image deployment/myservice \    myservice=registry.example.com/myservice:old-stable --recordkubectl rollout undo deployment/myservice # Docker Swarmdocker service update --image registry.example.com/myservice:old-stable myservice # Manual Dockerdocker stop myservicedocker run -d --name myservice registry.example.com/myservice:old-stable

Graceful Rollback (Hours)

For non-critical issues, roll back gradually by draining traffic from the new version, scaling down new version replicas, scaling up old version replicas, verifying all traffic on the old version, deleting new version containers, and conducting post-mortem analysis.

Timeline Examples

Quick Migration (Small Service)

Complete a small service migration in 3 days:

Week 1: Monday-Wednesday  Day 1: Build and local testing  Day 2: Staging deployment and testing  Day 3: Production deployment Week 1: Thursday-Friday  Monitor for issues, complete documentation

Standard Migration (Medium Service)

Plan for 4 weeks with proper testing:

Week 1: Planning and assessmentWeek 2: Development and unit testingWeek 3: Staging deployment and integration testingWeek 4: Production rollout and monitoring

Complex Migration (Multiple Services)

Spread complex migrations over 9 weeks:

Week 1: Inventory and assessmentWeek 2: Planning and resource allocationWeeks 3-4: Service 1 migrationWeeks 5-6: Service 2 migrationWeeks 7-8: Service 3 migration (dependent on 1 and 2)Week 9: Full validation and optimization

Tools and Automation

Automated Testing

Create a script to test migration automatically:

#!/bin/bash# test-migration.sh IMAGE=$1SERVICE=$2 echo "Testing $SERVICE with $IMAGE..." docker build -t $SERVICE:test -f Dockerfile.test .docker run --rm $SERVICE:test npm testdocker run --rm $SERVICE:test npm run integration-testdocker run --rm aquasec/trivy image $SERVICE:test echo "Tests completed!"

Monitoring Automation

Set up Prometheus alerts for problems:

# Prometheus alert rule- alert: HighErrorRateAfterMigration  expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.01  for: 5m  annotations:    summary: "High error rate detected"    action: "Check application logs and rollback if necessary"

Support Resources

CleanStart Language Guides, Application-Specific Guides, Troubleshooting Guide, and Community Slack.

Next Steps

Choose your first service for migration, Review the language-specific getting-started guide, Set up testing and staging environments, and Execute migration following this framework.