Docker Compose

The employees API needs a database. The frontend needs the API. Starting that by hand means three docker run commands with a network, a volume, published ports and a set of environment variables in the right order, typed correctly, every time. It works, and it lives in one person's shell history.

Compose replaces those commands with a file. You describe the services, the volumes and the networks you want; Compose works out what is missing and creates it. The file goes into version control next to the code, so the setup is reviewable, repeatable and the same for everyone who clones the repository.

One limit is worth stating before the example, because it prevents a familiar argument. Compose runs containers on one machine. It is a strong fit for development, for automated tests in a pipeline, and for small single-host deployments. It does not schedule work across several machines, it does not replace a failed host, and its update behaviour is basic. That work belongs to an orchestrator such as Kubernetes.

name: employees

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: employees
      POSTGRES_USER: api_user
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - employees-db-data:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"

  api:
    build:
      context: ./api
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      ASPNETCORE_HTTP_PORTS: "8080"
      ConnectionStrings__Employees: Host=db;Port=5432;Database=employees;Username=api_user;Password=${POSTGRES_PASSWORD}
    ports:
      - "8080:8080"
    depends_on:
      - db

  web:
    build:
      context: ./web
    environment:
      # Rendering on the server happens inside this container
      API_BASE_URL: http://api:8080
      # This one is read by the browser, which is not on this network
      NEXT_PUBLIC_API_BASE_URL: http://localhost:8080
    ports:
      - "3000:3000"
    depends_on:
      - api

volumes:
  employees-db-data:

• name sets the project name. Compose prefixes the containers, the network and the volumes with it, so two projects on one machine do not collide. Leave it out and the directory name is used, which is fine until someone renames the folder.
• There is no version: line at the top. Older Compose file formats required one and current Compose ignores it — if you meet one in an existing file, it is doing nothing.
• image: runs a published image. build: points at a directory containing a Dockerfile and Compose builds it. A service uses one or the other.
• The database publishes to 127.0.0.1 only, so a database client on this machine can connect and the surrounding network cannot. The API does not need the published port at all.
• Host=db in the connection string is the service name. Compose puts every service on one network and resolves those names, which is the mechanism from the Networks lesson, set up for you.
• employees-db-data is declared at the bottom and mounted where PostgreSQL stores its data. It is a named volume, so it outlives every container in this file.
• The frontend needs two addresses for one API, and this catches people. Code running inside the web container reaches http://api:8080. Code running in the browser cannot resolve api at all, because the browser is on your machine rather than on the Compose network, so it needs the published address.
• depends_on fixes the start order and nothing else. Read the callout below before relying on it.

Everything in the file is scoped to the project. A project named employees produces containers called employees-db-1, employees-api-1 and employees-web-1, a network called employees_default, and a volume called employees_employees-db-data. Two checkouts with different project names run side by side without interfering, which is how you keep a feature branch's database away from your main one.

Because every service is on that default network, no addresses appear anywhere in the configuration. The API connects to db, the frontend's server-side code connects to api, and Compose resolves both. Published ports are a separate path that exists only for traffic from your machine.

Compose also compares the file with what is already running. Change one service's configuration and run up again: that container is replaced, the others are left alone. The comparison is on configuration, not on source code, which matters for the services Compose builds.

# Build what needs building, create the network and volume, start everything
docker compose up -d

# What the project is running, and on which ports
docker compose ps

# Logs for one service, followed
docker compose logs -f api

# Every service interleaved, which shows the order things happened in
docker compose logs

# A shell in a running service, addressed by service name
docker compose exec api sh

# Rebuild the API image after a code change and replace only that container
docker compose up -d --build api

# Stop and remove the containers and the network. Named volumes are kept
docker compose down

# The same, and delete this project's named volumes. The database goes with them
docker compose down -v

• up -d creates whatever is missing and starts it in the background. Without -d your terminal stays attached to the interleaved logs and Ctrl+C stops the project, which is a reasonable way to work while you are editing the file.
• Commands take service names rather than container names, so they keep working after a container is recreated with a new numbered name.
• logs for one service is the narrow question; logs for all of them is how you see that the API tried to connect before the database had finished starting.
• --build is needed after a source change, because Compose reuses the image it built earlier. A code change that appears to do nothing is usually a missing --build.
• down removes the containers and the project network, and deliberately leaves named volumes in place. Running up -d afterwards gives you a clean set of containers with the same data.
• down -v adds the volumes to that list. Read the warning below before typing it.