The Problem
People constantly confuse the Dockerfile with Docker Compose because both are text files that live in a project and both involve "containers." But they answer two completely different questions. A Dockerfile answers "how do I build one image?" A Compose file answers "how do I run these containers together?" Using the wrong tool for the job leads to bloated images, hand-typed docker run commands with a dozen flags, and services that cannot find each other.
Both files are useful, and in real projects you use them together: Compose builds the web service from your Dockerfile and then runs it alongside a database and cache.
What a Dockerfile Is
A Dockerfile is a build recipe. It is a list of instructions that Docker executes top to bottom to produce a single, immutable image. It never runs anything on its own — it only describes how the image is assembled.
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
USER node
CMD ["node", "server.js"]
You turn this recipe into an image with one command:
docker build -t myapp:1.0 .
The output is myapp:1.0 — a layered, read-only image you can push to a registry and run anywhere.
What Docker Compose Is
A docker-compose.yml describes a running system — one or more services, the network between them, volumes for persistence, environment variables, and startup order. It is about orchestration at runtime, not about building a single image.
services:
web:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgres://app:secret@db:5432/appdb
REDIS_URL: redis://cache:6379
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: appdb
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 5s
timeout: 3s
retries: 5
cache:
image: redis:7-alpine
volumes:
pgdata:
Start the entire stack with one command:
docker compose up -d
Compose builds the web image from your Dockerfile, pulls postgres and redis, creates a shared network so web can reach db and cache by name, and starts everything in the right order.
Side-by-Side Comparison
| Aspect | Dockerfile | Docker Compose |
|---|---|---|
| Core question | How do I <strong>build</strong> one image? | How do I <strong>run</strong> containers together? |
| File | <code class="inline-code">Dockerfile</code> | <code class="inline-code">docker-compose.yml</code> |
| Scope | A single image | One or more services |
| Primary command | <code class="inline-code">docker build</code> | <code class="inline-code">docker compose up</code> |
| Networking | Not its concern | Creates a shared network automatically |
| Persistence | Not its concern | Defines named volumes |
| Env vars / ports | Baked defaults only | Set per service at run time |
| Startup order | N/A | <code class="inline-code">depends_on</code> with health conditions |
| Output | An immutable image | Running containers |
How They Relate
The key line that connects them is build: inside a Compose service:
services:
web:
build:
context: .
dockerfile: Dockerfile
image: myapp:1.0 # name the built image
When Compose sees build:, it runs the equivalent of docker build using your Dockerfile, then runs the resulting image as the web container. So Compose does not replace the Dockerfile — it consumes it. You can also skip building and point a service directly at a pre-built image with image:.
When to Use Which
- Use only a Dockerfile when you are packaging a single image to push to a registry, or when another system (Kubernetes, ECS) will handle running it.
- Use Compose when you need to run several containers together locally — a web app plus its database, a worker plus a queue, or a full microservice stack for integration tests.
- Use both in almost every real app: a Dockerfile builds your service's image, and a Compose file wires that service to its dependencies for local development.
Common Mistakes to Avoid
- Putting runtime config in the Dockerfile. Database URLs, secrets, and ports belong in Compose (or the orchestrator), not baked into the image. A baked-in secret ships to everyone who pulls the image.
- Expecting a Dockerfile to start a database. A Dockerfile builds one image; it cannot run Postgres alongside your app. That is Compose's job.
- Hard-coding container IPs. Compose gives every service a DNS name equal to the service name. Connect to
db:5432, never a numeric IP. - Skipping
depends_onhealth conditions.depends_onwithoutcondition: service_healthyonly waits for the container to start, not for the database to be ready to accept connections. - Forgetting a volume for the database. Without a named volume, your Postgres data vanishes the moment the container is recreated.
FAQ
Can Docker Compose work without a Dockerfile?
Yes. If every service uses a pre-built image from a registry (for example image: postgres:16), no Dockerfile is needed. You only need a Dockerfile for services whose image you build yourself, referenced with build:.
Is <code class="inline-code">docker compose up</code> the same as running <code class="inline-code">docker run</code> several times?
Conceptually yes, but Compose also creates a shared network, sets up DNS between services, mounts volumes, applies environment variables, and respects startup order — all from one declarative file. Doing that by hand with docker run is error-prone and hard to reproduce.
Should I use Docker Compose in production?
Compose is excellent for local development and small single-host deployments. For production at scale — rolling updates, autoscaling, self-healing across many nodes — most teams move to Kubernetes or a managed container service, while keeping the same Dockerfiles.
What is the difference between <code class="inline-code">docker-compose</code> and <code class="inline-code">docker compose</code>?
docker-compose (with a hyphen) is the older standalone Python tool (Compose v1). docker compose (a space) is the modern plugin built into the Docker CLI (Compose v2). The v2 plugin is the current standard and uses the same docker-compose.yml format.