Docker compose

Docker Compose Skill

Docker Compose defines and runs multi-container applications from a single compose.yaml file. This skill covers authoring the file, operating the stack, and structuring configuration for development vs production, with a typical Drupal stack (php-fpm, nginx, MariaDB, Redis) as the working example.

---

compose.yaml essentials

• The canonical filename is compose.yaml (docker-compose.yml still works).
• Do not add a top-level version: key — it is obsolete and ignored by Compose v2; linters flag it.
• Services, networks, and volumes are declared at the top level.

Drupal stack example

services:
  php:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    volumes:
      - ./:/var/www/html
      - drupal-files:/var/www/html/web/sites/default/files
    environment:
      DRUPAL_DB_HOST: db
      DRUPAL_DB_NAME: drupal
      DRUPAL_DB_USER: drupal
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./:/var/www/html:ro
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php

  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: drupal
      MARIADB_USER: drupal
      MARIADB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:?set DB_ROOT_PASSWORD in .env}
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine

volumes:
  db-data:
  drupal-files:

Key points illustrated:

• depends_on with condition: service_healthy — Drupal installs and drush commands fail if the database container is running but not yet accepting connections. A healthcheck plus condition fixes the race.
• Secrets via ${VAR:?error} — fail fast when required variables are missing instead of starting with empty passwords.
• Named volume for sites/default/files — keeps user uploads out of the bind-mounted codebase.

---

Common commands

docker compose up -d              # start stack in background
docker compose up -d --build      # rebuild images first
docker compose down               # stop and remove containers (volumes kept)
docker compose down -v            # ALSO delete named volumes (destroys DB!)
docker compose ps                 # container status + health
docker compose logs -f php        # follow logs of one service
docker compose exec php bash      # shell into running container
docker compose exec php vendor/bin/drush cr   # run drush inside the stack
docker compose run --rm php composer install  # one-off command container
docker compose config             # render the final merged config (debug)
docker compose watch              # sync+rebuild on file changes (dev loop)

---

Dev vs prod configuration

Compose merges multiple files; later files override earlier ones. compose.override.yaml is loaded automatically for local development:

compose.yaml            # base — shared definition
compose.override.yaml   # dev only — bind mounts, xdebug, exposed ports
compose.prod.yaml       # prod — restart policies, no source bind mount

docker compose up -d                                   # base + override (dev)
docker compose -f compose.yaml -f compose.prod.yaml up -d   # prod set

Use profiles for optional services (e.g. Solr or Mailpit only when needed):

services:
  solr:
    image: solr:9
    profiles: ["search"]

docker compose --profile search up -d

---

Best practices

• Pin image tags (mariadb:11.4, not latest) so the stack is reproducible.
• One process per container; php-fpm and nginx are separate services.
• Put everything secret in .env (gitignored) and reference with ${VAR}.
• Add a healthcheck to every service another service depends on.
• For Drupal, mount the project root once and let nginx mount it read-only.
• Run docker compose config after edits — it validates and shows the merge result before anything starts.

---

Troubleshooting

Symptom	Fix
Drupal install fails with "connection refused" to DB	Add DB healthcheck + depends_on.condition: service_healthy
Changes to compose.yaml have no effect	docker compose up -d again (recreates changed services); check docker compose config
Port already allocated	Another stack uses the host port — change ports: mapping or docker compose down the other project
Permission errors on sites/default/files	Align container user UID with host (user: key) or fix volume ownership in entrypoint
Stale vendor/ after switching branches	docker compose run --rm php composer install
version is obsolete warning	Delete the top-level version: key
Database empty after restart	You ran down -v — named volumes were deleted; restore from backup