Compose Commands

Docker Compose provides a rich set of commands for managing multi-container applications. This lesson covers all essential commands and their options.

Command Structure

docker compose [OPTIONS] COMMAND [ARGS]

Global options:

• -f, --file: Specify compose file
• -p, --project-name: Set project name
• --profile: Activate profile
• --env-file: Specify environment file

Lifecycle Commands

Up - Start Services

# Start all services
docker compose up

# Start in detached mode (background)
docker compose up -d

# Start specific services
docker compose up -d web api

# Build images before starting
docker compose up -d --build

# Force recreate containers
docker compose up -d --force-recreate

# Remove orphan containers
docker compose up -d --remove-orphans

# Don't start dependencies
docker compose up -d --no-deps api

# Scale while starting
docker compose up -d --scale worker=3

Down - Stop and Remove

# Stop and remove containers
docker compose down

# Also remove volumes
docker compose down -v

# Also remove images
docker compose down --rmi all        # All images
docker compose down --rmi local      # Only images without custom tag

# Remove orphan containers
docker compose down --remove-orphans

# Timeout for stopping containers
docker compose down -t 30

Start, Stop, Restart

# Stop without removing
docker compose stop
docker compose stop api

# Start stopped containers
docker compose start
docker compose start api

# Restart containers
docker compose restart
docker compose restart api

# Restart with timeout
docker compose restart -t 30 api

Pause and Unpause

# Freeze containers
docker compose pause
docker compose pause api

# Resume containers
docker compose unpause
docker compose unpause api

Build Commands

Build Images

# Build all service images
docker compose build

# Build specific services
docker compose build api worker

# Build without cache
docker compose build --no-cache

# Build with build arguments
docker compose build --build-arg VERSION=1.0

# Pull base images before building
docker compose build --pull

# Show build progress
docker compose build --progress plain

# Push images after building
docker compose build --push

Pull Images

# Pull all images
docker compose pull

# Pull specific services
docker compose pull db redis

# Ignore pull failures
docker compose pull --ignore-pull-failures

# Pull quietly
docker compose pull -q

Push Images

# Push all built images
docker compose push

# Push specific services
docker compose push api web

Execution Commands

Exec - Run in Running Container

# Execute command in running container
docker compose exec api bash

# Execute as specific user
docker compose exec -u root api bash

# Execute without TTY
docker compose exec -T api cat /app/config.json

# Set environment variable
docker compose exec -e DEBUG=true api npm test

# Set working directory
docker compose exec -w /app/tests api npm test

# Execute in specific container (when scaled)
docker compose exec --index 2 api bash

Run - Run One-off Command

# Run command in new container
docker compose run api npm test

# Remove container after running
docker compose run --rm api npm test

# Don't start dependencies
docker compose run --no-deps api npm test

# Override entrypoint
docker compose run --entrypoint bash api

# Map additional ports
docker compose run -p 9229:9229 api npm run debug

# Set environment variables
docker compose run -e NODE_ENV=test api npm test

# Run as specific user
docker compose run -u root api apt-get update

# Use service configuration but different command
docker compose run api bash

Key Difference: exec vs run

exec	run
Uses existing container	Creates new container
Faster	Slower (creates container)
Requires running container	Works with stopped services
No -rm needed	Use --rm to clean up

Information Commands

PS - List Containers

# List running containers
docker compose ps

# List all containers
docker compose ps -a

# Show only IDs
docker compose ps -q

# Filter by status
docker compose ps --status running
docker compose ps --status exited

# Custom format
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"

Logs - View Output

# View all logs
docker compose logs

# Follow logs
docker compose logs -f

# Follow specific services
docker compose logs -f api db

# Show timestamps
docker compose logs -t

# Last N lines
docker compose logs --tail 100

# Since timestamp
docker compose logs --since 10m
docker compose logs --since 2024-01-15T10:00:00

# Until timestamp
docker compose logs --until 2024-01-15T12:00:00

# No color
docker compose logs --no-color

# Combine options
docker compose logs -f -t --tail 50 api

Top - View Processes

# All processes in all containers
docker compose top

# Specific service
docker compose top api

Config - Validate and View

# Validate compose file
docker compose config

# Show resolved config
docker compose config --format yaml

# Show only service names
docker compose config --services

# Show only volume names
docker compose config --volumes

# Show only profile names
docker compose config --profiles

Events - Stream Events

# Stream container events
docker compose events

# JSON format
docker compose events --json

# Filter events
docker compose events api

Port - Show Port Mappings

# Show mapped port
docker compose port api 3000
# Output: 0.0.0.0:3000

# Specific protocol
docker compose port api 3000/tcp

# Specific container index (when scaled)
docker compose port --index 2 api 3000

Cleanup Commands

RM - Remove Containers

# Remove stopped containers
docker compose rm

# Force remove without confirmation
docker compose rm -f

# Remove volumes too
docker compose rm -v

# Stop before removing
docker compose rm -s

Kill - Force Stop

# Force stop all containers
docker compose kill

# Force stop specific services
docker compose kill api worker

# Send specific signal
docker compose kill -s SIGTERM api

Advanced Commands

Create - Create Without Starting

# Create containers without starting
docker compose create

# Recreate containers
docker compose create --force-recreate

# Build before creating
docker compose create --build

Copy - Copy Files

# Copy from container
docker compose cp api:/app/config.json ./config.json

# Copy to container
docker compose cp ./config.json api:/app/config.json

# Copy from specific container when scaled
docker compose cp --index 2 api:/app/logs ./logs

Wait - Wait for Condition

# Wait for service to be running
docker compose wait api

# Wait for service to exit
docker compose wait --down-project api

Working with Multiple Files

# Use specific file
docker compose -f docker-compose.prod.yml up -d

# Merge multiple files
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

# Use .env file
docker compose --env-file .env.production up -d

Command Cheat Sheet

Task	Command
Start everything	docker compose up -d
Stop everything	docker compose down
View logs	docker compose logs -f
Rebuild and start	docker compose up -d --build
Shell into container	docker compose exec api bash
Run tests	docker compose run --rm api npm test
Scale service	docker compose up -d --scale worker=3
Check status	docker compose ps
Validate config	docker compose config
Clean up	docker compose down -v --rmi all

Key Takeaways

• up -d and down are the most common lifecycle commands
• Use --build to rebuild images when code changes
• exec for running containers, run for one-off commands
• Always use --rm with run to avoid container buildup
• logs -f follows logs in real-time
• config validates your compose file before running
• Use -f to specify alternative compose files
• down -v removes volumes (careful with data!)