Production Compose Workflow

Running docker compose up -d in production without a process is risky. A disciplined workflow covers four phases: preflight, deploy, verify, and rollback readiness. This lesson defines each phase.

The Four Phases

flowchart LR
    A["1. Preflight<br/>Validate config + images"] --> B["2. Deploy<br/>Pull + up -d"]
    B --> C["3. Verify<br/>Health + logs + endpoints"]
    C -->|"Issues?"| D["4. Rollback<br/>Revert to previous version"]
    C -->|"All good"| E["Stable ✓"]

    style A fill:#e3f2fd,stroke:#1565c0
    style B fill:#fff3e0,stroke:#ef6c00
    style C fill:#e8f5e9,stroke:#2e7d32
    style D fill:#ffebee,stroke:#c62828
    style E fill:#e8f5e9,stroke:#2e7d32

Phase 1: Preflight

Before touching production, validate everything:

# 1. Render and review the merged config
docker compose -f compose.yaml -f compose.prod.yaml config

# 2. Verify images exist and are pullable
docker compose -f compose.yaml -f compose.prod.yaml pull

# 3. Check host resources
df -h           # Disk space
free -h         # Memory
docker system df # Docker disk usage

Preflight Checklist

Check	Command / Action
Config valid?	docker compose config
Images pullable?	docker compose pull
Secrets/env available?	Verify .env or secret manager
Enough disk space?	df -h
Backup recent?	Verify volume backups for stateful services
Rollback artifacts ready?	Keep previous compose files and image tags

Phase 2: Deploy

# Pull first (separates registry issues from deployment)
docker compose -f compose.yaml -f compose.prod.yaml pull

# Deploy
docker compose -f compose.yaml -f compose.prod.yaml up -d

Pull Before Up

Pulling images separately surfaces registry or authentication errors early, before you have touched running containers.

Phase 3: Verify

Platform Checks

# All services running and healthy?
docker compose -f compose.yaml -f compose.prod.yaml ps

# Any errors in logs?
docker compose -f compose.yaml -f compose.prod.yaml logs --tail=100

# Check health of critical services
docker inspect --format='{{.State.Health.Status}}' myproject-db-1

Application Checks

# Can the API respond?
curl -f http://localhost:8080/health

# Can the web frontend load?
curl -s -o /dev/null -w "%{http_code}" http://localhost:80

What to Watch For

Signal	What It Means
All services Up (healthy)	Platform is good
Restart count increasing	A service is crash-looping
Health endpoint returns 200	Application is ready
Error spike in logs	Something is wrong at the app level

Phase 4: Rollback

If verification fails, roll back to the previous known-good state.

Before You Deploy: Save Rollback Artifacts

# Save current running image digests
docker compose -f compose.yaml -f compose.prod.yaml images > rollback-images.txt

# Keep previous compose files versioned in git
git stash  # or use git tags to mark releases

Rolling Back

# Revert compose files to previous version
git checkout HEAD~1 -- compose.yaml compose.prod.yaml

# Redeploy the previous version
docker compose -f compose.yaml -f compose.prod.yaml pull
docker compose -f compose.yaml -f compose.prod.yaml up -d

# Verify the rollback
docker compose -f compose.yaml -f compose.prod.yaml ps

Treat rollbacks with the same verification rigor as forward deployments.

Update Strategy Comparison

Strategy	Downtime	Complexity	Best For
docker compose up -d (recreate)	Brief (seconds)	Low	Most Compose deployments
Blue/Green (manual)	None	High	Critical zero-downtime services
Rolling update (Swarm/K8s)	None	Medium	Orchestrated environments

For most single-host Compose deployments, recreating with up -d causes only a few seconds of downtime during the container swap.

Key Takeaways

• Production deployments need a four-phase process: preflight → deploy → verify → rollback.
• Always docker compose config and docker compose pull before touching running containers.
• Verify both platform health (services running, no restarts) and application health (endpoints responding).
• Keep rollback artifacts (previous compose files, image tags) ready before every deployment.
• docker compose pull before up -d separates image pull failures from deployment failures.

What's Next

• Return to the Docker Compose in Depth module overview.
• Continue to Module 8: Operations, Observability, and Maintenance for day-2 operational tasks.