Docker Compose for Beginners: Complete Setup Guide
Docker Compose simplifies multi-container Docker applications. Instead of running multiple `docker run` commands manually, you define your entire stack—services, networks, and volumes—in a single YAML file. With one command (`docker compose up`), you launch everything. This guide walks you through installing, configuring, and running Docker Compose on any system. You’ll learn how to define services, manage dependencies, and persist data. By the end, you’ll have a working multi-container setup for development or production.

*Photo by Wolfgang Weiser on Pexels*
## What is Docker Compose?
Docker Compose is a tool for defining and running multi-container Docker applications. It uses a `compose.yaml` (or `docker-compose.yml`) file to configure:
- Services – Each container (e.g., web app, database, cache).
- Networks – How containers communicate.
- Volumes – Persistent data storage.
Key benefits:
- Single command to start/stop all services.
- Declarative configuration – version-controlled and repeatable.
- Environment-specific overrides (dev, staging, prod).
- Dependency management – wait for a database before starting the app.
## Prerequisites
Before installing Docker Compose, ensure you have:
- Docker Engine installed (Docker Desktop on Windows/Mac, or `docker-ce` on Linux).
- Basic terminal knowledge – running commands, editing files.
- A text editor (VS Code, nano, or vim).
Check Docker version:
“`bash
docker –version
“`
If missing, install Docker.
## Installing Docker Compose
Docker Compose is bundled with Docker Desktop (Windows/Mac). On Linux, install it separately.
### Linux Installation
“`bash
# Download the latest stable release
sudo curl -L “https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)” -o /usr/local/bin/docker-compose
# Apply executable permissions
sudo chmod +x /usr/local/bin/docker-compose
# Verify installation
docker-compose –version
“`
### Windows & Mac
Docker Desktop includes Compose. Verify with:
“`bash
docker compose version
“`
Note: Modern Docker Desktop uses `docker compose` (with a space) as a plugin. Both syntaxes work.
## Your First Docker Compose File
Create a project directory and a `compose.yaml` file:
“`yaml
version: ‘3.8’
services:
web:
image: nginx:latest
ports:
- “8080:80”
db:
image: postgres:15
environment:
POSTGRES_PASSWORD: example
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
“`
What this does:
- web – runs Nginx on port 8080.
- db – runs PostgreSQL with a password and persistent volume.
- Volumes – `pgdata` keeps database data even if the container restarts.
## Running Your Stack
Start all services in detached mode:
“`bash
docker compose up -d
“`
Check status:
“`bash
docker compose ps
“`
Stop and remove containers:
“`bash
docker compose down
“`
Key commands:
| Command | Action |
|---|---|
| `docker compose up -d` | Start services in background |
| `docker compose down` | Stop and remove containers |
| `docker compose logs` | View service logs |
| `docker compose exec |
Enter a running container |

*Photo by Wolfgang Weiser on Pexels*
## Defining Dependencies
Use `depends_on` to control startup order:
“`yaml
services:
web:
image: my-app:latest
depends_on:
- db
- redis
db:
image: postgres:15
redis:
image: redis:7
“`
Important: `depends_on` only waits for the container to start, not for the service to be ready. For production, use a health check or an init script.
## Environment Variables and .env Files
Keep secrets and config out of your compose file:
Create .env file:
“`
DB_PASSWORD=supersecret
DB_USER=admin
“`
Reference in compose.yaml:
“`yaml
services:
app:
image: my-app:latest
environment:
- DB_PASSWORD=${DB_PASSWORD}
- DB_USER=${DB_USER}
“`
Best practice: Never commit `.env` to version control. Add it to `.gitignore`.
## Networking Made Simple
Docker Compose automatically creates a default network for your services. Containers can reach each other by service name.
Example: Your `web` service can connect to `db` using `db:5432` as the host:port.
Custom networks:
“`yaml
networks:
frontend:
backend:
services:
web:
networks:
- frontend
api:
networks:
- frontend
- backend
db:
networks:
- backend
“`
This isolates your database from the frontend, improving security.
## Data Persistence with Volumes
Volumes store data outside the container lifecycle. Define them at the top level:
“`yaml
volumes:
data-volume:
services:
app:
volumes:
- data-volume:/app/data
“`
Types of volumes:
- Named volumes – managed by Docker (recommended).
- Bind mounts – map a host directory (e.g., `./src:/app/src` for live code reloading).
Example bind mount for development:
“`yaml
services:
app:
volumes:
- ./src:/app/src
“`

*Photo by Wolfgang Weiser on Pexels*
## Scaling Services
Docker Compose can run multiple instances of a service:
“`bash
docker compose up -d –scale web=3
“`
Important: Scaling works best with stateless services. For stateful services (databases), use a single instance or a clustered setup.
## Real-World Example: Web App + Database + Cache
Here’s a complete stack for a typical web application:
“`yaml
version: ‘3.8’
services:
web:
image: nginx:alpine
ports:
- “80:80”
volumes:
- ./html:/usr/share/nginx/html
depends_on:
- api
api:
build: ./api
environment:
- DB_HOST=db
- DB_PORT=5432
- REDIS_HOST=redis
depends_on:
- db
- redis
db:
image: postgres:15-alpine
environment:
POSTGRES_DB: myapp
POSTGRES_PASSWORD: changeme
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
pgdata:
“`
Run it:
“`bash
docker compose up -d
“`
Test it: Open `http://localhost` in your browser.
## Troubleshooting Common Issues
Port already in use:
“`bash
# Find what’s using the port
sudo lsof -i :8080
# Change port in compose.yaml or stop the conflicting service
“`
Container exits immediately:
“`bash
# Check logs
docker compose logs
“`
Permission denied for volumes:
“`bash
# On Linux, fix permissions
sudo chown -R $USER:$USER ./data
“`
## Comparison: Docker Compose vs. Manual Docker Commands
| Aspect | Docker Compose | Manual Docker Commands |
|---|---|---|
| Setup time | Minutes (one YAML file) | Hours (multiple scripts) |
| Reproducibility | High (version-controlled) | Low (manual steps vary) |
| Multi-container | Built-in orchestration | Complex network setup |
| Scaling | `–scale` flag | Requires custom scripts |
| Environment isolation | `.env` files | Hardcoded or separate scripts |
| Learning curve | Medium | High for complex stacks |
Verdict: For any project with more than one container, Docker Compose is the clear winner.
## Best Practices for Production
1. Use specific image tags – avoid `latest`; pin versions like `postgres:15.4`.
2. Separate dev/prod profiles – use `docker-compose.override.yml` for local changes.
3. Limit resource usage – add `deploy.resources.limits` for memory/CPU.
4. Health checks – define `healthcheck` for critical services.
5. Backup volumes – regularly snapshot persistent data.
Example health check:
“`yaml
services:
db:
healthcheck:
test: [“CMD-SHELL”, “pg_isready -U postgres”]
interval: 10s
timeout: 5s
retries: 5
“`
## Conclusion
Docker Compose transforms how you manage multi-container applications. With a single YAML file, you define, run, and scale your entire stack. Start small with two services (web + database), then add caching, workers, and monitoring as needed. The time invested in learning Compose pays off immediately in faster setup, easier debugging, and reproducible environments.
Ready to automate your entire DevOps stack? Visit freefile.store to download ready-to-use Docker Compose templates, automation scripts, and developer tools. From CI/CD pipelines to monitoring stacks, we have production-tested configurations that save you hours of setup time.

*Photo by George Morina on Pexels*