Docker Compose Validator
Validate docker-compose.yml structure and service definitions before deploy.
Validating Docker Compose files
Docker Compose describes multi-service stacks: images, ports, volumes, networks, and dependencies. Errors that pass YAML syntax may still fail at runtime when service names do not resolve, ports collide, or bind mounts point to missing host paths.
Validation catches structural problems early: undefined services in depends_on, incompatible compose file versions, and missing image or build contexts. It complements but does not replace running docker compose config in CI with your override files merged.
Environment-specific overrides belong in separate files gitignored from the repository. Validating the base file in review ensures defaults are sane; validate overrides in deployment pipelines where secrets and host paths exist.
Service names become DNS labels on the default network. A typo in depends_on means the dependent container starts before its database is defined, producing race errors that look intermittent. Explicit healthchecks with condition: service_healthy are preferable to depends_on alone when order matters.
Published ports map host ports to container ports. Multiple developers running the same compose file on one machine collide when postgres always binds 5432. Document alternate override files for local port shifts and validate each variant before onboarding new contributors.
Profiles and extends compose features split optional services across files. Lint each file individually, then validate the merged result with docker compose config because references across files are invisible when you inspect only the root docker-compose.yml.
Use compose validation when onboarding developers, reviewing platform pull requests, or triaging why a stack fails on CI runners. Local linting keeps internal registry URLs and credentials off external validators.
Real-world scenario
Smoke-testing a local Docker stack
A new docker-compose.yml adds api, worker, and postgres services. docker compose up fails on a laptop because depends_on references a typoed service name and port 5432 is already bound.
- 1
Lint the base compose file
Paste docker-compose.yml into the validator. Fix undefined services in depends_on and missing image or build keys before adding overrides.
- 2
Review published ports
Check for host port collisions with other local stacks. Map postgres to 5433:5432 if 5432 is taken on the developer machine.
- 3
Lint the Dockerfile
Switch to the Dockerfile linter for services using build:. Pin base image tags and confirm the USER is not root for the API container.
- 4
Inspect env files
Parse .env with env tools to confirm DATABASE_URL hostnames match the postgres service name on the default network.
- 5
Merge and config in CI
Run docker compose -f docker-compose.yml -f docker-compose.override.yml config in CI after local validation passes.
Part of the Validate a Docker stack workflow, which chains related DevPipe tools for the full task.
Reference Guide
Docker Compose files describe multi-container stacks. Validate structure before CI or production deploy.
| Check | Why it fails at runtime |
|---|---|
Unknown depends_on service | Compose rejects or ignores dependency |
Missing image or build | Service cannot start |
| Host port already bound | docker compose up fails on developer laptop |
| Bind mount path | Windows vs Linux path breaks CI |
Minimal valid pattern:
services:
api:
build: .
ports:
- "8080:8080"
depends_on:
- db
environment:
DATABASE_URL: postgres://db:5432/app
db:
image: postgres:16-alpinedepends_on vs healthcheck:
depends_onorders container start, not readiness.- Add
healthcheckon db and use Compose v2 condition syntax when the API must wait. - Published ports can conflict on shared CI runners; use overrides per environment.
- Keep secrets in
.envfiles gitignored from the repository.
Run docker compose config in CI after local lint for merged overrides.
Current mode
Operation: compose-validate
All processing runs locally in your browser. Paste input, click Run, and copy the result.
Example Input
services:
web:
image: nginx:alpine
ports:
- "8080:80"A sample loads automatically when you open this tool. Use Load Sample to reset it.