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.

Docker Compose logo next to a terminal window showing docker compose up command

*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 bash` Enter a running container

Terminal screenshot showing docker compose ps output with two containers running

*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

“`

Diagram showing Docker volumes persisting data across container restarts

*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.

Developer smiling while looking at a dashboard showing multiple Docker containers running successfully

*Photo by George Morina on Pexels*

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *