docker compose — a container stack in one file

docker compose is the Docker plugin for a stack of several containers. Services, their images, ports, volumes, variables and start order live in one compose.yaml file. docker compose up -d creates the network, volumes and containers from it; down removes them. Everything compose does can be done by hand with docker commands — the file saves you long docker run lines and keeping the start order in your head.

The lab machine has Docker Compose 2.40, written with a space: docker compose. The old hyphenated docker-compose program is not installed. Like other Docker commands, compose goes through sudo.

Compose looks for compose.yaml (or docker-compose.yml) in the current directory. Another file — -f stack.yaml.

The compose.yaml file

A stack of two services: backend serves a page from a volume, proxy is nginx in front of it and the only one with a port to the outside.

services:
  backend:
    image: busybox
    command:
      - sh
      - -c
      - >-
        echo "<h1>$$GREETING</h1>" > /www/index.html &&
        exec httpd -f -p 8000 -h /www
    environment:
      GREETING: ${GREETING:-hello}
    volumes:
      - data:/www
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null",
             "http://127.0.0.1:8000/"]
      interval: 5s
      timeout: 3s
      retries: 3
  proxy:
    image: nginx:alpine
    ports:
      - "8090:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      backend:
        condition: service_healthy
    restart: unless-stopped
volumes:
  data:

Next to it lies nginx.conf with proxy_pass http://backend:8000; — nginx reaches its neighbour by service name.

The top-level volumes key declares named volumes, networks extra networks. The syntax is YAML: indent with spaces, tabs are not allowed. Quote ports: "8090:80".

A volume created beforehand (docker volume create keep) is attached as external — compose neither creates nor removes it:

volumes:
  data:
    external: true
    name: keep

If the external volume is missing, up fails: external volume "keep" not found. Without external: true compose creates its own empty <project>_data volume, even if keep with data sits right there.

Without a networks key all project services share one network. Your own networks are declared under top-level networks: and listed per service: networks: [front, back]. A service name is visible only on shared networks: web on front cannot find db on back (server can't find db), while app, attached to both, sees both.

Project: names of containers, network and volumes

The file describes a project. The project name is the name of the directory holding compose.yaml; everything compose creates is named after it:

student@ubuntu:~/stack$ sudo docker compose up -d
 Network stack_default  Created
 Volume stack_data  Created
 Container stack-backend-1  Created
 Container stack-proxy-1  Created
 Container stack-backend-1  Started
 Container stack-backend-1  Waiting
 Container stack-backend-1  Healthy
 Container stack-proxy-1  Started

All project services share one network, and each is visible to the others by its service name:

student@ubuntu:~/stack$ sudo docker compose exec proxy nslookup backend
Server:         127.0.0.11
…
Name:   backend
Address: 172.18.0.2

Compose commands address services by their names from the file: logs backend, exec proxy, restart proxy. Run them from the project directory — or with -f and -p.

Variables

Compose substitutes ${GREETING:-hello} itself, before any container starts: the environment variable's value, or hello if it is unset. Variables come from a .env file next to compose.yaml:

student@ubuntu:~/stack$ echo GREETING=privet > .env
student@ubuntu:~/stack$ sudo docker compose up -d
 Container stack-backend-1  Recreate
 Container stack-backend-1  Recreated
 Container stack-proxy-1  Running
…
student@ubuntu:~/stack$ curl -s localhost:8090/
<h1>privet</h1>

up -d re-created only backend: its environment changed. proxy did not change and kept running.

A shell variable in front of sudo never reaches compose: sudo clears the environment, so GREETING=privet sudo docker compose up -d changes nothing. Put the value in .env.

$$ is a literal dollar sign: compose leaves $$GREETING in command alone, and the shell inside the container expands it. docker compose config shows the result of substitution.

Start order and healthcheck

depends_on: [backend] only sets the order: proxy starts once the backend container is running, whether it is ready to answer or not. condition: service_healthy waits for readiness — compose waits for the healthy status from the backend healthcheck.

healthcheck.test is a command inside the container: code 0 means healthy. Docker runs it every interval, waits at most timeout, and after retries failures in a row marks it unhealthy. The status shows in ps:

student@ubuntu:~/stack$ sudo docker compose ps
NAME              …   SERVICE   …   STATUS
stack-backend-1   …   backend   …   Up 6 seconds (healthy)
stack-proxy-1     …   proxy     …   Up Less than a second

The PORTS column of proxy shows 0.0.0.0:8090->80/tcp, [::]:8090->80/tcp.

The check command must exist in the image: busybox and alpine have wget but no curl.

Stack commands

Only up -d applies a compose.yaml or .env edit. restart restarts the process in the old container: it re-reads files from the host, but the variables stay as they were.

student@ubuntu:~/nets$ echo GREETING=privet > .env
student@ubuntu:~/nets$ sudo docker compose restart app
student@ubuntu:~/nets$ sudo docker compose exec app env | grep GREETING
GREETING=hello
student@ubuntu:~/nets$ sudo docker compose up -d
 Container nets-app-1  Recreate
…
student@ubuntu:~/nets$ sudo docker compose exec app env | grep GREETING
GREETING=privet

• docker — containers, volumes, networks and inspect without compose.
• container-images — where service images come from.
• dockerfile — building your own image for build:.
• env-vars — environment variables in services.
• nginx — a proxy in front of the stack's services.
• curl — checking the stack's answer from the host.
• jq — parsing ps --format json.