Docker Compose Linter

The Problem

Your docker-compose.yml works on your laptop. Then a database password gets committed to git because it was hardcoded in the environment: block. Your Postgres port 5432 is mapped to the host, so anyone on the network can connect. A container runs out of memory and kills your host because there are no deploy.resources.limits. A dependency service crashes on startup but the app container doesn't wait for it because depends_on without condition: service_healthy only waits for the container to start, not to be ready.

Docker Compose files are deceptively simple YAML that hide real security and reliability landmines. A 50-line compose file can have 14 different misconfiguration categories, and docker compose config only validates syntax — it won't tell you that privileged: true gives your container root access to the host kernel.

What You Get

• 14-point quality gate checklist — YAML syntax, deprecated version field, hardcoded secrets, privileged mode, exposed database ports, running as root, missing no-new-privileges, missing healthchecks, missing restart policies, missing resource limits, unpinned image tags, implicit network definitions, missing logging config, dangerous capabilities (cap_add: ALL)
• Security audit with severity levels — 🔴 CRITICAL for hardcoded secrets and privileged containers, 🟡 WARNING for missing healthchecks and unpinned images, ✅ PASS for verified configurations
• Secret pattern detection — flags env var names matching *(PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL)* with literal (non-variable) values
• Network architecture recommendations — flags missing explicit network definitions and suggests internal: true networks for database/internal services
• Ready-to-use lint script — bash script (scripts/lint-compose.sh) that runs all 7 checks in sequence with pass/fail/warn output for CI integration
• Tool integration guide — DCLint, yamllint, checkov, and docker compose config commands for deeper analysis

Why This Beats Prompting It Yourself

docker compose config validates that the YAML parses correctly and the compose schema is followed. It won't catch that your Postgres port is exposed to the host, that your Redis has no healthcheck, that your app container has no memory limit, or that a hardcoded password sits on line 14. The linter checks security, reliability, and operational best practices that the Docker CLI doesn't cover — 14 specific failure modes that real teams hit in production.

Example Session

You: "Lint this docker-compose.yml for security and reliability issues."

Agent:

=== Docker Compose Lint: docker-compose.yml ===

[1/7] Validating YAML syntax...                          ✅ PASS
[2/7] Checking deprecated     🟡 WARN: 'version: "3.8"' is
'version' field...            deprecated — remove it
────────────────────────────  ────────────────────────────
[3/7] Scanning for hardcoded  🔴 FAIL: POSTGRES_PASSWORD on
secrets...                    line 14
🔴 FAIL: REDIS_PASSWORD on
line 21
[4/7] Checking for            ✅ PASS
privileged containers...
[5/7] Checking for            🟡 WARN: No healthcheck for
healthchecks...               'web', 'worker'
[6/7] Checking for resource   🟡 WARN: No resource limits
limits...                     defined
[7/7] Checking image version  🟡 WARN: 'nginx:latest',
pinning...                    'node:lts' unpinned

=== Lint complete: 2 CRITICAL, 4 WARNING, 1 PASS ===

🔴 CRITICAL — Hardcoded secret: POSTGRES_PASSWORD on line 14
  → Move to env_file or Docker secret

🔴 CRITICAL — Hardcoded secret: REDIS_PASSWORD on line 21
  → Move to env_file or Docker secret

🟡 WARNING — Image 'nginx:latest' is unpinned
  → Pin to specific version (e.g., nginx:1.27.4-alpine)

🟡 WARNING — Missing healthcheck for services 'web', 'worker'
  → Add healthcheck with HTTP or TCP probe

Use Cases

• Pre-deployment security gate — run before docker compose up -d in production to catch secrets and misconfigurations
• PR review for compose changes — lint as part of code review when docker-compose.yml is modified
• New project setup — validate the initial compose file before the team starts building services on top of it
• CI/CD pipeline check — integrate the lint script to fail builds on CRITICAL findings
• Infrastructure audit — scan all compose files in a repo for accumulated misconfigurations

Known Limitations

The linter checks compose file contents, not the running containers themselves — runtime behavior like actual port exposure or resource consumption requires container-level monitoring tools. Some checks (like image pinning) depend on the image tag format and may produce false positives for images with unusual tagging schemes.

Upgrade Path

Free validates best practices on the laptop. Docker Compose Linter Pro ($5 one-time) hardens for production: override merging, port conflicts, production-readiness score, and an auto-fixer script for CI.

Upgrade when compose files leave the laptop:

https://www.agensi.io/skills/docker-compose-linter-pro