Docker Compose checker: validate docker-compose.yml

What to paste

Paste one Compose file. If it uses ${VARIABLES}, paste their values into the second box as KEY=VALUE lines. Use made-up values for passwords.

The checker reads only what you paste. It doesn't see your .env file, files listed under a service's env_file, or files pulled in with include or extends. When a file uses include or extends, the result says the model is incomplete.

How to read the findings

Each finding names the path in the file, such as services.app.ports[0], and the line when it can.

Severity	What it means
Error	Compose would reject this, or a reference points at nothing. Fix it first.
Warning	The file probably doesn't do what you meant, such as a variable with no value.
Advisory	Valid, but worth a second look. It isn't a security verdict.
Info	Context about what the checker did or couldn't read.

A web app that depends on a database you forgot to add

Example

services:
  app:
    image: nginx:latest
    ports:
      - "8080:80"
    depends_on:
      - db

The result is Compose model has blocking issues. The error says the dependency db is not in the file. Two advisories follow: the image doesn't pin a version, and port 8080 has no host address.

Why is my container port open to the whole network?

A port written as "8080:80" listens on every network interface of the host, not just on the host itself. Docker's port publishing guide calls this insecure by default.

If only a reverse proxy on the same machine should reach the app, add the local address: "127.0.0.1:8080:80". The checker flags published ports with no host address for this reason.

To set up the proxy side, the nginx proxy_pass calculator shows how a request path maps to the app. The course chapter on accessing apps safely at home covers the bigger picture.

Is mounting the Docker socket safe?

Only for containers you trust fully. A container with /var/run/docker.sock can control Docker, and Docker runs as root. Docker's security guide says only trusted users should control the daemon.

Reverse proxies and dashboards often ask for it. Check what the app needs the socket for before you add it.

Why isn't my variable being replaced?

Compose fills ${VAR} from your shell and the .env file in the project folder. A service's env_file is different: it passes variables into the container and doesn't fill ${VAR} in the Compose file. See variable interpolation.

The default forms differ on empty values:

${VAR-default} uses the default when VAR isn't set.
${VAR:-default} uses it when VAR isn't set or is empty.
${VAR?message} stops with the message when VAR isn't set.
${VAR:?message} stops when VAR isn't set or is empty.

Write $$ for a literal dollar sign, such as in a healthcheck command. The full list is in the interpolation reference.

Do I still need the version line?

No. Docker's Compose reference says version is only informative and Compose warns that it's obsolete. Compose always uses the latest schema, whatever the line says. You can delete it unless an older tool still needs it.

Does depends_on wait for the database to be ready?

Not by default. A plain depends_on only sets the start order. To wait until the database is ready, give it a healthcheck and use condition: service_healthy, as Docker's startup order guide shows.

The checker confirms that each dependency exists in the file. It can't tell whether a healthcheck will pass.

Should I pin image tags?

Pinning makes updates a choice instead of a surprise. An image with no tag, or with latest, can change the next time you pull. Pin a version such as postgres:16, or a digest when you need the exact same image every time.

How do I check the whole project?

Run docker compose config -q in the project folder. It merges every file, .env, and profile the way the real deployment does, and prints nothing when the model is valid. Add --environment to see the values it used. See the compose config reference.

Neither check proves the images exist, ports are free on the host, or the services start. Those need a real docker compose up. If Compose is new to you, start with understanding Docker Compose. If your services build from a Dockerfile, the .dockerignore tester shows what goes into the build.