Docker Compose: Multi-Container Apps Made Easy

Docker Compose: Multi-Container Apps

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 down cleans 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.

Related Articles

0 0 votes
Article Rating
guest
0 Comments
Oldest
Newest Most Voted
Scroll to Top