Docker Compose Commands

Compose v2 is a Docker CLI plugin, so the command is docker compose with a space. The hyphenated docker-compose was v1, written in Python, and has been retired; if a tutorial still uses it, swap in the space. The file is compose.yaml by default (docker-compose.yml still works), and the old version: key at the top is obsolete and ignored.

Start and Stop

Run these from the directory that holds compose.yaml, or point at it with -f.

up -d is also how you apply changes: it compares the file against the running containers and recreates only the ones whose configuration changed. restart does not do that.

Status and Logs

Exec and Run

exec runs inside an existing container. run starts a new one from the service definition, which is the right tool for one-off jobs like migrations.

Without --rm, every run leaves a stopped container behind. docker compose ps -a shows them and docker compose rm clears them.

Build and Pull

Update a running stack to newer images:

docker compose pull
docker compose up -d

up -d recreates only the containers whose image changed. For services you build yourself, docker compose up -d --build does the same thing in one step. The Dockerfile generator is a quick way to get the build: side started.

Files, Projects and Profiles

compose.override.yaml is loaded automatically alongside compose.yaml when you do not pass -f, which is the usual way to keep dev-only ports and bind mounts out of the main file. The same flags can live in the environment: COMPOSE_FILE=compose.yaml:compose.prod.yaml, COMPOSE_PROFILES=debug, COMPOSE_PROJECT_NAME=myproject.

A .env file in the project directory is read automatically for ${VAR} substitution inside compose.yaml. It is not the same as env_file: on a service, which passes variables into the container.

Validate and Clean Up

Found orphan containers on up is a warning, not an error: a service was renamed or removed from the file and its old container is still around. --remove-orphans on up or down clears it.

compose.yaml Keys

The keys you actually use, per service. Indentation is two spaces and matters.

Top-level volumes: and networks: declare the names the services refer to:

volumes:
  data:
networks:
  backend:

Services on the same project network reach each other by service name (db:5432), which is why DB_HOST=db works. Compose creates a default network per project, so you only need networks: when you want to split services up.

Example compose.yaml

A web app built from the local Dockerfile, a Postgres database with a healthcheck, and a named volume for its data:

services:
  web:
    build: .
    image: myapp:latest
    ports:
      - "8080:3000"
    env_file: .env
    environment:
      DB_HOST: db
      NODE_ENV: production
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

volumes:
  data:

${DB_PASSWORD:-changeme} reads DB_PASSWORD from the shell or the project .env file and falls back to changeme. The Docker Compose generator builds files like this for common stacks.

Healthcheck and depends_on

depends_on alone only orders startup: the db container starts first, but Postgres may still be initialising when web connects. A healthcheck plus condition: service_healthy makes Compose wait.

The check runs inside the container, so curl or pg_isready has to exist in that image. Alpine images often lack curl; wget -qO- http://localhost:3000/health usually works instead. docker compose ps shows (healthy) or (unhealthy) next to the state, and docker inspect -f '{{json .State.Health}}' container shows the last few results.

command vs entrypoint

The string form (command: npm start) is split on spaces by Compose without a shell, so quotes inside it are kept literally and && is passed as an argument. When in doubt, use the list form and name sh -c explicitly. A multi-line script can go under a folded block scalar:

    command: >
      sh -c "npm run migrate &&
             npm run seed &&
             npm start"

Gotchas

• docker compose restart does not read the file again. After editing compose.yaml, run docker compose up -d; it recreates only what changed.
• down -v deletes every named volume declared in the file, including the database. down alone keeps them.
• depends_on without a condition only orders container starts. Add a healthcheck and condition: service_healthy when the app crashes on boot because the database is not ready.
• Ports in YAML must be quoted ("8080:80"); 22:22 unquoted is parsed as a base-60 number by some YAML parsers and becomes garbage.
• .env in the project directory feeds ${VAR} substitution in the file. env_file: feeds the container. They are different files with different jobs, and a variable in .env does not reach the container unless you also pass it through environment: or env_file:.
• Services started with --profile need the same --profile on down, or their containers are left running.
• Error response from daemon: ... port is already allocated on up means another container, or a process on the host, holds that port. docker ps and ss -tlnp find it; see Error response from daemon for the other variants.
• Bare docker commands work on Compose containers too: docker logs myproject-web-1, docker exec -it myproject-web-1 sh. The docker commands sheet covers them.