Docker Compose Linter Pro

Catch conflicting ports, missing health checks, security anti-patterns, and orphaned volumes in your docker-compose.yml before they become 3 AM incidents.

Free vs Pro

The free linter validates compose files against best practices and security basics. Pro adds production hardening: multi-file/override merging validation, resource-limit and healthcheck enforcement, secret-handling audits, dependency-order verification, and environment-parity checks between dev and prod compose files. Free validates — Pro hardens.

Upgrade Path

Free for local dev hygiene; Pro when the same compose files reach staging or production.

The Problem

Your docker-compose.yml has 12 services, 3 networks, and 8 volumes. It "works on my machine" but fails in CI with Bind for 0.0.0.0:5432:5432 failed: port is already allocated because two services bind the same host port. Another service runs as root with no resource limits, and the production compose file is missing health checks — so the load balancer routes traffic to services that haven't finished initializing. You've been fixing these issues ad-hoc for months, and each fix introduces a new subtle problem.

What You Get

• Comprehensive linting — validates YAML syntax, service configuration, dependency chains (circular dependency detection), port conflicts, network definitions, and volume mount paths in a single pass
• Security scanning — detects containers running as root, privileged mode, exposed ports on 0.0.0.0, hardcoded secrets in environment variables, missing read-only root filesystem, and deprecated field usage
• Production readiness scoring — validates health checks, restart policies, resource limits, logging drivers, network definitions, and volume drivers, producing a pass/fail per check
• Automated fixer — generates patches for missing health checks, resource limits, restart policies, user directives, and deprecated fields with --dry-run preview and --backup before applying
• JSON and Markdown output — structured reports for CI integration (JSON with exit codes) and team review (Markdown with severity-ranked findings)
• CI pipeline integration — pre-commit hooks and GitHub Actions steps that block compose files with errors or critical security findings

Why This Beats Prompting It Yourself

When you ask an agent to "review my docker-compose.yml," it checks syntax and maybe mentions a few missing fields. It doesn't detect port conflicts across services, doesn't flag privileged mode as a security issue, doesn't validate that health checks exist on all services, and doesn't generate the fix — it just describes what's wrong. The automated fixer with backup and dry-run modes means the agent doesn't just identify problems, it resolves them safely.

Example Session

You: Lint my production docker-compose.yml.

Agent: Lint Results: 2 errors, 4 warnings, 3 security findings. Errors:

• services.api.ports: Port 3000 conflicts with services.web.ports (both bind 0.0.0.0:3000)
• services.db.volumes: Mount path /var/lib/postgresql/data does not exist

Security:

• services.api: Running as root (no user directive) — add user: "1000:1000"
• services.api: Privileged mode enabled — remove unless required
• services.db: Hardcoded password in environment — use ${DB_PASSWORD} from .env

Production Readiness: 6/10 checks passed. Missing: health check on worker, resource limits on api, restart policy on scheduler, logging driver on all services.

Auto-fix available: python3 scripts/fixer.py fix --file docker-compose.yml --backup

Use Cases

• Linting a docker-compose.yml before deploying a new service to production
• Scoring a compose file for production readiness as part of a deployment checklist
• Auto-fixing common issues (missing health checks, restart policies, user directives) across a team's compose files
• Integrating compose validation into pre-commit hooks to prevent broken configurations from reaching CI
• Auditing a compose file for security anti-patterns before a security review

Known Limitations

Variable substitution (${VARIABLE}) is not fully resolved during linting — validate with actual .env files for complete checking. Multi-file compose configurations (docker-compose -f base.yml -f override.yml) must be linted separately or merged first with docker-compose config. Extension fields (x- prefixed) are valid YAML but may not be fully validated.

---

Tags: docker docker-compose devops linting security production-readiness containers

Version: 1.0.0