English for Docker Compose

Docker Compose is often the first multi-container tool developers use, and its vocabulary — “service” versus “container,” “volume” versus “bind mount” — trips people up because the terms sound interchangeable but aren’t. Getting them right matters when debugging why a container can’t reach another, or why data disappeared after a restart. This guide covers the essential terms.

Key Vocabulary

Service — a definition in docker-compose.yml describing how to run a container (image, ports, environment, volumes), distinct from the running container itself. “The db service defines the Postgres image and its environment variables, but the actual running container is created when we run docker compose up.”

Volume — a persistent storage mechanism managed by Docker, used to keep data (like a database’s files) alive across container restarts and rebuilds. “We lost all the local data because we forgot to mount a volume — the container’s filesystem resets every time it’s recreated.”

Bind mount — a way of mapping a specific host directory into a container, commonly used in development to sync source code changes live without rebuilding the image. “The bind mount on ./src means changes we make locally show up inside the container immediately, without a rebuild.”

Network — an internal Compose-managed network that lets services reach each other by service name, without needing to know container IPs. “The API service can reach the database just by using db as the hostname, because Compose puts them on the same network automatically.”

depends_on — a directive that controls the order in which services start, though by default it only waits for the container to start, not for the application inside it to be ready. “depends_on started the database container first, but the API still crashed because Postgres wasn’t actually accepting connections yet — we needed a healthcheck too.”

Healthcheck — a command Docker runs periodically inside a container to determine if it’s actually ready, which depends_on can wait on when combined with condition: service_healthy. “Once we added a healthcheck to the database service, the API service correctly waited until Postgres was truly ready to accept connections.”

Common Phrases

• “Is this data in a named volume, or will it disappear the next time we rebuild?”
• “Are these two services on the same network? That would explain why the hostname isn’t resolving.”
• “depends_on alone won’t guarantee the database is actually ready — do we need a healthcheck?”
• “Is this a bind mount for local development, or should it be a volume in production?”
• “Which service is actually failing — the container itself, or something inside it?”

Example Sentences

Debugging a startup failure: “The app container starts fine, but it’s crashing on its first database query — depends_on only waited for the Postgres container to start, not for Postgres itself to finish initializing, so we need a healthcheck-based dependency instead.”

Explaining a data-loss incident in a postmortem: “We were using a bind mount pointed at a temporary directory instead of a named volume, so when the container was recreated during the deploy, all the uploaded files were wiped.”

Onboarding a new developer: “Each service in the compose file maps to one container, they’re all connected on the same internal network, and you can reach any of them by service name — so the frontend just calls http://api:3000, not a hardcoded IP.”

Professional Tips

• Say “service” when referring to the Compose configuration and “container” when referring to the actual running process — the distinction matters when debugging startup order or scaling.
• Distinguish a named volume from a bind mount explicitly in documentation — a bind mount ties data to a specific host path, while a volume is managed by Docker and safer for production data.
• Clarify that depends_on without a healthcheck only guarantees start order, not readiness — this is one of the most common causes of intermittent startup failures.
• Use “network” precisely when explaining connectivity issues — a service that can’t reach another almost always traces back to being on a different network or using the wrong hostname.

Practice Exercise

1. Explain in two sentences the difference between a named volume and a bind mount.
2. Write a one-sentence bug report describing a service that starts before its dependency is actually ready.
3. Describe, in your own words, how two services in the same Compose file reach each other by name.