
Photo by Rubaitul Azad on Unsplash
Docker Compose is the de‑facto tool for defining, building, and running multi‑container Docker applications on a single host. While Kubernetes handles orchestration at scale, Compose lets you prototype, test, and even ship small‑to‑medium workloads without leaving the comfort of docker compose up. In this article we’ll explore why Compose remains essential in 2025, how to write clean docker-compose.yml files, and practical tips for networking, data persistence, CI integration, and troubleshooting.
Why Compose Still Matters
- Rapid iteration – Spin up an entire stack (web server, database, cache) with a single command.
- Local parity – Your development environment mirrors production exactly, reducing “works‑on‑my‑machine” bugs.
- Zero‑friction CI – Most CI providers ship Docker and Compose pre‑installed; you can run your entire test suite inside containers.
- Lightweight orchestration – No need for a full Kubernetes cluster when you only require a few services on a laptop or a small VPS.
With over 90 % of organizations using or evaluating container platforms, the ecosystem around Docker Compose—Compose v2, BuildKit, and integrated tooling—is robust enough to support production workloads in many use cases.
1. The Anatomy of a docker-compose.yml
A Compose file is a declarative YAML document that describes services, networks, volumes, and other configuration options. Below is a minimal example for a three‑service stack: a Python web app, a PostgreSQL database, and a Redis cache.
# docker-compose.yml
version: "3.9"
services:
web:
build: ./app # Build from local Dockerfile
ports:
- "8000:80" # Host:Container mapping
environment:
DATABASE_URL: postgres://postgres:pw@db:5432/app
REDIS_URL: redis://redis:6379
depends_on:
- db
- redis
db:
image: postgres:15
volumes:
- db-data:/var/lib/postgresql/data # Persist data across restarts
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: pw
POSTGRES_DB: app
redis:
image: redis:7
volumes:
- redis-data:/data
networks:
default:
driver: bridge # Default Docker network
volumes:
db-data:
redis-data:
Key Points
| Section | Purpose | Tips |
|---|---|---|
services |
Each container in the stack | Keep service names short and descriptive. |
build / image |
How to obtain the image | Use build for local code, image for public registries. |
ports |
Expose ports to the host | Avoid exposing sensitive ports unless necessary. |
environment |
Pass env vars into containers | Store secrets in a .env file and reference them with ${VAR}. |
depends_on |
Order of startup | Does not wait for readiness; use healthchecks or entrypoint scripts if needed. |
volumes |
Persist data | Named volumes are automatically cleaned up with docker compose down -v. |
networks |
Container communication | By default all services join the same bridge network, enabling hostname resolution (db, redis). |
2. Advanced Service Configuration
2.1 Build Contexts and Multi‑Stage Builds
When a service needs custom binaries or build steps, use multi‑stage Dockerfiles:
# app/Dockerfile
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages ./lib
COPY . .
CMD ["python", "server.py"]
Compose automatically passes the build context, but you can override it:
web:
build:
context: ./app
dockerfile: Dockerfile.dev # Optional custom Dockerfile name
2.2 Healthchecks and Readiness
Compose supports health checks to signal when a service is ready for traffic.
db:
image: postgres:15
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
You can then use depends_on with condition: service_healthy in Compose v3.9, ensuring dependent services start only after the database is ready.
2.3 Secrets and .env Files
Store sensitive data outside the repository:
# .env (ignored by Git)
POSTGRES_PASSWORD=supersecret
REDIS_PASSWORD=anothersecret
Reference them in docker-compose.yml:
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
REDIS_PASSWORD: ${REDIS_PASSWORD}
Compose automatically loads the .env file, but you can also pass a custom file with --env-file.
3. Networking Deep Dive
3.1 Default Bridge Network
All services share a single bridge network by default, enabling inter‑service DNS resolution (db, redis). This is sufficient for most local stacks.
3.2 Custom Networks
For more control (e.g., segregating frontend from backend), define multiple networks:
networks:
front:
driver: bridge
back:
driver: bridge
services:
web:
networks:
- front
- back
Now web can talk to db on the back network while remaining isolated from other services that only join front.
3.3 Host Networking
If you need container ports to be exposed directly on the host’s interfaces (e.g., for a VPN or Wi‑Fi hotspot), use:
services:
wifi:
image: some/host-networked
network_mode: host
Caution: network_mode: host disables port mapping and isolates the container from Compose networking.
4. Data Persistence and Volume Management
4.1 Named Volumes vs Bind Mounts
| Type | Use Case |
|---|---|
Named volumes (volumes:) |
Persistent data across restarts, managed by Docker |
Bind mounts (./local:/container) |
Development: hot‑reload code, share host files |
Example bind mount for a Node.js app:
web:
build: .
volumes:
- ./:/app # Source code
- /app/node_modules # Prevent host node_modules from overriding container’s
4.2 Backing Up Volumes
Use Docker CLI or third‑party tools to snapshot named volumes:
docker run --rm \
-v db-data:/data \
-v $(pwd)/backup:/backup \
alpine tar czf /backup/db.tar.gz -C /data .
Automate this in CI/CD pipelines to maintain point‑in‑time restores.
5. Integrating Compose into CI/CD
Most CI services (GitHub Actions, GitLab CI, Bitbucket Pipelines) provide Docker runtime out of the box. A minimal GitHub Actions workflow that tests a Python service:
name: Test
on:
push:
branches: [ main ]
jobs:
build-test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:15
env:
POSTGRES_PASSWORD: pw
POSTGRES_DB: app
ports:
- 5432:5432
steps:
- uses: actions/checkout@v4
- name: Set up Docker Compose
run: |
docker compose version
- name: Run tests
env:
DATABASE_URL: postgres://postgres:pw@localhost:5432/app
run: |
docker compose up --build -d
pytest
docker compose down
Key takeaways:
- Service definition in the workflow mirrors your
docker-compose.yml. - Environment variables can be overridden per job.
docker compose downcleans up resources after tests.
6. Common Pitfalls and How to Avoid Them
| Issue | Symptom | Fix |
|---|---|---|
| Port conflicts on host | Cannot bind port 80: address already in use |
Use different host ports or remove the mapping during local dev. |
| “Image not found” errors | Docker Compose fails to pull public image | Verify tag spelling; ensure network connectivity; run docker login. |
Unhealthy containers stuck in starting |
Services never become ready | Add healthchecks, or increase restart: on-failure. |
Data loss after docker compose down -v |
Volumes removed unintentionally | Use named volumes and avoid the -v flag unless you want a clean slate. |
| Secrets leaking into images | Environment variables appear in image layers | Pass secrets via .env or Docker secrets; never bake them into Dockerfiles. |
7. When to Move Beyond Compose
Compose shines for local development, small deployments, and simple CI pipelines. However, when you need:
- High availability (automatic scaling, self‑healing)
- Cross‑cluster networking (services spread across multiple hosts or clouds)
- Advanced scheduling policies (affinity, taints)
…you should consider Kubernetes or a managed orchestrator like Amazon ECS/Fargate. Compose can still be used as a lightweight front for local testing before porting to an orchestrator.
Conclusion
Docker Compose remains the fastest path from code to running multi‑container applications. By mastering its YAML syntax, networking model, and integration patterns, you can keep your development stack lean while ensuring consistency across environments. Whether you’re a solo developer on a laptop or a team deploying microservices to a VPS, Compose gives you the power of containers without the overhead of a full cluster.
Happy composing!
Frequently Asked Questions (FAQ)
What is the difference between docker compose up and docker compose run?
docker compose up starts all services defined in the Compose file and keeps them running, creating networks and volumes as needed.
docker compose run runs a one‑off command in a new container for a single service without starting the rest of the stack.
How can I keep my secrets out of the docker-compose.yml file?
Place sensitive values in a separate .env file and reference them with ${VAR} syntax in the Compose file.
Docker Compose automatically loads the .env file, keeping credentials off‑hand from version control.
Does depends_on guarantee that dependent services are ready before starting?
No—depends_on only controls start order, not readiness.
Use health checks or entrypoint scripts to wait for a service (e.g., PostgreSQL) to be fully available before proceeding.
Can I use Compose in production environments?
Yes; with Compose v2, BuildKit, and proper networking/volume management, it supports lightweight production workloads on single hosts or small VPS.
For larger scale orchestration, consider Kubernetes, but Compose remains suitable for many production scenarios where simplicity is key.


