Skip to main content
Docker·7 min read

Dockerfile vs Docker Compose — Build One Image vs Run a Whole Stack

A clear, practical comparison of Dockerfile and Docker Compose: a Dockerfile defines how to build a single image, Compose defines how to run multiple containers together. Includes a realistic web+db example, a side-by-side table, and when to use each.

DT

DevOps Engineer & Technical Writer

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.

DOCKERFILE BUILDS ONE IMAGE · COMPOSE RUNS MANY CONTAINERS DOCKERFILE → BUILD INSTRUCTIONS FROM/COPY/RUN docker build one image ARTIFACT myapp:1.0 image One recipe → one layered, immutable image used by COMPOSE → RUN TOGETHER SERVICE web build: . SERVICE db postgres:16 SERVICE cache redis:7 SHARED NETWORK web → db:5432 · web → cache:6379 docker compose up

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

AspectDockerfileDocker Compose
Core questionHow 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>
ScopeA single imageOne or more services
Primary command<code class="inline-code">docker build</code><code class="inline-code">docker compose up</code>
NetworkingNot its concernCreates a shared network automatically
PersistenceNot its concernDefines named volumes
Env vars / portsBaked defaults onlySet per service at run time
Startup orderN/A<code class="inline-code">depends_on</code> with health conditions
OutputAn immutable imageRunning 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_on health conditions. depends_on without condition: service_healthy only 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.