How to Update Docker Compose Containers Safely

An update can start successfully and still leave you with a broken login, a failed background worker or a database the old version can no longer read. The useful question is not just “how do I get the latest image?” It is “how will I know the update worked, and what will I do if it did not?”

Below is a repeatable workflow for self-hosted applications, APIs and bots. If you are still setting up your server, start with our Docker Compose VPS guide. Here we focus on maintaining a stack that already contains data you care about.

1. Check the running stack before changing anything

Open the directory you normally deploy from. Keep the same Compose files, project name, environment file and profiles throughout the update. If your deployment uses -f, -p or --env-file, include those same options in the commands below. A different project name can create a different named volume and make an application appear empty.

docker compose version
docker compose config --quiet
docker compose config --services
docker compose ps
docker compose images
df -h
docker system df

config --quiet validates without printing the resolved configuration. Avoid pasting unrestricted docker compose config output into tickets: resolved environment variables can include credentials. See Docker's configuration command reference.

Prefer an explicit version over an unexpected change

Select the release you intend to deploy in the service's image: setting. A floating tag such as latest does not describe an upgrade policy. Even a version tag can be republished; a recorded image digest identifies a particular image. Check the publisher's release and architecture support before pinning one.

Keep configuration in version control where practical, but keep passwords, tokens and private environment files out of the repository. Store the recovery copy securely too. Knowing the old image is helpful only if you can also reconstruct its configuration.

2. Back up application data, not just the Compose file

A Compose file describes the deployment. It does not contain uploaded files, database rows or all the secrets required to recover them. Map out the data before taking a backup:

docker compose ps -q app
# Use the container ID returned above:
docker inspect --format '{{json .Mounts}}' CONTAINER_ID

Check every stateful service, not just the web application. Confirm where each mount points and whether important files have accidentally been written only inside a container. Docker's volume documentation explains why persistent storage lives separately from the container's writable layer.

• Database: use the database's supported backup/export procedure and verify its exit status. A copy of live database files is not automatically a consistent backup.
• Uploads and application state: back up the relevant named volumes or bind-mounted directories with ownership and permissions preserved.
• Configuration and keys: save Compose files, required environment settings and encryption keys in protected storage. Missing encryption keys can make an otherwise complete backup unusable.

If writes must be paused to obtain a consistent recovery point, put the application into its documented maintenance mode and stop the relevant writers or workers. Follow the application's backup instructions rather than assuming one generic archive command works for every stack.

Keep a copy outside the VPS. Our VPS backup strategy covers recovery planning, while the encrypted Storage Box backup guide provides an off-server file-storage workflow. Neither a backup job reporting success nor an untested snapshot proves that the application can be restored.

3. Pull the selected image and recreate the service

After editing the image reference to your chosen release and completing the backup, validate again. For a standalone application update whose existing dependencies remain compatible:

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

Run these one at a time and stop if a command fails. Compose pull fetches the image without replacing the running container. Compose up applies the changed image or configuration. The --no-deps option keeps this operation scoped to the selected service; it is not appropriate if that release also needs updated dependencies.

For a coordinated update, review and pin the intended versions for the whole stack, back up every affected stateful component, then use docker compose pull and docker compose up -d. Do not accidentally roll a database onto a new major version while trying to update only the frontend.

What if the application is built locally?

If you use build: rather than a published application image, pull is not a replacement for rebuilding your code. Docker's production Compose guidance uses a rebuild followed by recreation of the selected service:

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

Build from the reviewed source revision and dependency lockfiles. Keep the previous deployable image available until the new release is accepted. A source checkout alone may not reproduce an older build if dependencies or base images have changed.

Likewise, docker compose restart restarts existing containers; it does not apply a new image or changed environment settings. That distinction is documented in the restart reference.

4. Check more than the container's running status

docker compose ps
docker compose logs --since=10m --tail=200 app
docker stats --no-stream

Look for migration failures, permission errors, repeated restarts and unusual resource use. Logs can contain sensitive information, so redact them before sharing. If you have configured meaningful health checks and your Compose version supports it, docker compose up -d --no-deps --wait --wait-timeout 120 app can wait for startup health. Without a health check, a running container is still not proof the application works.

Expect a brief interruption when a single application container is replaced. If you need near-zero downtime, plan redundant instances, traffic switching and compatible data migrations separately. A successful pull or a restart policy does not provide that architecture.

If something fails, our guides to 502 errors behind a reverse proxy, Docker exit 137 and OOM kills, and a full Linux disk can help narrow down the cause before you make another change.

5. Decide whether you need a rollback or a restore

There are two different recovery situations. If only the application image changed and the old version remains compatible with the data, returning the image: reference to the recorded previous version or digest and recreating the service may be sufficient.

If the release migrated the database or rewrote stored files incompatibly, switching the image alone is not a safe rollback. Stop further writes, retain the failed state for investigation where feasible, and follow the vendor's recovery process using the matching configuration and pre-update backup. Restoring that backup may discard writes received since it was taken; account for those changes before reopening the service.

• Document the last known-good version and the exact recovery point.
• Confirm that the previous image is still retrievable or retained locally.
• Set a maintenance-window limit so troubleshooting does not continue indefinitely.
• Re-run the same user-facing checks after recovery.

Do not run a broad cleanup immediately after deployment. Old images may be part of your recovery plan. Once the release is accepted and recovery requirements are satisfied, review unused resources deliberately; “unused” does not mean “worthless”.

Should you enable automatic container updates?

Automate notification and testing first. For a small stateless service with reliable health checks and a tested rollback, unattended updates may be a reasonable trade-off. For a personal archive, password vault, database-backed business application or bot with paid users, a silent overnight migration deserves more caution.

A practical middle ground is to receive release alerts, review the changes, run an isolated test, then deploy during a short maintenance window. Keep a schedule for security updates so “manual review” does not become “never update”. Your operating system, Docker Engine and application images also have separate update lifecycles.

Running your Compose stack on HYEHOST

A HYEHOST Cloud VPS gives you control over Docker, application versions and maintenance timing. Choose Wolverhampton, Ashburn or Auckland based on your users and requirements, then allow enough RAM and disk for the application plus updates and recovery work. Do not size only for the idle container.

A separate Storage Box can hold exported backups over supported protocols; it is a backup destination, not a substitute for a database-aware backup procedure. If you maintain several environments, VPS resource pools let you divide capacity between VMs. Check the current pool locations and limits before planning a staging deployment.

Docker Compose update FAQ