Upgrade a running container to a new image

Pulling a new image does not update an existing container. Recreate the container from the intended image while preserving its deployment settings and durable data. Plan application and database compatibility before the change.

Prepare, replace, verify

Pull first, while the old service is still running:

docker pull registry.example.com/team/myapp:1.3
docker image inspect registry.example.com/team/myapp:1.3
docker inspect myapp

Record the old image ID or digest and the original deployment definition. Inspect output may contain secrets; protect it. Preserve mounts, networks, environment/secret sources, ports, user, resource limits, restart policy and other relevant settings. The following is only an example for a service with those particular settings:

set -e
docker update --restart=no myapp
docker stop myapp
docker rename myapp myapp-old
docker run -d --name myapp \
  --restart unless-stopped \
  -p 127.0.0.1:8080:80 \
  --mount type=volume,source=app-data,target=/data \
  registry.example.com/team/myapp:1.3

The old container is retained but stopped, with automatic restart disabled. This prevents an old always policy from reviving it after a daemon restart while the replacement uses the same data. Record the original policy before the change and restore it deliberately if you roll back. The shell stops on a failed command so a failed stop or rename does not proceed to launching the replacement. Do not run old and new versions simultaneously against a data directory unless the application supports it. Retaining a container is not a backup: a new version may migrate shared data so the old version can no longer read it.

Check logs, the running image identity and representative business requests before retiring the old container:

docker logs --tail 100 myapp
docker inspect --format '{{.Image}}' myapp

With an existing Guance log integration, compare errors by service and version. Use that evidence alongside functional checks, not as a substitute for them.

Compose workflows

For registry images, update the image reference in the Compose file, then:

docker compose pull app
docker compose up -d --no-deps app

For a service built locally:

docker compose up -d --build --no-deps app

Recreation normally retains configured volumes, but changed mount names can select different storage. Do not use down -v as an upgrade step unless data deletion is explicitly intended.

Availability and rollback

Downloading beforehand reduces the replacement window, but startup, migrations and readiness can take longer than a few seconds. Blue-green deployment can reduce interruption if you validate a new instance on another endpoint and switch traffic deliberately. Shared state and schema compatibility still need a plan.

A healthcheck reports health. Plain Compose does not automatically roll back an unhealthy image, and Kubernetes rollout failure does not generally perform an automatic rollback either. Define who or what stops the rollout and restores a known-compatible version and data state.

Back up durable data and copy out any necessary writable-layer changes. docker commit can preserve some filesystem changes for investigation, but it excludes mounted volumes and is not a database backup or reproducible release process.

FAQ

What if the tag stays the same? Pull it, record the resulting digest, and compare it with the deployed content. A tag is movable; an image ID and a registry manifest digest are related identifiers, not interchangeable formats. Deploying a reviewed digest reduces ambiguity.

Can an updater automate this? Tools such as Watchtower have been used to detect image changes and recreate containers. Assess the tool's current maintenance, permissions and rollback behavior before adopting it; unattended updates should not bypass compatibility tests.

How does Kubernetes update? Updating a Deployment's container image triggers its configured rollout. Readiness, replica count, capacity and strategy affect availability; neither zero downtime nor successful rollback is automatic. Preserve a tested rollback and data-migration procedure.

See Compose up reference, Container commit limitations, Kubernetes Deployment rollouts.