Cloud & Infrastructure

Deploying a Real Stack with Docker Compose

If containers don't come up after a server restart, or the database connects to the wrong network, this practical Docker Compose guide solves the problem.

Cloud & Infrastructure

You've restarted the server and now the site won't come up. docker ps shows no containers, or worse: the database is up but the application can't connect to it with a Connection refused error. If you've brought up several containers manually with docker run, this is exactly where you hit the wall. Docker Compose was built for this very moment: one file, the whole stack, and predictable behavior after every restart.

Why docker run doesn't work for a real stack

A single docker run command describes only one container. When you have a web app, a database, and a cache, you have to manually manage startup order, the shared network, volumes, and environment variables yourself. This works the first time. The second time the server restarts, no one runs the commands again.

Compose turns this situation into a compose.yaml file that is both documentation and executable. The main difference comes down to three things: the internal network where services find each other by name, startup order dependencies, and the restart policy.

Internal network: why the application can't find the database by name

In Compose, each service is reachable by its own name on the default network. That means if you name the database service db, the application must connect to the host db, not localhost. This is where people make mistakes: a developer hardcodes localhost in the code on their laptop, then brings the same code up on the server and finds the application can't connect to the database. The symptom is this: the web container comes up healthy, the log shows a connection error, but docker ps shows everything green.

The solution is an environment variable. Never hardcode the database host in the code:

services:
  web:
    image: myapp:1.4.2
    environment:
      DB_HOST: db
      REDIS_HOST: cache
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      retries: 5

  cache:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  db_data:

Two points in this file are worth noting. First, depends_on with condition: service_healthy actually waits until the database is ready; the simple version of depends_on only respects the start order and doesn't care about readiness. Second, restart: unless-stopped makes containers come back on their own after a server restart. Without this line, you see exactly the scene described at the beginning.

Managing environment variables and secrets

Don't write the database password inside compose.yaml. You'll commit the file to Git and the password stays in the history forever. Use a .env file and put it in .gitignore:

DB_ROOT_PASSWORD=a-long-random-password
APP_ENV=production

Compose automatically reads the .env file next to compose.yaml and substitutes ${DB_ROOT_PASSWORD}. For a production environment, keep the secrets file with restricted permissions: chmod 600 .env. This prevents other users on the server from reading the password.

A practical trap: if a variable's value contains the $ character, Compose interprets it as a variable. For random passwords that may contain $, write it as $$ or use a separate env_file.

Volumes: data that shouldn't die with the container

Any data written inside a container is lost when the container is removed. For a database, this is a disaster. A named volume (db_data in the example above) keeps data outside the container's lifecycle. The same logic applies to users' uploaded files; if the volume of files grows, keeping them on object storage instead of the local disk makes backups simpler and keeps server space free.

A point that's rarely mentioned: don't wipe volumes with docker compose down -v unless you deliberately want to rebuild everything from scratch. The -v flag also deletes the database data, and in a production environment that means losing all records.

Startup order and database migration

Even with service_healthy, database migrations must run before the application comes up. You have two options: a separate service that only runs the migration and then exits, or running the migration in the application's own entrypoint. The first approach is cleaner because if the migration fails, the application doesn't come up at all and you see the error sooner.

  migrate:
    image: myapp:1.4.2
    command: ["./manage.sh", "migrate"]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"

The value restart: "no" is intentional. This service should run once and be done. If you set unless-stopped, it keeps running over and over even after success.

When Compose isn't enough

Compose is the right choice for one server, a few services, and moderate load. It's simple, easy to debug, and doesn't need heavy orchestration. But it has one real limitation: it doesn't scale across multiple servers. If you need multiple nodes, load distribution across machines, and automatic container restart on a healthy node, Compose no longer works and you have to move toward Kubernetes. For small teams, this migration imposes a lot of maintenance cost prematurely; if you choose managed Kubernetes, only do so when you truly need multiple nodes.

For a single-server stack, my recommendation is clear: choose Compose and don't go near Kubernetes until the number of servers exceeds one. If you later need horizontal scaling, the service architecture stays the same and only the orchestration layer changes. To better understand the scaling path, the guide Autoscaling; horizontal or vertical? is a good starting point.

Running and checking stack health

After writing the file, validate first and then bring it up:

docker compose config
docker compose up -d
docker compose ps
docker compose logs -f web

The config command prints the file with variables substituted and shows syntax errors before deployment. If a password was substituted incorrectly, you see it here, not in the production log. For continuous service monitoring and alerts on outages, see the guide Server monitoring and smart alerting; Compose brings the service up, but monitoring tells you when it went down.

If you run the stack on a cloud server, choose resources correctly from the start. A database on NVMe disk makes a noticeable difference in query response time, and migrating data later becomes expensive. Cloud infrastructure (IaaS) from ServerNet lets you choose resources from the very beginning.

Frequently asked questions

Why don't containers come up after a server restart?

It's almost always because of a missing restart: unless-stopped on the services. By default, Docker doesn't re-run stopped containers after system boot. Add this line to every service that should always be running, then apply it once with docker compose up -d.

What's the difference between simple depends_on and condition: service_healthy?

Simple depends_on only determines the start order of containers and gives no guarantee about service readiness. With condition: service_healthy, Compose waits until the database healthcheck succeeds and then brings up the dependent service. For databases, always choose the second version.

Where should we keep secrets in Docker Compose?

In a .env file next to compose.yaml, with chmod 600 permissions and outside Git. In the Compose file, reference them only with ${VAR}. If a secret contains $, write it as $$ so Compose doesn't misinterpret it.

Is Compose suitable for production?

For a single-server stack with moderate load, yes, and it's a more sensible choice than Kubernetes. Its main limitation is horizontal scaling across multiple servers. As long as you're working on one machine, Compose is simpler, faster to debug, and cheaper to maintain.

Right now, open your compose.yaml file and see which service doesn't have restart. That one line is the difference between a site that comes back after a restart and a site that stays down until morning.

ServerNet Support

ServerNet engineering & editorial team — specialists in infrastructure, networking and web hosting.

Cloud Infrastructure (IaaS)
Share:

Comments 0

No comments yet — be the first!

Leave a comment

Related service

Cloud Infrastructure (IaaS)

Servers, private networks, firewalls and storage — all API-driven and billed hourly. Infrastructure as code that scales with you.