Validating a Docker Compose file before starting or deploying it helps catch malformed YAML, unresolved variables, missing services, invalid references, and unsafe configuration early. This reusable checklist shows how to inspect the rendered configuration, review service relationships, test ports and storage assumptions, verify health checks, and protect secrets before a Compose change reaches a shared environment.
Overview
A Compose file can be valid YAML and still fail when Docker interprets it. For example, a variable may be absent, a service may refer to a network that does not exist, or a host port may already be occupied. Validation is therefore more than checking indentation: it is a layered review of syntax, interpolation, resources, runtime behavior, and operational intent.
Use the Docker Compose CLI from the directory containing your Compose file. The first pass should render the configuration that Compose will use:
docker compose config
To check the configuration without printing the full result, use:
docker compose config --quiet
A successful command does not prove that every container will become healthy, but it is a strong first gate. The rendered output is especially useful during code review because it exposes merged files, interpolated values, profiles, networks, volumes, and service settings that may not be obvious in the source YAML.
Keep the Compose specification and the CLI version used by your team in mind. Supported fields and behavior can change, so treat warnings about obsolete or unsupported options as review items rather than harmless noise. For related infrastructure review practices, see this Terraform plan review checklist.
Checklist by scenario
Before starting a local stack
- Check YAML structure. Confirm that indentation is consistent, mappings and lists are correctly formed, and quoted values are used where characters such as
:,#, or${...}could be interpreted unexpectedly. A YAML linter can identify syntax problems, but Compose validation should remain the authoritative application-level check. - Render the file. Run
docker compose configand read the output. Look for an unexpectedly empty value, a service that disappeared because of a profile, or a path that resolves differently from what you intended. - Review variable sources. Check the shell environment, the project environment file, and any explicitly supplied
--env-file. Do not assume that a variable used for substitution is the same as a variable passed into a container. Confirm that required values are present and that defaults are deliberate. - Check image and build settings. Verify image names and tags, build contexts, Dockerfiles, build arguments, and target stages. A valid reference can still point to an image or build target that is unavailable to the current machine.
- Inspect published ports. Compare host ports with other local projects and running containers. Prefer binding development-only services to a deliberate interface and port rather than exposing every service unnecessarily.
When adding or changing services
- Map dependencies. For each
depends_onrelationship, ask whether startup order is actually sufficient. A dependency may be running before it is ready to accept connections. Where appropriate, add a health check and make the application retry connection failures. - Review service names and internal addresses. Containers on the same Compose network normally communicate using service names, not host-published ports. Check that connection strings use the correct hostname, port, protocol, and credentials.
- Check profiles. Make sure optional services are enabled in the scenario being tested. A file can validate successfully while a database, worker, or debugging service remains excluded by profile selection.
- Confirm resource assumptions. Review CPU and memory limits where used, restart policies, read-only settings, user identities, and filesystem permissions. These settings may behave differently across local Docker, CI runners, and production platforms.
Before a deployment or pull request
- Validate the exact file set. If the deployment combines multiple files, run validation with the same files and order used by the deployment process, for example
docker compose -f compose.yml -f compose.production.yml config. - Compare the rendered diff. Inspect changes to images, commands, environment values, mounts, ports, networks, and privileges. Reviewing only the source fragment can hide overrides from another file.
- Check external resources. Mark networks, volumes, or other resources as external only when the target environment creates and manages them separately. Confirm their names and existence outside Compose.
- Run a controlled startup. After static validation, start the relevant services and inspect logs, status, and health. A useful sequence is
docker compose up -d, followed bydocker compose psanddocker compose logs --tail=100. - Test the application path. Exercise the endpoint, queue, database migration, or worker action that matters. Configuration validation cannot confirm that an application is listening on the expected route or accepting the expected schema.
What to double-check
Environment variables and secrets
Separate configuration from credentials. Environment substitution is convenient, but it can place a secret into rendered output, process metadata, logs, or a committed file. Do not paste rendered Compose output containing credentials into an issue or pull request. Check that secret files are excluded from version control and that production credentials are supplied through the environment's approved secret mechanism.
Also distinguish an unset variable from an intentionally empty one. If a value is required, use a validation step or a shell/CI check that fails clearly when it is missing. A container starting with a blank password, hostname, or signing key can create a harder-to-diagnose failure later.
Networks, volumes, and data
Review whether each volume is meant to persist data or merely share source code. Confirm mount paths, read-only flags, ownership, and the consequences of removing the project. Named volumes can outlive containers, while bind mounts depend on host paths and permissions. For production-like data, document backup and migration expectations separately from the Compose file.
For networks, verify aliases and isolation boundaries. A service that needs to reach a database does not necessarily need access to every network used by the stack.
Health and shutdown behavior
A health check should test useful readiness, not merely whether a process exists. Use the right command, interval, timeout, and retry assumptions for the service. Check that dependent applications handle temporary unavailability and that shutdown signals allow workers and databases to close cleanly.
For broader API failure diagnosis after the stack is running, use the HTTP status code troubleshooting matrix and the webhook debugging guide.
Common mistakes
| Symptom | Likely cause | Useful check |
|---|---|---|
| Compose rejects the file immediately | Invalid YAML, wrong indentation, or an unsupported field | Run docker compose config and a YAML linter; read the first reported location |
| A value is blank in the rendered output | Variable is not defined in the expected environment or file | Inspect variable sources and add an explicit required-value check |
| Container starts but cannot reach another service | Wrong hostname, network, port, or startup assumption | Check service names, shared networks, health status, and application retries |
| Port binding fails | Another process or container already uses the host port | List active containers and host listeners; change the host-side port if appropriate |
| Data disappears after recreation | Data was stored in a container layer or an unintended bind mount | Inspect volume declarations and mount destinations before removing containers |
| Configuration works locally but not in CI | Different working directory, environment variables, profiles, platform, or Compose files | Validate the exact CI command and print non-sensitive environment assumptions |
Another common mistake is treating depends_on as a complete readiness mechanism. It can express an ordering relationship, but the application still needs a reliable health or retry strategy. Similarly, a green configuration check does not replace image vulnerability review, integration tests, access-control review, or deployment rollback planning.
When to revisit
Run this checklist whenever you add or remove a service, change a Compose file, environment file, image, port, volume, network, health check, or secret reference. Recheck it when upgrading Docker or Compose tooling, changing CI runners, moving between operating systems, or adapting a local stack for staging. It is also worth revisiting before seasonal planning cycles or any period when multiple teams will rely on the same development environment.
For a practical pull-request gate, make the following routine:
- Validate the exact Compose file combination with
docker compose config --quiet. - Review the rendered configuration without sharing sensitive values.
- Start the affected services in an isolated environment.
- Check container status, health, logs, ports, and mounted data.
- Exercise one representative application or integration path.
- Record any required external networks, volumes, variables, and secrets.
Keep the checklist beside the Compose files and update it when the workflow changes. For additional configuration-focused developer tools, the GitHub Actions validation guide and OpenAPI validation workflow provide similar layered review patterns.