Zero-Downtime Deployments with Docker Compose

The goal

A restart that takes your site offline for a few seconds is a deployment that failed quietly. With a reverse proxy in front and a health check after it, a Compose stack can be updated while the old container keeps serving traffic.

Health checks come first

Compose lets you declare a healthcheck for every service.

• The proxy should only pass traffic to containers reporting "healthy".
• The application's health endpoint must not just return 200; it should verify the database connection behind it.
• Give the check a generous start period on the first boot.

The update strategy

When you run `docker compose up -d`, Compose recreates changed containers one by one. Pair that with a running proxy and you get a rolling update for free.

• Run the migrations and other long tasks as a separate one-shot service before the web container restarts.
• Let the new container reach healthy before the old one is removed.
• Watch the logs during the switch instead of walking away.

What this blog's deploy actually does

The deploy script for this site pulls the new images, runs a migration guard, starts the new containers and then verifies a health URL returns 200 before reporting success. That verification step is what turns a deploy from a wish into a fact.

The takeaway

Zero downtime is a composition of small habits: a real health endpoint, a proxy that respects it, and a deploy script that will not celebrate early. Automate the checks and your teammates will thank you.

Key takeaways

• Put a reverse proxy in front of the stack and let it forward traffic only to containers reporting healthy.
• Make the health endpoint check the database connection, not just return a 200 status code.
• Run migrations as a separate one-shot service so they finish before the web container restarts.
• Give the first boot a generous health-check start period so slow starts are not killed.
• Verify a health URL returns 200 before the deploy script reports success, and watch the logs during the switch.

FAQ

Q: What actually makes a Docker Compose update zero-downtime? A: The combination of a reverse proxy and a real health check. Compose recreates changed containers one by one, so as long as the proxy forwards traffic only to healthy containers, the old container keeps serving while the new one boots.

Q: What should a health endpoint check before I call a deploy successful? A: More than a status code. The endpoint should verify the database connection behind it, and the deploy script should fetch a health URL and see 200 before it reports success. That verification step is what turns a deploy from a wish into a fact.