"But it runs on my laptop..."
That sentence has become a legend in the standup room every time staging or production throws a tantrum. Fortunately, Docker arrived with a fix: wrap the application in a container so the environment is identical everywhere.
But one thing still gets in the way. When the application needs a web server (FastAPI), a database (PostgreSQL), a cache (Redis), and a queue (RabbitMQ), are you really going to run docker run one at a time for each container?
This is where Docker Compose steps in as the hero. 😎
Key takeaways
- A Dockerfile only manages one container, while a real application usually needs a database, a cache, and a message broker at once.
- Docker Compose packs the web server, the database, and the cache into one declarative
docker-compose.ymlfile you start with a single command. - Network isolation and persistent volumes are handled automatically by Compose, so database data survives even when the container is stopped.
- Onboarding a new team member becomes smooth, because
git clonethendocker compose up -dis all it takes, with nothing installed by hand.
Why Is a Dockerfile Not Enough?
A Dockerfile is like a recipe for building one container. For example, a recipe specific to your FastAPI application.
In real practice, an application rarely stands alone. You need a database, you need Redis, and you might need RabbitMQ too.
With nothing but a plain Dockerfile:
- You have to build and run the application container.
- You have to run the PostgreSQL container with its own environment variables.
- You have to run the Redis container.
- You have to wire all three together by hand inside one Docker Network.
Never mind the new team member who has to repeat every one of those steps from scratch. Exhausting, right? 😅
Docker Compose exists to organize many containers (multi-container) from a single configuration file.
One File for Every Service
With Docker Compose, you create one file named docker-compose.yml holding the blueprint for the whole application stack.
Once the file is ready, run one command:
docker compose up -d
Every service (web, database, redis) starts automatically and connects to the others on one network.
The Anatomy of a docker-compose.yml File
Here is a simple docker-compose.yml configuration that connects a web server to PostgreSQL:
services:
web:
build: .
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://user:password@db:5432/mydatabase
depends_on:
db:
condition: service_healthy
db:
image: postgres:15-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: password
POSTGRES_DB: mydatabase
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user -d mydatabase"]
interval: 5s
timeout: 5s
retries: 5
volumes:
postgres_data:
A quick explanation:
services: the list of containers to run (webanddb).build: .: the instruction to build the container from the local Dockerfile.depends_onwithcondition: service_healthy: wait until thedbcontainer is genuinely ready for connections, not merely started.volumes: store database data so it is not lost when the container stops.
Oh, and older examples sometimes that put version: '3.8' on the first line. That field is no longer needed in newer Compose versions, and Docker prints an obsolete warning if you include it.
The Commands You Use Most
A few commands you will type every day:
docker compose up -d: start every service in the background.docker compose ps: peek at the status of the services that are running.docker compose logs -f web: follow the application log in real-time.docker compose down: stop every container and the network.
One Command, No Drama
Send the "it runs on my laptop" drama far away from your team. With docker-compose.yml, the whole application stack configuration, from web server and PostgreSQL database to Redis cache and message broker, is documented neatly as consistent declarative code.
One docker compose up -d command and your local environment is ready to take requests in seconds. A new team member does git clone, runs one command, and starts coding. No more two-hour debugging sessions over a slightly different PostgreSQL version. 🎉
Happy Composing, and may your docker compose up never fail on the first day of work. 👋