Docker Standard
Docker Compose governance — no hardcoded values, env from managers, healthcheck patterns, overlay pattern
Tags
Overview
Purpose
Docker Compose governance — no hardcoded values, env from managers, healthcheck patterns, overlay pattern
Rules
DCK-001: All docker-compose paths/ports via environment variables. NO hardcoded values in service definitions.
Hardcoded values couple compose files to a specific machine. Environment variables enable portability and registry-driven configuration.
Verification: Compose review: no literal paths or port numbers in service definitions.
DCK-002: Docker services must declare required env vars in comments at top of service definition.
Declared requirements are self-documenting. Missing env var errors become clear immediately, not after container startup failure.
Verification: Compose review: each service has a comment block listing required env vars.
DCK-003: Run validation before docker-compose up. Check .env exists and has required vars.
Validation before startup prevents cascading failures. One clear error beats three containers failing with cryptic messages.
Verification: Startup script includes .env validation step before docker-compose up.
DCK-004: External client services generated from templates via docker-manager.
Template generation ensures consistent service configuration. Manual compose files diverge over time.
Verification: Generated services match template output. No manual edits to generated files.
DCK-005: Use Docker Compose include: pattern for generated services. Requires Docker Compose 2.20+.
Include pattern keeps generated services in separate files, preventing merge conflicts with manually maintained compose files.
Verification: Compose files use include: for generated service definitions.
DCK-006: All environment variables sourced from managers: client-manager for paths, port-manager for ports.
Managers are the single source of truth. Bypassing them creates drift between registry and container configuration.
Verification: Env values in compose files reference manager outputs, not hardcoded values.
DCK-007: Health endpoints MUST support GET method. HEAD may return 405 (Chi router). Use wget -qO-, not --spider.
Chi router registers GET handlers only. HEAD requests return 405, causing healthcheck failures. wget -qO- uses GET.
Verification: Healthcheck commands use wget -qO- or curl, not wget --spider.
DCK-008: Use 127.0.0.1 in healthchecks, NEVER localhost. Alpine resolves localhost to IPv6 first, causing failures.
Alpine Linux DNS resolution tries IPv6 (::1) before IPv4. Services bound to 0.0.0.0 don't listen on ::1, causing healthcheck timeout.
Verification: Healthcheck URLs use 127.0.0.1, not localhost.
DCK-009: VITE_* variables are compile-time. Set via ARG BEFORE build command, not in docker-compose environment.
Vite inlines VITE_* at build time. Setting them in docker-compose environment has no effect on the built bundle.
Verification: Dockerfile: ARG VITE_* declared before RUN build command.
DCK-010: Services MUST bind to 0.0.0.0 to accept Docker network connections. Never bind to localhost/127.0.0.1.
localhost binding only accepts connections from within the container. Docker network communication requires 0.0.0.0 binding.
Verification: Service startup: listen address is 0.0.0.0, not 127.0.0.1 or localhost.
DCK-011: Inter-container communication uses service names (http://sbx-api:5100), never localhost.
Docker Compose DNS resolves service names to container IPs. localhost inside a container refers to that container only.
Verification: Code review: inter-service URLs use compose service names, not localhost.
DCK-012: Use docker-compose.yml + docker-compose.{dev,prod}.yml overlay pattern. Never mix environments in one file.
Overlay pattern enables environment-specific overrides without duplication. Mixing environments creates configuration that's wrong everywhere.
Verification: Compose structure: base + environment overlay files. No environment-specific values in base.