Docker Compose Validator
Validate docker-compose.yml structure, services, and depends_on before deploy. Free Docker Compose validate check in the browser.
Docker Compose validator for compose file checks
A Docker Compose validator checks docker-compose.yml structure before you run docker compose up or merge a platform PR. Search intent for "docker compose validate" and "validate compose file" is about catching service, network, volume, and depends_on mistakes that plain YAML parsers miss.
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. Use the browser tool for quick PR review; keep the CLI config command as the merge-aware gate.
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.
Common pitfalls: mixing Compose specification versions without checking field support; referencing secrets or configs that only exist on one machine; and assuming build: context paths are relative to the shell cwd instead of the compose file location. Failures often show up only on CI runners with a different working directory.
When should you validate Compose in the browser? During onboarding, reviewing platform pull requests, or triaging why a stack fails on CI before you install Docker locally. Local linting keeps internal registry URLs and credentials off external validators. DevPipe processes the file in your tab.
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.