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.