Docker Compose Guide

Introduction

Docker Compose helps you run multi-container apps with one config file. Instead of starting your API, database, and cache one by one, you describe them in compose.yml and manage everything with docker compose.

What Docker Compose does

Use Docker Compose when your app depends on more than one service.

Common examples:

• A Node.js app and a Postgres database
• A Laravel app, MySQL, and Redis
• A frontend, backend, and worker service

Compose lets you:

• Define services in one YAML file
• Start and stop everything together
• Share networks automatically
• Mount volumes for live development
• Rebuild services when code changes

Basic compose.yml example

This example starts an app and a database:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

What the main keys mean

• services: The containers your app needs
• build: Build an image from a local Dockerfile
• image: Use an existing image from Docker Hub
• ports: Map host ports to container ports
• volumes: Persist data or mount local files
• environment: Pass environment variables into the container
• depends_on: Start one service before another

Daily commands

These are the Compose commands you will use most often:

# Start all services
docker compose up

# Start in background
docker compose up -d

# Rebuild and start
docker compose up --build

# See running services
docker compose ps

# Read logs
docker compose logs

# Follow logs live
docker compose logs -f

# Stop services
docker compose stop

# Stop and remove containers, network, and default resources
docker compose down

Common development flow

docker compose up -d --build
docker compose ps
docker compose logs -f

When you are done:

docker compose down

Working with one service

You can target a specific service instead of the whole stack:

# Start only the app service
docker compose up app

# Rebuild one service
docker compose build app

# Open a shell inside a service
docker compose exec app sh

Using profiles

Profiles let you keep optional services out of the default startup.

Example:

services:
  migrate:
    image: my-app:latest
    command: npm run migrate
    profiles: ["ops"]

That means migrate will not run during a normal docker compose up.

Start it only when needed:

docker compose --profile ops up migrate

This is useful for jobs like migrations, admin tools, or one-off maintenance tasks.

Quick tips

• Use docker compose for projects with multiple services.
• Keep service names simple like app, db, and redis.
• Use volumes in development so code changes appear inside the container.
• If something fails, check docker compose ps and docker compose logs -f first.