SpunkArt
Command line and project setup

How to write a Docker Compose file

Docker Compose describes several containers in one YAML file and starts them together with one command. This page walks through a small web app with a database, key by key, and lists the mistakes that cause most first-run errors.

What Compose is for

Running one container is a single docker run command. Running an app, its database and a cache means three long commands, a shared network and the right start order. Compose writes that down. You keep a file called compose.yaml (older projects use docker-compose.yml, which still works) and run docker compose up.

A working example

services:
  web:
    build: .
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - dbdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 10

volumes:
  dbdata:

Key by key

KeyWhat it means here
servicesEach child is one container definition: web and db
build: .Build an image from the Dockerfile in this folder
imageUse a published image and tag instead of building
ports"HOST:CONTAINER": your browser uses 8080, the app listens on 3000
environmentVariables passed into the container
volumesPersistent storage; dbdata survives container rebuilds
healthcheckA command Docker runs to decide whether the service is ready
depends_onStart order; with service_healthy, wait for the healthcheck

Notice the database host in DATABASE_URL is just db. Compose puts all services on one private network where each service name works as a host name. Inside that network the database is reached on its own port 5432; it is not published to your machine at all, which is a good default.

Keeping secrets out of the file

${DB_PASSWORD} is filled in from your shell or from a file named .env next to compose.yaml. Put the real value in .env, add that file to .gitignore, and commit a .env.example with placeholder values so others know what to set.

Day-to-day commands

docker compose up -d          # start everything in the background
docker compose ps             # what is running, and on which ports
docker compose logs -f web    # follow one service's output
docker compose exec db psql -U app   # open a shell tool inside a container
docker compose down           # stop and remove containers (volumes stay)
docker compose down -v        # also delete named volumes: data is gone
docker compose config         # print the file after variables are filled in

Common mistakes

  • Using localhost between containers. Inside a container, localhost means that same container. Use the service name.
  • Swapping the port numbers. The left number is on your machine, the right one inside the container. "3000:8080" and "8080:3000" are different setups.
  • Expecting depends_on alone to wait for readiness. Without a healthcheck condition it only waits for the container to start, not for the database to accept connections.
  • Running down -v casually. It deletes the database volume. Back up first.
  • Tabs in YAML. Indent with spaces only.

Questions

Do I still need the version: line at the top?

No. Current Docker Compose ignores the top-level version key and prints a warning that it is obsolete. You can delete it.

Is Compose meant for production?

It suits single-host deployments and development well. Multi-machine setups usually move to an orchestrator, but the service definitions translate fairly directly.

How do I rebuild after changing the Dockerfile?

Run docker compose up -d --build. Without --build, Compose reuses the image it built before.