Docker Compose Conventions

dockerdevopsinfrastructure

Conventions for writing maintainable, reproducible Docker Compose configurations for local development and staging environments.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Docker Compose Conventions ## File Organization - Use `docker-compose.yml` as the base configuration. Use `docker-compose.override.yml` for local dev overrides (auto-merged by Compose). - Add `docker-compose.prod.yml` for production-specific overrides; apply with `-f docker-compose.yml -f docker-compose.prod.yml`. - Never commit secrets in any Compose file — use `env_file: .env` and gitignore `.env`. - Provide a `.env.example` with all required variable names and safe placeholder values. ## Service Naming - Use lowercase `kebab-case` for service names: `api-server`, `postgres-db`, `redis-cache`. - Match service names to their roles, not implementation details: `db` not `postgres14`. - Use consistent naming across environments — the same logical service always has the same name. ## Image & Build - Pin image versions explicitly: `postgres:16.2-alpine`, never `postgres:latest`. - Use multi-stage Dockerfiles. Reference the correct stage in `build.target`. - Set `build.context` and `build.dockerfile` explicitly, even when using defaults. - Prefer Alpine-based images to minimize attack surface and image size. ## Ports - Expose only necessary ports. Internal service-to-service communication uses Docker network — no need to expose. - Format: `"HOST:CONTAINER"` with explicit host binding: `"127.0.0.1:5432:5432"` — never `"5432:5432"` (binds to 0.0.0.0). - Document every exposed port with a comment explaining its purpose. ## Volumes - Use named volumes for persistent data: `postgres-data:`, `redis-data:`. Declare them in the top-level `volumes:` section. - Use bind mounts for local development code sync: `./src:/app/src:ro` — use `:ro` (read-only) when the container should not write. - Never use anonymous volumes for important data — they are hard to identify and manage. - Exclude `node_modules` / `.venv` from bind mounts using anonymous volume overlay: `- /app/node_modules`. ## Networking - Define explicit networks. Do not rely on the default network for multi-service projects. - Use bridge networks for most cases. Name networks descriptively: `backend-net`, `frontend-net`. - Use `internal: true` for networks that should not have external access (e.g., DB network). - Services that don't need to communicate should not share a network. ## Health Checks - Define `healthcheck` for every stateful service (databases, caches, message queues). - Use `depends_on` with `condition: service_healthy` to sequence service startup correctly. - Example for Postgres: `test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]`. - Set reasonable intervals and retries: `interval: 10s`, `timeout: 5s`, `retries: 5`. ## Resource Limits - Set `deploy.resources.limits` for memory and CPU in production Compose files to prevent runaway containers. - Example: `memory: 512m`, `cpus: '0.5'`. ## Environment Variables - Prefer `env_file` over inline `environment:` for more than 3 variables. - Use `environment:` for service-specific, non-secret config that varies per environment. - Never hardcode credentials inline: `POSTGRES_PASSWORD: secret` in a committed file is a security violation. ## Logging - Configure `logging.driver` and `logging.options` explicitly. Use `json-file` with `max-size: 10m` and `max-file: 3` to prevent log files from filling disk. ## Anti-Patterns - Do not use `privileged: true` unless absolutely necessary and documented with justification. - Do not use `network_mode: host` in production. - Do not run application containers as root — set `user:` to a non-root UID. - Do not use `restart: always` without a health check — a broken container will restart forever.

CLI

npx mindaxis apply docker-compose-rules --target cursor --scope project

Используется в паках

Multi-Cloud Deployment

Deploy anywhere — AWS, Azure, GCP, and beyond

Открыть пак →

Incident & SRE Toolkit

On-call readiness: monitoring, alerting, chaos engineering, and incident response

Открыть пак →

← Правила

Docker Compose Conventions

dockerdevopsinfrastructure

Conventions for writing maintainable, reproducible Docker Compose configurations for local development and staging environments.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

CLI

npx mindaxis apply docker-compose-rules --target cursor --scope project

Используется в паках

Multi-Cloud Deployment

Deploy anywhere — AWS, Azure, GCP, and beyond

Открыть пак →

Incident & SRE Toolkit

On-call readiness: monitoring, alerting, chaos engineering, and incident response

Открыть пак →