Questions People Ask About Compose Files and Dockerfiles

The Compose File

Do I still need the version key in docker-compose.yml?

No. The version key belonged to the Compose v1 file formats. Docker Compose v2 follows the Compose Specification, ignores the key and prints a warning when it sees one. Delete the line; the rest of the file is unaffected.

What is the difference between ports and expose?

ports publishes a container port on the host, written host:container, so your browser or other machines can reach it. expose only documents a port for other containers, which can reach every container port on the shared network anyway. Most services need ports; databases usually need neither.

Should I use a named volume or a bind mount?

Use a bind mount (./folder:/path) for source code you edit while the container runs. Use a named volume (name:/path, declared under a top-level volumes key) for data the container produces and must keep, such as database files. Named volumes survive docker compose down; bind mounts are just your folder.

Why does my app fail to connect to the database on the first start?

Because depends_on in its short form only orders container start, and a database is started a moment before it accepts connections. Add a healthcheck to the database service and change the dependant to the long form with condition: service_healthy, so it waits for the probe to pass.

How do services talk to each other?

By service name. Compose creates a private network and registers each service name in its DNS, so the app connects to db:5432, not to localhost or an IP. localhost inside a container is the container itself.

Why is docker compose up saying the port is already allocated?

Something on the host already listens on the left-hand number in ports. It may be another Compose project, a local database, or a previous container that did not stop. Change the host port (the left number), keep the container port (the right number), and check docker ps for leftovers.

Is it bad to use image tags like latest?

It is unpredictable. latest is whatever the maintainers pushed most recently, so the same file pulls different software on different days and a rebuild can break a working stack. Pin a version tag such as postgres:16-alpine and bump it on purpose.

Images, Users and Secrets

Why does my container run as root, and does it matter?

Because images run as root unless a USER instruction says otherwise, and most application images never add one. It matters: a vulnerability in the app then has root inside the container, and a container escape becomes root on the host. Create a user in the Dockerfile and switch to it before CMD, or set user: in Compose.

Where do passwords go if not in the Compose file?

In a .env file next to the Compose file, one KEY=value per line, referenced from the YAML as ${KEY}. Add .env to .gitignore. Compose reads it automatically. For production, secrets: with files or a secrets manager keeps them out of environment variables altogether.

The longer version of most of these answers is in the guide, and the validator will point at the exact line in your own file.