Docker Compose 备忘单

Docker Compose is a powerful tool for defining and running multi-container Docker applications. It uses a YAML file (compose.yaml) to configure application services, networks, volumes, and more. This file allows developers to declaratively describe infrastructure and dependencies, making it easier to manage complex environments.

Whether you’re building a local dev stack or deploying to production, Compose simplifies orchestration and keeps your configuration readable and version-controlled.

📁 File Name

compose.yaml 

✅ YAML Formatting Rules

• Use 2 spaces for indentation (not tabs)
• Keys and values are case-sensitive
• Lists use - for each item
• Strings with special characters should be quoted
• Environment variables can be defined inline or via .env files

🧱 Basic Structure

services: service_name: image: image_name:tag build: context: . dockerfile: Dockerfile ports: - "host_port:container_port" volumes: - ./host_path:/container_path environment: - VAR_NAME=value depends_on: - other_service networks: - custom_network networks: custom_network: driver: bridge volumes: custom_volume: 

⚙️ Services

Each service defines a container.

Common Service Options

services: web: image: nginx:latest build: context: ./app dockerfile: Dockerfile command: ["nginx", "-g", "daemon off;"] container_name: custom_name ports: - "8080:80" expose: - "80" environment: - DEBUG=true env_file: - .env volumes: - ./data:/data restart: always depends_on: - db networks: - frontend healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 30s timeout: 10s retries: 5 

🏗️ Build Options

build: context: ./dir dockerfile: Dockerfile args: build_arg: value target: build-stage 

• build: Tells Compose how to build the image.
  • context: is the directory containing the Dockerfile and source code.
  • dockerfile: lets you specify a custom Dockerfile name or path.

📦 Volumes

volumes: data_volume: driver: local driver_opts: type: none device: /path/on/host o: bind 

Mounting Volumes

volumes: - data_volume:/app/data - ./local:/container/path 

• volumes: Mounts host directories or named volumes into the container.
  • ./src:/app/src mounts the local src folder into the container at /app/src.

🌐 Networks

networks: frontend: driver: bridge backend: driver: overlay 

• networks: Connects the service to one or more custom networks. Enables service discovery and isolation.

Assigning Networks to Services

services: app: networks: - frontend - backend 

🌐 Ports

 ports: - "3000:3000" 

• ports: Maps container ports to host ports. Format is "host:container". Useful for exposing services to your local machine.

🔐 Secrets (Docker Swarm only)

secrets: db_password: file: ./db_password.txt services: db: secrets: - db_password 

🔑 Configs (Docker Swarm only)

configs: my_config: file: ./config.txt services: app: configs: - source: my_config target: /etc/config.txt 

🧪 Healthcheck

healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 30s timeout: 10s retries: 3 start_period: 5s 

• healthcheck: Defines how Docker checks if the container is healthy.
  • test: is the command to run
  • interval: how often to run the check
  • timeout: how long to wait for a response
  • retries: how many failures before marking unhealthy

🔄 Restart Policies

restart: no # Never restart restart: always # Always restart restart: on-failure # Restart on failure restart: unless-stopped 

🧬 Environment Variables

environment: - VAR1=value1 - VAR2=value2 env_file: - .env 

• environment: Sets environment variables inside the container. Useful for configuration.
• env_file: Loads environment variables from a file. Keeps secrets and config separate from the Compose file.

Command

 command: npm start 

• command: Overrides the default command defined in the Dockerfile. Useful for customizing container behavior.

Dependencies

 depends_on: - db 

• depends_on: Specifies service startup order. In Compose, this does not wait for the service to be “ready”—just started.

🧹 Clean Up

docker compose down # Stop and remove containers, networks, volumes docker compose down -v # Also remove named volumes 

🚀 Commands

🧠 Mounting GPU / iGPU

Docker Compose supports GPU access via the device_requests field (Compose v3.8+ and Docker 19.03+).

✅ NVIDIA GPU Example

services: gpu-app: image: nvidia/cuda:11.0-base deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] 

✅ Intel iGPU (via VAAPI or OpenCL)

services: igpu-app: image: intel/openvino devices: - /dev/dri:/dev/dri 

🔧 Make sure your host has the necessary drivers and runtime (e.g., NVIDIA Container Toolkit or Intel Media SDK).

🔄 Compose vs Swarm YAML Differences

🧠 Tip: Use compose.yaml for local development and stack.yml for Swarm deployments.

🧬 Profiles (Compose v3.9+)

Profiles allow conditional inclusion of services based on the active profile. This is useful for separating dev/test/staging environments.

✅ Defining Profiles

services: web: image: nginx profiles: - default debug: image: busybox command: top profiles: - debug 

✅ Activating Profiles

docker compose --profile debug up 

✅ Notes

• Services without a profiles key are always included.
• Multiple profiles can be activated simultaneously.
• Useful for feature toggles, optional services, or environment-specific setups.

⚔️ YAML Differences: Docker Compose vs Docker Swarm Mode

Docker Compose and Docker Swarm both use YAML files to define services, but they serve different purposes and support different features. Compose is optimized for local development and testing, while Swarm is designed for production-grade orchestration across clusters.

🧭 Purpose

🧩 Key Differences in YAML Structure

🔧 Compose-Only Features

These features are useful for local development but are ignored in Swarm:

build:

services: app: build: context: . dockerfile: Dockerfile 

• Compose builds images locally.
• Swarm requires pre-built images pushed to a registry.

restart:

restart: unless-stopped 

• Compose uses this to auto-restart containers.
• Swarm uses deploy.restart_policy instead.

depends_on:

depends_on: - db 

• Compose starts services in order.
• Swarm ignores this; use healthchecks and wait-for-it scripts.

🛡️ Swarm-Only Features

These features are exclusive to Swarm and ignored by Compose:

deploy:

services: app: deploy: replicas: 3 placement: constraints: - node.role == manager restart_policy: condition: on-failure 

• Controls scaling, placement, and restart behavior in a cluster.

configs: and secrets:

configs: app_config: file: ./config.yml secrets: db_password: file: ./password.txt 

• Used to securely distribute configuration and secrets across nodes.

placement: (inside deploy)

placement: constraints: - node.labels.env == production 

• Assigns services to specific nodes based on labels.

🧪 Healthchecks (Supported in Both)

healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 30s timeout: 10s retries: 3 

• Works in both Compose and Swarm.
• In Swarm, health status can influence service rescheduling.

📦 Volume Differences

Swarm requires external volumes to be pre-created on all nodes.

🧠 Summary

🧭 Tip: Use compose.yaml for development and stack.yml for Swarm. You can split your configuration into multiple files or use tools like kompose to convert Kubernetes manifests.

📚 Resources

• Compose File Reference
• Docker CLI Reference
• NVIDIA GPU Support
• Intel GPU Support