Docker Compose Validator

How to Use This Docker Compose Validator

1. Paste your docker-compose.yml content into the editor on the left. You can also click one of the example buttons to load a sample file.
2. Click Validate to run the analysis. The tool first checks for valid YAML syntax, then inspects the Docker Compose schema.
3. Review the results panel on the right. Each issue includes a severity level, description, approximate line number, and a fix suggestion.
4. Correct the flagged issues in your local file and re-validate until the file passes all checks.

What Is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. Instead of running multiple docker run commands with complex flags, you describe your entire application stack in a single YAML file — typically named docker-compose.yml or compose.yml. A single docker compose up command then creates and starts all the services, networks, and volumes defined in that file.

Docker Compose is the standard approach for local development environments, CI/CD pipelines, and small-to-medium production deployments. It supports service dependencies, health checks, resource limits, network isolation, persistent volumes, environment variable injection, and build configurations. For orchestration at larger scale, teams typically graduate to Kubernetes or Docker Swarm, but Compose remains the go-to for development and single-host deployments.

Docker Compose File Structure

A Compose file is organized around several top-level keys. The most important is services, which defines each container in your application. Other top-level keys include:

• services — The core section. Each key under services is a service name, and its value is the service configuration (image, ports, volumes, environment, etc.).
• networks — Custom networks for inter-service communication. By default, Compose creates a single network for all services.
• volumes — Named volumes for persistent data storage. Without declared volumes, data is lost when containers are removed.
• configs and secrets — For managing configuration files and sensitive data like passwords and API keys.
• name — Sets a custom project name instead of using the directory name.

Each service must define either an image (to pull from a registry) or a build context (to build from a Dockerfile). Everything else — ports, volumes, environment variables, dependencies — is optional but commonly used.

Common Docker Compose Errors

These are the most frequent mistakes developers encounter when writing Compose files:

• YAML indentation errors — YAML is whitespace-sensitive. Mixing tabs and spaces, or using inconsistent indentation levels, causes parse failures. Always use spaces (typically 2) and never tabs.
• Missing image or build — Every service needs one of these. Without either, Compose does not know what container to run.
• Invalid port mappings — Port numbers must be between 1 and 65535. The format is HOST:CONTAINER. Quoting port strings (e.g., "8080:80") avoids YAML interpreting them as sexagesimal numbers.
• Undeclared volumes or networks — If a service references a named volume or custom network, it must be declared in the top-level volumes or networks section.
• Circular dependencies — Service A depending on Service B which depends on Service A creates an unresolvable cycle.
• Invalid restart policies — Only no, always, on-failure, and unless-stopped are valid. A common mistake is writing on_failure (underscore) instead of on-failure (hyphen).
• Healthcheck without test — Defining a healthcheck section without a test command means the health status is never evaluated.
• Duplicate container names — Two services cannot share the same container_name value, as Docker requires unique container names on a host.

Docker Compose Best Practices

• Always set a restart policy for production services. unless-stopped is the most common choice, ensuring containers restart after crashes or host reboots but stay stopped if manually halted.
• Use healthchecks with depends_on conditions. Instead of just depends_on: [db], use the long syntax with condition: service_healthy so your application waits until the database is actually ready, not just started.
• Pin image tags to specific versions (e.g., postgres:16-alpine) rather than latest. This ensures reproducible deployments and prevents surprise breaking changes.
• Use named volumes for database data and other persistent storage. Bind mounts (./data:/var/lib/data) are convenient for development but named volumes offer better performance and portability.
• Never put secrets directly in environment variables within the Compose file. Use Docker secrets, env_file, or a .env file (excluded from version control) instead.
• Avoid privileged mode unless absolutely necessary. Use specific Linux capabilities via cap_add to grant only the permissions a container needs.
• Remove the version field. Docker Compose v2 ignores it and infers the schema automatically. Keeping it can cause confusion about which features are available.
• Quote port mappings as strings (e.g., "3000:3000") to prevent YAML from misinterpreting numbers containing colons.

Docker Compose v1 vs v2

Docker Compose v1 was a standalone Python application invoked as docker-compose (with a hyphen). It required a version field in the YAML file to determine which features were available. Docker Compose v2 is a Go-based plugin integrated directly into the Docker CLI, invoked as docker compose (with a space). It drops the version field requirement and supports all features regardless. V1 reached end-of-life in June 2023 — all new projects should use v2.

Related Tools

Convert between JSON and YAML with the JSON-YAML Converter. Format TOML configuration files with the TOML Formatter. Compare configuration file versions with the Diff Checker. Audit environment variable files with the .env Diff Tool. Generate TypeScript types from JSON with the JSON to TypeScript Generator.