Keep Docker Containers Updated Without Breaking Things
A practical guide to updating Docker containers safely, choosing the right image tags, automating stateless services, protecting databases, and knowing when an update should stay completely manual.
Updating Docker containers sounds more complicated than it really is. The confusion usually starts with one assumption: that Docker somehow patches the software inside a running container.
It does not. In normal Docker workflows, you update the image, remove the old container and create a new container from that newer image. Persistent data survives because it should be stored outside the disposable container filesystem in volumes or bind mounts.
Once you understand that model, updating a web server such as Nginx can be almost boring. Updating a database, however, deserves much more care. A web container can usually be replaced in seconds. A database may require backups, compatibility checks, migrations and a deliberate maintenance window.
For most Docker Compose projects, the safest basic update is: pull the new image and recreate the service.
docker compose pull web docker compose up -d web
Use automatic updating only where failure is easy to recover from. Stateless services such as reverse proxies, exporters and simple web applications are reasonable candidates. Databases should normally be pinned to a major version and updated deliberately after a backup.
The Docker jargon you actually need
You do not need to memorize Docker’s entire vocabulary before maintaining a server. These concepts explain nearly everything that matters during an update.
The packaged blueprint used to create a container. Images are read-only and versioned.
A running instance created from an image. Containers are designed to be replaceable.
A readable image label such as nginx:latest or postgres:16.
A cryptographic identifier representing one exact image. Unlike a tag, a digest does not silently move.
Persistent storage kept outside the disposable container. Databases and application data belong here.
A server storing images. Docker Hub is the best-known example, although private registries are common.
A service whose container can disappear without destroying irreplaceable data.
A service whose data must survive, such as Postgres, MySQL, Nextcloud or many automation platforms.
Updating a Docker container really means replacing it
A normal Docker container is not something you should treat like a traditional virtual machine. You normally do not log into it, run package upgrades and keep that modified container around forever.
Instead, you describe the application configuration outside the container. When an updated image becomes available, Docker starts a replacement using the same configuration.
Existing image
app:1.4
Pull newer
image
Recreate
container
Reattach volume
& configuration
Imagine a hotel room rather than a house. Your application container is the room. Your important data is the luggage. When you update, you move the luggage into a fresh room rather than rebuilding the old room while you are still inside it.
The safe manual Docker update workflow
Even if you eventually automate updates, learn the manual process first. Automation tools are mostly performing these same operations for you.
Back up important state
Stateless services may need no special backup. Stateful applications and databases are different. Before changing versions, verify that you have a recent backup and know how to restore it.
For a simple named volume, one possible backup pattern looks like this:
docker run --rm \ -v my_app_data:/data \ -v "$(pwd)":/backup \ alpine \ tar czf /backup/my_app_data-backup.tar.gz /data
Pull the new Docker image
If your service in compose.yml is named web, run:
docker compose pull web
Docker downloads the image layers while your old container continues running. Pulling therefore usually creates no user-visible outage by itself.
Recreate the service
docker compose up -d web
Compose compares the service definition against what is currently running. If the image changed, it replaces the old container and attaches the same networks, environment variables, ports and volumes defined in your Compose configuration.
Verify the application
Do not assume that a running container means a healthy application. Check its state, logs and public endpoint.
docker compose ps docker compose logs --tail=100 web curl -I https://example.com
If your image or application exposes a version, confirm that the new version is actually running.
Clean up old images
After you are satisfied with the update, you can remove dangling images to recover disk space:
docker image prune
Avoid aggressive cleanup commands until you are confident you no longer need older images for a quick rollback.
backup if necessary → pull → recreate → verify → clean up. That workflow is easy to understand, easy to audit and usually all a small server needs.
Automating Docker updates with Watchtower
Watchtower is designed to inspect running containers, discover updated images and recreate qualifying containers automatically.
The original containrrr/watchtower repository was archived in December 2025. A maintained fork continues the project under nicholas-fedor/watchtower .
A safer Watchtower Compose configuration
services:
watchtower:
image: nickfedor/watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WATCHTOWER_LABEL_ENABLE=true
- WATCHTOWER_SCHEDULE=0 0 4 * * *
- WATCHTOWER_CLEANUP=true
restart: unless-stopped
The most important line is WATCHTOWER_LABEL_ENABLE=true . It changes the model from “update everything” to “update only what I specifically approve.”
Opt one service into automatic updates
services:
web:
image: nginx:latest
labels:
- "com.centurylinklabs.watchtower.enable=true"
restart: unless-stopped
With this configuration, your web service is eligible for Watchtower updates. An unlabeled database sitting beside it is ignored.
When Watchtower makes sense
Why blindly auto-updating databases can break your stack
The most dangerous Docker update configuration is not Watchtower itself. It is combining unrestricted automation with a database image that tracks a moving major version.
Imagine the following Compose service:
services:
db:
image: postgres:latest
volumes:
- postgres_data:/var/lib/postgresql/data
This may work perfectly for months. Then the latest tag can move to a new Postgres major version.
Your data directory was initialized by the previous major version. The new server binary may refuse to use that older on-disk format until you perform the migration required by Postgres.
A safer database configuration
services:
db:
image: postgres:16
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
Now normal updates stay within Postgres 16 unless you deliberately change the image reference.
Database major upgrades should be treated as migrations
A deliberate major upgrade should include:
- Read the release and migration notes.
- Create and verify a current backup.
- Confirm compatibility with the application using the database.
- Schedule a maintenance window if downtime matters.
- Perform the documented upgrade or migration process.
- Verify data, application behavior and backups afterward.
Diun: know an update exists without automatically installing it
Sometimes the ideal automation is not “update my software.” It is simply “tell me when an update is available.”
Diun stands for Docker Image Update Notifier. It monitors image changes and can send notifications without replacing your application containers.
That separation is particularly useful for databases and important stateful applications.
Example Diun service
services:
diun:
image: crazymax/diun:latest
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- diun_data:/data
environment:
- DIUN_WATCH_SCHEDULE=0 */6 * * *
- DIUN_PROVIDERS_DOCKER=true
restart: unless-stopped
volumes:
diun_data:
Then opt a service into monitoring:
services:
db:
image: postgres:16
labels:
- "diun.enable=true"
Your workflow becomes:
published
the change
a notification
to update
That extra human decision is not a weakness. For valuable state, it is often exactly the safety control you want.
Which Docker update strategy should you use?
There is no universal Docker update rule because container risk depends on what the service does and what happens if it starts incorrectly.
| Container type | Examples | Tag strategy | Suggested update method |
|---|---|---|---|
| Stateless | Nginx, redirects, exporters, simple web frontends | Latest or a major pin | Watchtower can work well when label-scoped and monitored. |
| Stateful application | Nextcloud, n8n, Ghost, Uptime Kuma | Prefer a controlled version range | Notification first, then manual update after a backup. |
| Database | Postgres, MySQL, MariaDB, MongoDB | Pin the major version | Notify only. Perform patch updates deliberately and treat major jumps as migrations. |
| Update helper | Diun, Watchtower | Latest is often acceptable | Automatic update may be reasonable because these normally store little application state. |
A practical maintenance rhythm
You do not have to obsessively update every container the minute an image changes. A more useful goal is to create a repeatable maintenance habit.
What about downtime?
For a simple single-container service, the visible interruption normally occurs during the stop-and-start window, not during the image download. On a reasonably fast server that can be short, although exact timing varies with the application, health checks, initialization time and server load.
The previous container can normally continue serving while Docker downloads the new image.
Downtime starts when the old instance stops and ends when the new service is ready.
Database checks, migrations and startup routines can significantly extend recovery time.
If even a few seconds are unacceptable, the solution is not simply “never update.” Use deployment architecture designed for availability: multiple replicas, health checks, a reverse proxy or load balancer, and rolling or blue/green deployment techniques.
How to roll back a Docker update
Rollback is easiest when you avoid floating tags for critical deployments and know which image worked before the update.
Suppose your Compose file originally contained:
services:
app:
image: example/app:2.7.3
You change it to example/app:2.8.0 and discover a problem. Restore the previous tag:
services:
app:
image: example/app:2.7.3
Then pull and recreate:
docker compose pull app docker compose up -d app
Docker container update command cheat sheet
| Task | Command |
|---|---|
| Show running Compose services | docker compose ps |
| Pull images for all services | docker compose pull |
| Pull one service | docker compose pull app |
| Recreate services | docker compose up -d |
| Recreate one service | docker compose up -d app |
| Read recent logs | docker compose logs --tail=100 app |
| List Docker images | docker image ls |
| Remove dangling images | docker image prune |
| Show container resource usage | docker stats |
Docker update best practices
1. Keep your Compose files
Your Compose configuration is the recipe for recreating the environment. Keep a copy outside the server and ideally track it in Git.
2. Never store irreplaceable data only inside a container
Containers are disposable. Persistent data should live in volumes, bind mounts, external databases or other durable storage.
3. Use health checks when possible
A process can be running while the service is still unusable. Docker health checks and external monitoring provide stronger verification than checking container status alone.
4. Read release notes for stateful software
The more important the data, the less appropriate blind updating becomes. Review breaking changes, backup instructions and migration requirements before switching versions.
5. Monitor disk usage
Repeated image pulls can leave old layers consuming disk space. Inspect usage periodically:
docker system df
6. Do not expose the Docker socket casually
Tools such as Watchtower need substantial Docker privileges when given access to /var/run/docker.sock . Treat containers with Docker socket access as highly trusted infrastructure.
Frequently asked questions
Does docker container update install a newer Docker image?
No. The command modifies selected runtime configuration such as CPU, memory and restart behavior. To run newer application software, pull a new image and recreate the container.
How do I update one Docker Compose container?
If the service is called
web, a common workflow is:
docker compose pull web docker compose up -d web
Can I update Docker containers without losing data?
Yes, if important data is stored persistently in volumes, bind mounts or external storage. Replacing the application container does not automatically delete a separate Docker volume.
Should I use the latest tag?
It depends on the service. A floating latest tag may be convenient for disposable stateless software. For a database or other important stateful application, pinning at least the major version provides more predictable upgrades.
Is Watchtower still maintained?
The original containrrr/watchtower repository was archived in December 2025. Development continues in the maintained nickfedor/watchtower fork .
Should Watchtower automatically update Postgres?
Automatic major-version changes are risky for databases. A safer pattern is to pin the database major version, receive update notifications, create a backup and perform the update deliberately.
What is the difference between Watchtower and Diun?
Watchtower can act on an update by pulling an image and recreating the container. Diun primarily tells you that an updated image is available. For this reason, Diun is particularly attractive for services where you want a human to approve the update.
How often should Docker containers be updated?
There is no universal schedule. Security-sensitive, public-facing services deserve frequent review. Routine applications can be handled during a regular weekly or monthly maintenance window. Critical databases should be updated according to their security advisories, compatibility requirements and your backup procedure.
Can Docker containers be updated with zero downtime?
A single container usually has at least a short replacement window. True near-zero-downtime deployment normally requires multiple replicas or a second application instance behind a reverse proxy or load balancer so traffic can move before the old instance stops.
Before your next container update
- Confirm which image tag is currently deployed.
- Check the release notes for important changes.
- Back up stateful applications and databases.
- Pull the image before stopping the current container.
- Recreate only the service you intend to change.
- Verify logs and application health afterward.
- Keep the previous version information available for rollback.
- Clean old images only after confirming the upgrade is stable.
The safest Docker updater is a good update policy
The best Docker maintenance setup is not necessarily the one with the most automation.
For a disposable web service, automatic updates may save time. For a database containing important business data, receiving a notification and spending a few minutes reviewing the release is often a better trade.
Keep the distinction simple:
Once your images are sensibly pinned, data lives in persistent storage, backups are tested and Compose files are preserved, updating Docker containers becomes a predictable maintenance task instead of something to fear.
