On a single Docker host, how do you replace a running container with a new image version?

### A container is not a server you upgrade in place An image is immutable, and a container is **one execution of one image with one set of flags**, fixed at the moment it was created. Nothing you can run against an existing container changes which image it runs. `docker restart invoice-worker` stops and starts the *same* container object — same image ID, same ports, same environment. `docker pull` fetches layers into the host's image store and never touches a running process. `docker update` changes a few resource limits and nothing about the image. So "deploy a new version" on a single host has exactly one shape: **create a new container from the new image and get rid of the old one.** Everything else is about ordering that sequence so the outage window is small and so you can go back. ### Pull, then replace The naive script is the wrong order: ```bash docker stop invoice-worker && docker rm invoice-worker docker pull invoice-render:2026.08.19-7c41ab2 # <- service is down for this docker run -d --name invoice-worker invoice-render:2026.08.19-7c41ab2 ``` The pull is the slow, network-dependent, failure-prone step: it can take tens of seconds for changed layers, and it can fail outright on a registry hiccup or an expired credential. Doing it *after* the stop means the service is down for all of it, and a failed pull leaves you with no container at all. Pull first and the old container is still answering requests the whole time; if the pull fails you abort and nothing has changed. The remaining downtime is the stop plus the start — for a small Python service on `python:slim` that is typically a second or two, dominated by the application's own startup. ### Pin the tag Pull-then-replace is only reproducible if the tag is. A floating tag such as `latest` makes two questions unanswerable: *which build is on this box?* and *what does rollback mean?* Two hosts pulling `latest` a minute apart can land on different builds, and re-pulling `latest` after a bad deploy gets you the bad build again. Use a build-specific tag — `invoice-render:2026.08.19-7c41ab2`, a date plus the commit — or pin the digest with `invoice-render@sha256:…`, which is the only form that is cryptographically exact. Note that a running container is never affected by someone re-pushing a tag; the container holds a resolved image ID. The change only arrives when you pull *and* recreate. ### Put the flags where the deploy can find them The run flags **are** the deployment: published ports, mounts, environment, `--user`, memory limits. If they live in a shell history, the next deploy loses one of them silently. On a single host the usual home for them is a systemd unit that owns the container, with the pull as a pre-start step: ```ini [Service] ExecStartPre=-/usr/bin/docker pull invoice-render:2026.08.19-7c41ab2 ExecStartPre=-/usr/bin/docker rm -f invoice-worker ExecStart=/usr/bin/docker run --rm --name invoice-worker \ -p 127.0.0.1:8127:8000 invoice-render:2026.08.19-7c41ab2 ExecStop=/usr/bin/docker stop invoice-worker ``` Deploying is then editing the tag and running `systemctl restart invoice-worker`. The leading `-` on the pre-start lines matters: without it, a boot while the registry is unreachable fails the unit and you get no service at all, when the cached image on disk would have been perfectly good. With it, a failed pull is tolerated and the host boots on what it already has. The `docker rm -f` line clears a stale container left by an unclean stop — otherwise `docker run --name invoice-worker` fails with `Conflict. The container name "/invoice-worker" is already in use`. ### Keep the old image Rollback on one host is `docker run` on the previous tag — seconds, and no registry round trip — **provided the previous image is still on disk**. A deploy script that prunes images immediately after a successful start has thrown that away and turned a ten-second rollback into a re-pull that may not even succeed. Keep the last few builds and clean up on a schedule instead. ### What replacement destroys Because the deploy deletes a container, everything in that container's writable layer goes with it: temporary files, anything the app wrote to a path that is not a mount. Any state that must survive a deploy has to live in a named volume or a bind mount, or outside the host entirely. This is worth saying out loud in an interview, because it is the difference between "we redeploy weekly" and "we redeploy weekly and lose the render cache each time". ### What this pattern does not give you Pull-then-replace shrinks the outage; it does not remove it. The stop and the start do not overlap, so there is a window — short, but real — in which nothing is listening on the port and callers get connection refused. Removing that window means running both containers at once behind something that routes, which is a different technique with its own constraints.