Introduction

A running Docker container does not auto-refresh when its image is updated. To apply a new image, you replace the container while preserving required runtime settings and persistent data. A good upgrade runbook includes pull, replace, health verification, and rollback.

Core Sections

1. Treat upgrades as container replacement

Containers are immutable runtime instances created from images. Once started, they keep using the original image layers even if a newer tag exists remotely. That means an upgrade is a recreate operation, not an in-place mutation.

Typical upgrade sequence:

1. Pull target image tag.
2. Stop and remove old container.
3. Start new container with equivalent options.
4. Validate service health.

2. Pull exact image version

Use explicit version tags, not mutable tags, for predictable rollouts.

docker pull myorg/myapp:2.4.1
docker image ls myorg/myapp

If your team supports digest pinning, store and deploy by digest to guarantee byte-identical rollouts across environments.

3. Preserve runtime configuration before replacement

Most failures come from forgetting flags used by the old container. Capture current settings before removing it.

docker inspect myapp > myapp.inspect.json

Important settings to preserve:

• published ports
• environment variables
• mounted volumes
• network aliases
• restart policy

If configuration is already defined in Compose or orchestration manifests, prefer those sources over manual reconstruction.

4. Recreate the container with the new image

1docker stop myapp
2docker rm myapp
3
4docker run -d \
5  --name myapp \
6  -p 8080:8080 \
7  -e APP_ENV=prod \
8  -v myapp-data:/var/lib/myapp \
9  --restart unless-stopped \
10  myorg/myapp:2.4.1

Volume-backed data remains available after container replacement, which is why volume mapping must be preserved exactly.

5. Use Docker Compose for repeatable upgrades

Compose reduces manual flag drift and is usually safer than direct docker run for services with several settings.

docker compose pull myapp
docker compose up -d --no-deps myapp
docker compose ps

--no-deps upgrades one service without restarting unrelated dependencies. Use full stack restart only when dependency contracts changed.

6. Validate health before traffic cutover

A container in running state is not proof of application readiness. Validate endpoints and logs:

curl -f http://localhost:8080/health
docker logs --tail=200 myapp

If app initialization takes time, use health checks and wait conditions in deployment workflow before switching traffic.

7. Prepare and test rollback path

Keep previous stable image tag available until the new version proves stable. Rollback should be a documented command set, not an improvised response.

docker stop myapp
docker rm myapp
docker run -d --name myapp -p 8080:8080 myorg/myapp:2.3.7

For zero-downtime services, use blue-green style rollout and switch load balancer targets only after new container passes checks.

8. Clean up safely after stabilization window

After observing stable behavior for a defined window, remove unused artifacts:

docker image prune -f
docker container prune -f

Do cleanup after rollback window, not immediately after deployment.

Common Pitfalls

• Pulling a new image but forgetting to recreate the running container.
• Recreating container without original env vars, ports, or volumes.
• Deploying mutable tags such as latest in production environments.
• Declaring rollout complete before health and log checks pass.
• Deleting old images too early and slowing incident rollback.

Summary

• Docker upgrades after image changes are replacement workflows.
• Use explicit version tags and preserve runtime configuration.
• Prefer Compose or declarative manifests for repeatability.
• Validate readiness before routing real traffic.
• Keep rollback commands and previous stable images ready.