Does Docker Compose still need a version field?

No. The top-level version: field is obsolete in modern Compose. It is still accepted for backwards compatibility, but it has no effect on parsing or features — Compose v2 derives its capabilities from the installed engine. Including it can mislead readers into thinking the file targets a specific schema version. The validator flags it as Informational, not Critical, so legacy files still work.

What does depends_on actually guarantee?

Short-form depends_on only controls startup and shutdown ordering: Compose starts the target before the dependent service, and tears it down after. It does not wait for the target to be ready to accept connections. For readiness, use long-form depends_on with condition: service_healthy (pairs with a healthcheck on the target) or condition: service_completed_successfully (for one-shot containers like database migrators).

How do I make Compose wait for a database to be healthy?

Add a real healthcheck to the database service (for Postgres, test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER -d $POSTGRES_DB"]) and use long-form depends_on with condition: service_healthy on the dependent service. Compose will start the database, poll its healthcheck until it reports healthy, and only then start the dependent. This replaces the shell-retry-loop patterns people used to write around short-form depends_on.

Can two services publish the same host port?

Only if they bind to different host IPs or different protocols. On the same host IP + host port + protocol, only one owner is possible — the second container will fail to start with an address-already-in-use error. Host 0.0.0.0 is a wildcard and collides with any specific IP on the same port and protocol. This tool detects these collisions including port ranges (e.g. 3000-3005:3000-3005) and bracketed IPv6 bindings.

What causes a circular dependency in Compose?

Any cycle in the dependency graph. Compose derives startup order from multiple sources: depends_on, links, volumes_from, and network_mode: "service:…". A cycle involving any of those constructs blocks docker compose up. Break it by removing one edge — typically by introducing a message broker between the two sides, or by splitting a service that has taken on two roles.

Are services connected automatically on the default network?

By default, yes. If you do not declare any top-level networks and do not set a networks: list on services, Compose creates a single default network and attaches every service to it. Services resolve each other by service name via DNS. Declaring a custom networks: list on a service disables the implicit default network for that service, so make sure peers share at least one network.

Are links still recommended?

No. links: is a legacy compatibility feature from the original Docker networking model. On modern bridge networks, services on the same network already resolve each other by service name via Docker's internal DNS. links: adds little value and can complicate startup ordering. This tool flags it as a Recommendation (not a Critical failure) so existing files keep working, but prefer aliases: on the network attachment if you need alternate DNS names.

Can I export the service graph as an image?

Yes. Use the SVG or PNG export buttons in the graph toolbar. SVG is recommended for READMEs, wikis, and design docs because it scales cleanly; PNG is useful when the destination does not render SVG reliably (e.g. some chat tools or older CMSes). Both exports render on a white background so they work on both light and dark documentation themes.

Does this tool upload my Compose file anywhere?

No. The Compose file is parsed, validated, and visualized entirely in your browser in v1. Nothing is sent to a server, logged, or stored beyond your browser's local storage (used only to preserve your last input between reloads). This matters because Compose files can expose private image names, internal service names, ports, networks, registries, and secret references — even without raw credentials, that metadata can be sensitive.

Why is the docker compose CLI itself a better source of truth than text-matching?

The Compose CLI's docker compose config command is the canonical way to see how Compose will actually interpret your file, including environment interpolation, extends, and includes. This tool focuses on structural and semantic checks that are useful before you even run the CLI — especially for code review — but for deep questions about how a specific variable will be substituted in a specific environment, docker compose config remains the authoritative answer.

All tools

Docker Compose Validator & Service Graph

Catch host-port collisions, circular dependencies, readiness gaps, and outdated syntax — then see the architecture as an interactive service graph. Everything runs locally.

Compose file

Summary

3 services parsed.
2 dependencies ordered only by startup, not by health/readiness.
2 required environment variables need values.
All services share the default network.

critical0

warning4

recommend1

info0

depends_onShared networkVolume mountSecret mountConfig mountlinks (legacy)

Quick answers for the questions most Compose files run into

Short, practical answers you can apply directly to acompose.yamlfile. Every section below is based on the current Compose specification.

How do I visualize a Docker Compose file?

Parse the YAML into a Compose model (services, networks, volumes, secrets, configs), then render four overlapping but distinct relationships: startup dependencies (depends_on), shared-network reachability (service-name DNS across a network), resource attachment (named volumes, secrets, configs), and any legacy constructs (links, volumes_from, network_mode: service:…). Draw them with separate edge styles so a reader can instantly tell the difference between “A starts before B” and “A can talk to B” — those are not the same thing.

What does `depends_on` actually do?

The short-form depends_on: [db] controls startup and shutdown ordering only. Compose guarantees db is started before the dependent service, and torn down after it. It does not wait for the container to be ready to accept connections.

Readiness requires long-form depends_on with a condition:

service_started — same as short form
service_healthy — waits for the target's healthcheck to report healthy
service_completed_successfully — waits for a one-shot container (like a migrator) to exit cleanly

Compose also takes links, volumes_from, and network_mode: "service:…" into account when deriving startup order — which is why a cycle involving those constructs can also block docker compose up.

Compose error cheat sheet

Compose issue	Why it happens	What to do
Port collision	Two services publish the same host IP + host port + protocol. Docker allows only one owner per binding.	Change one host port, bind to a specific host IP, or remove the duplicate publish.
Circular dependency	A cycle across depends_on, links, volumes_from, or network_mode: service:… leaves Compose without a valid startup order.	Remove one edge: introduce a broker, move to healthcheck-gated depends_on on only one side, or split a service.
Startup without health readiness	Short-form depends_on only orders startup. The dependent service may run before the target is actually accepting connections.	Add a healthcheck to the target and use long-form depends_on with condition: service_healthy.
Undefined env variable	A ${VAR} is interpolated with no fallback. Compose silently substitutes an empty string, usually breaking connection strings and image tags.	Provide a value via .env, --env-file, shell export, or add a :- fallback. Use Compose secrets for sensitive values.
Obsolete version: field	Modern Compose ignores the top-level version:. It is accepted for backwards compatibility but misleads readers.	Delete the version: line. Compose v2 derives capabilities from the installed engine.
Legacy links:	links: is a legacy compatibility feature from the original Docker networking model. Modern bridge networks already resolve service names via DNS.	Remove links: and rely on service-name DNS across a shared network. Use aliases: on the network attachment for alternate names.
Undefined network / volume / secret / config	A service references a top-level resource that is not declared. Compose refuses to run with an undefined resource.	Add the missing top-level declaration, mark it external: true if managed outside Compose, or fix the typo.

Modern Compose best-practice dependency snippet

The canonical way to make an app wait for a database to be genuinely ready: a real healthcheck on the target, plus long-form depends_on with condition: service_healthy.

services:
  api:
    image: myorg/api:latest
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

With this shape, Compose starts db first, polls its healthcheck until it reports healthy, and only then starts api. You get predictable startup without shell-script retry loops.

Why a service graph is better than reading the YAML

YAML is a good serialization format but a poor architecture review surface. Once a file passes four or five services it becomes hard to answer simple questions by scrolling: which services share a network?, who actually mounts this volume?, is there a dependency cycle?, who talks to the database?.

A service graph forces those relationships to be explicit and makes hidden coupling jump out. That helps in four concrete ways:

Architecture review. Reviewers see the shape of the stack at a glance instead of pattern-matching on indentation.
Handoff & documentation. New teammates and open-source contributors get oriented in seconds; the diagram is a README-grade artifact.
Faster detection of hidden coupling. Cycles and multi-network bridges stand out visually, even when the YAML looks innocent.
Better READMEs and wikis. Exporting an SVG or PNG turns the graph into a real, versioned asset for your internal or open-source docs.

Local-only processing

In this version, your Compose file never leaves your browser. Parsing, validation, and graph rendering all run client-side; nothing is uploaded, logged, or sent to a server. This matters because Compose files routinely expose private image names, internal service names, ports, networks, registry URLs, and secret references — even without raw credentials, that metadata alone can be sensitive. Still, follow your organisation's policy before pasting confidential infrastructure definitions into any browser tool.

Compose files are parsed locally in your browser. Nothing you paste is uploaded, stored, or sent to a server.

Overview

A Compose file starts simple — an app, a database, maybe a cache — but grows surprisingly fast. Once you have workers, a broker, migrations, multiple networks, and three services sharing a volume, the YAML stops reflecting the architecture in any readable way. Two services quietly end up publishing the same host port; a cycle sneaks in through a legacy links: entry; an API is ordered to start after a database but not actually waiting for it to be ready. None of these fail YAML validation, so a plain linter misses them.

This tool fills that gap. It parses your Compose file with a Compose-aware understanding of services, networks, volumes, configs, secrets, and profiles, then runs a set of semantic checks drawn from the current Compose specification: host-port collision (including host IP, protocol, and port ranges), circular dependency across depends_on and legacy constructs, readiness gaps, environment interpolation, and undefined references to volumes, secrets, or networks. Findings are ranked from Critical to Informational with plain-English explanations and suggested fixes — not just error codes.

A visual service graph sits alongside the validator. Startup dependencies, shared-network reachability, and resource attachments each get their own edge styling, so “A starts before B” is never visually conflated with “A can reach B over the network” — two very different Compose semantics that linting tools usually merge. You can filter by node or edge type, highlight problem services, and export the diagram as SVG or PNG for READMEs and wikis. The whole thing runs locally in your browser; no Compose file is ever uploaded.

Use cases

When to use it

Spot host-port conflictsTwo services trying to bind 8080/tcp is the fastest way to a broken docker compose up.
Find circular dependenciesAcross depends_on, links, volumes_from, and network_mode: service:… so cycles that hide in legacy constructs still surface.
Review readiness gapsSee which dependencies only order startup versus which actually wait for a healthcheck-gated readiness signal.
See the network topology clearlyUnderstand which services can reach each other by service name versus which are isolated behind custom networks.
Document open-source or internal stacksExport an SVG or PNG for your README, wiki, or design doc instead of hand-drawing another diagram.
Audit required env vars and shared resourcesGet a ready-to-fill .env checklist and a list of every declared volume, secret, and config the services rely on.

When it's not enough

Runtime debuggingThis is a static analyser. For runtime issues use docker compose logs, docker compose ps, and docker inspect.
Production deployment validationCompose is excellent for local development and small deployments; for production orchestration use Kubernetes, ECS, or Nomad, each with their own validators.
Schema migration checksThe tool does not run SQL, execute migrations, or validate data models. It reads your Compose file only.

How to use it

1
Paste your Compose file (or load an example)
Drop in compose.yaml / docker-compose.yml, upload a file, or pick one of the built-in samples to see what findings look like.
2
Read the summary card
A few plain-English bullets at a glance: how many services parsed, whether ports collide, whether there are cycles, and how many required env vars you need to provide.
3
Walk the issues panel
Findings are ranked Critical, Warning, Recommendation, Informational. Each has a plain-English detail and a suggested fix. Critical issues block docker compose up; warnings and recommendations are quality improvements.
4
Inspect the service graph
Click a service to see its neighbours and highlighted edges. Filter by node type (services, networks, volumes, secrets, configs) or edge kind to reduce visual noise on larger stacks.
5
Fix collisions, tighten readiness, add healthchecks
Resolve any port collision first. Then add real healthchecks to critical dependencies (databases, brokers) and switch short-form depends_on to condition: service_healthy.
6
Export the diagram and env checklist
Download the service graph as SVG or PNG for your README and copy the generated .env template for teammates.

Common errors and fixes

depends_on fires before the database is ready

Add a healthcheck to the database service (e.g. pg_isready, redis-cli PING, or an HTTP probe) and use long-form depends_on with condition: service_healthy. Short-form depends_on only orders startup, not readiness.

Container fails to start with an address-already-in-use error

Two services are publishing the same host IP + host port + protocol. Change one of the host ports, or bind them to different host IPs. Note that 0.0.0.0 is a wildcard and collides with any specific IP on the same port.

Compose refuses to run with `services cannot be started in order`

A dependency cycle exists. Check depends_on, links, volumes_from, and network_mode: service:…. Break the cycle by removing one of the edges, introducing a message broker, or splitting a service that plays two roles.

`Compose does not know about the version: field` hints in logs

The top-level version: key is obsolete in modern Compose. It is accepted for backwards compatibility but no longer required. Remove it to stop misleading readers.

Services cannot reach each other by name after adding custom networks

Declaring a custom networks: list on a service disables the implicit default network for that service. Make sure the peer services share at least one network, or add `default` to the service's networks list.

Undefined named volume / secret / config at runtime

A service references a resource that is not declared at the top level. Add the missing top-level entry, mark it external: true if it is managed outside this Compose project, or fix the typo.

Sensitive values are leaking into `docker inspect`

Switch from environment: to Compose secrets: for passwords, tokens, and API keys. Secrets are mounted as files under /run/secrets/<name> and are not visible in inspect output.

Frequently asked questions

Visual Subnet Calculator & CIDR Range Validator AWS EventBridge Cron & Rate Expression Builder Cron Parser, Builder & Timezone Translator JSON ↔ YAML Converter JSON Formatter & Validator Webhook Signature Verifier & HMAC Playground All developer tools

Working on the network ranges your containers sit on? Pair this validator with the visual subnet calculator to plan VPC and CIDR layouts, then come back here to validate the container services running on top of them. Automating scheduled workloads? Build them with the AWS EventBridge schedule builder or cron parser, and validate the local stack that runs them here. Already have a JSON or YAML config you trust syntactically? Syntax is only the first step — the JSON ↔ YAML converter and JSON formatter help with the shape; this tool validates the architectural semantics.