docker-compose

# Docker Compose — 多容器编排与 Compose 文件 Expert guidance for writing production-grade Docker Compose configurations. ## When to Use **ALWAYS use this skill when the user mentions:** - "docker compose", "docker-compose.yml", "compose 文件" - "compose 怎么写", "compose 配置" - "多容器", "multi-container", "服务编排" - "depends_on", "profiles", "override" - "compose network", "compose volume" ## Complete File Structure ```yaml # compose.yml name: myapp services: # Container definitions networks: # Network topology volumes: # Persistent storage secrets: # Sensitive data (Swarm) configs: # Non-sensitive configs (Swarm) ``` ## Services — Core Configuration ```yaml services: web: image: myapp:${TAG:-latest} # Pull from registry # build: . # Or build from Dockerfile # build: # Build with options # context: . # dockerfile: Dockerfile.prod container_name: myapp-web # Explicit name (optional) hostname: web ports: - "8080:8080" # host:container - "127.0.0.1:8443:443" # bind to localhost - "8080:8080/udp" # UDP environment: - NODE_ENV=production - DB_HOST=db # Service name = hostname! # env_file: .env.production # Load from file volumes: - app-logs:/var/log/app # Named volume - ./config:/etc/app:ro # Bind mount (read-only) - /tmp/app:/tmp # Bind mount (read-write) depends_on: db: condition: service_healthy # Wait for health check redis: condition: service_started healthcheck: test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"] interval: 30s timeout: 3s retries: 3 start_period: 10s restart: unless-stopped deploy: # Swarm-only replicas: 3 resources: limits: cpus: '0.5' memory: 512M profiles: # Optional service - debug ``` ## Networking ### Default Network (Auto-Created) ```yaml # Compose auto-creates a default bridge network. # All services can reach each other by service name. services: web: ports: ["8080:8080"] db: # No ports exposed externally — only accessible by 'web' ``` ### Custom Networks ```yaml networks: frontend: # Public-facing backend: internal: true # No external access services: web: networks: [frontend, backend] # In both networks db: networks: [backend] # Backend only (isolated) cache: networks: [backend] ``` ## Environment Variables ### Approaches | Method | Where | Best For | |--------|-------|----------| | `environment:` | In compose.yml | Simple, few vars | | `env_file:` | External `.env.prod` | Many vars, env-specific | | `.env` file | Project root (auto-loaded) | Default values, `$VARIABLE` substitution | ### .env File (Auto-Loaded) ```bash # .env — auto-loaded by docker compose TAG=v1.2.3 DB_PASSWORD=secret123 ``` ```yaml # compose.yml — uses ${TAG} and ${DB_PASSWORD} services: web: image: myapp:${TAG:-latest} db: environment: POSTGRES_PASSWORD: ${DB_PASSWORD} ``` ### env_file ```bash # .env.production DB_HOST=prod-db.example.com DB_PORT=5432 ``` ```yaml services: web: env_file: .env.production ``` ## Depends On — Service Order ```yaml services: db: image: postgres:16-alpine healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s retries: 5 web: depends_on: db: condition: service_healthy # Wait for DB to be ready redis: condition: service_started # Wait for Redis to start ``` ## Profiles — Optional Services ```yaml services: app: image: myapp debug-tools: image: nicolaka/netshoot command: sleep infinity profiles: [debug] # Only starts with --profile elasticsearch: image: elasticsearch:8.15.0 profiles: [analytics] # Only starts with --profile ``` ```bash docker compose --profile debug up # Starts app + debug-tools docker compose --profile analytics up # Starts app + elasticsearch ``` ## Multi-Environment with Override ``` compose.yml # Base configuration compose.override.yml # Local dev overrides (auto-applied) compose.prod.yml # Production overrides ``` ```bash # Local: compose.yml + compose.override.yml (auto) docker compose up -d # Production: explicit files docker compose -f compose.yml -f compose.prod.yml up -d ``` ## Migration to Kubernetes ```bash kompose convert -f compose.yml # Generates K8s YAML files kubectl apply -f . ``` ## Workflow — 推荐编排流程 Step 1: **规划服务**: 列出所有服务、端口、数据卷、环境变量 Step 2: **编写 compose.yml**: 定义 services/networks/volumes Step 3: **配置依赖**: depends_on + condition: service_healthy Step 4: **本地验证**: `docker compose up -d` → `docker compose ps` → `docker compose logs` Step 5: **生产部署**: 添加 resource limits、restart policy、日志轮转 → `docker compose -f compose.yml -f compose.prod.yml up -d` ## Gotchas — Common Pitfalls - **depends_on without healthcheck**: `depends_on` only waits for container START, not READY. → **Recovery**: Always add `condition: service_healthy` + `healthcheck:` block; use `docker compose ps` to verify health status. - **Port conflict**: Multiple services can't bind the same host port. → **Recovery**: Use different host ports or remove `ports:` for internal-only services (they communicate via service name). - **Bind mount paths**: Relative paths are resolved from the compose file location. → **Recovery**: Use `./config` not `config/`; verify with `docker compose config` to see resolved paths. - **`.env` file security**: `.env` files often contain secrets. → **Recovery**: Add `.env` to `.gitignore`; use Docker secrets for Swarm; use `.env.example` with placeholder values. - **`docker compose` vs `docker-compose`**: Modern syntax is `docker compose` (plugin). → **Recovery**: `docker-compose` (standalone binary) is deprecated; always use `docker compose` (with space). ## Boundary — 能力边界（适用与不适用场景） | 分类 | 场景 | 说明 | |------|------|------| | ✅ 能做 | 多容器应用编排 | services/networks/volumes/secrets/configs 完整定义 | | ✅ 能做 | 环境管理 | .env / env_file / override 文件策略 | | ✅ 能做 | 依赖控制 | depends_on + healthcheck + profiles | | ⚠️ 需条件 | 多主机部署 | 迁移到 Swarm（`docker stack deploy`）或 K8s | | ⚠️ 需条件 | 滚动更新/自动扩缩 | Compose 不支持，需 Swarm 或 K8s | | ❌ 超范围 | 编写 Dockerfile | 使用 `docker-dockerfile` | | ❌ 超范围 | K8s 部署 | 使用 `kompose convert` + K8s 技能 | | ❌ 超范围 | 云服务编排（Terraform） | IaaC 工具 | ## When NOT to Use This Skill | ❌ Skip | ✅ Use Instead | |---------|---------------| | Single-container apps | `docker-run` | | Writing Dockerfile | `docker-dockerfile` | | Kubernetes deployment | K8s manifests / Helm charts | | Docker basics | `docker-basics` | ## Security & Stability - Use `internal: true` for backend networks to prevent external access. - Never commit `.env` files with secrets. Use CI secrets or Docker Swarm secrets. - Production Compose on single host: combine with systemd for auto-start on boot. - Multi-host production: migrate to Swarm (`docker stack deploy`) or Kubernetes. ## 📚 官方文档参考 | 文档 | 地址 | |------|------| | Docker Compose 概述 | https://docs.docker.com/compose/ | | Compose 文件参考 | https://docs.docker.com/reference/compose-file/ | | Compose CLI | https://docs.docker.com/reference/cli/docker/compose/ | | 环境变量 | https://docs.docker.com/compose/environment-variables/ | | Compose 网络 | https://docs.docker.com/compose/networking/ | | 生产环境 Compose | https://docs.docker.com/compose/production/ | ## 🧭 Docker Skills Journey > 📍 **You are here: `docker-compose` — 多容器编排** **← Previous**: `docker-buildx` / `docker-networking` **→ Next**: `docker-production` / `docker-cicd`