Docker Compose Complete Guide (2026): Install, Configure, and Deploy Multi-Container Apps

┌─────────────────────────────────┬───────────────────────────────┐
│       Virtual Machines          │          Containers           │
├─────────────────────────────────┼───────────────────────────────┤
│  ┌─────┐ ┌─────┐ ┌─────┐       │  ┌─────┐ ┌─────┐ ┌─────┐     │
│  │App A│ │App B│ │App C│       │  │App A│ │App B│ │App C│     │
│  ├─────┤ ├─────┤ ├─────┤       │  ├─────┤ ├─────┤ ├─────┤     │
│  │Bins │ │Bins │ │Bins │       │  │Bins │ │Bins │ │Bins │     │
│  │Libs │ │Libs │ │Libs │       │  │Libs │ │Libs │ │Libs │     │
│  ├─────┤ ├─────┤ ├─────┤       │  └──┬──┘ └──┬──┘ └──┬──┘     │
│  │Guest│ │Guest│ │Guest│       │     └───────┼───────┘         │
│  │ OS  │ │ OS  │ │ OS  │       │      ┌──────┴──────┐          │
│  └──┬──┘ └──┬──┘ └──┬──┘       │      │   Docker    │          │
│     └───────┼───────┘          │      │   Engine    │          │
│      ┌──────┴──────┐           │      └──────┬──────┘          │
│      │ Hypervisor  │           │             │                  │
│      └──────┬──────┘           │      ┌──────┴──────┐          │
│      ┌──────┴──────┐           │      │   Host OS   │          │
│      │   Host OS   │           │      └──────┬──────┘          │
│      └──────┬──────┘           │      ┌──────┴──────┐          │
│      ┌──────┴──────┐           │      │  Hardware   │          │
│      │  Hardware   │           │      └─────────────┘          │
│      └─────────────┘           │                                │
├─────────────────────────────────┼───────────────────────────────┤
│  Traits:                        │  Traits:                       │
│  • Full OS per VM               │  • Shared host kernel          │
│  • Boot time: minutes           │  • Boot time: seconds          │
│  • Memory: GB-scale             │  • Memory: MB-scale            │
│  • Isolation: strong            │  • Isolation: good             │
└─────────────────────────────────┴───────────────────────────────┘

┌───────────────────────────────────────────────────────────────────┐
│                        Docker Architecture                        │
├───────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Client                                Docker Host                │
│  ┌─────────────────┐                 ┌───────────────────────────┐│
│  │ docker build    │                 │     Docker Daemon         ││
│  │ docker pull     │  ──REST API──>  │     (dockerd)             ││
│  │ docker run      │                 │  ┌─────────────────────┐  ││
│  └─────────────────┘                 │  │    Containers       │  ││
│                                      │  │ ┌───┐ ┌───┐ ┌───┐   │  ││
│                                      │  │ │ C │ │ C │ │ C │   │  ││
│                                      │  │ └───┘ └───┘ └───┘   │  ││
│                                      │  └─────────────────────┘  ││
│                                      │  ┌─────────────────────┐  ││
│                                      │  │      Images         │  ││
│                                      │  │ ┌───┐ ┌───┐ ┌───┐   │  ││
│                                      │  │ │ I │ │ I │ │ I │   │  ││
│                                      │  │ └───┘ └───┘ └───┘   │  ││
│                                      │  └─────────────────────┘  ││
│                                      └───────────────────────────┘│
│                                                    ▲               │
│                                                    │               │
│                                               pull/push            │
│                                                    │               │
│                                                    ▼               │
│                                      ┌───────────────────────────┐│
│                                      │       Registry            ││
│                                      │     (Docker Hub)          ││
│                                      │  ┌─────────────────────┐  ││
│                                      │  │ nginx, mysql, redis │  ││
│                                      │  │ node, python, ...   │  ││
│                                      │  └─────────────────────┘  ││
│                                      └───────────────────────────┘│
└───────────────────────────────────────────────────────────────────┘

brew install --cask docker

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoids needing sudo)
sudo usermod -aG docker $USER

# Install prerequisites
sudo yum install -y yum-utils

# Add the repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Install Docker Engine
sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group
sudo usermod -aG docker $USER

# Check version
docker --version
# Docker version 24.0.7, build afdd53b

# View detailed info
docker info

# Run the test container
docker run hello-world

docker run hello-world

┌─────────────────────────────────────────────────────────────┐
│            docker run hello-world — step by step            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. The Docker client sends the command to the Daemon       │
│                    │                                        │
│                    ▼                                        │
│  2. The Daemon checks for a local hello-world image         │
│                    │                                        │
│           ┌───────┴───────┐                                 │
│           │  Image found  │                                 │
│           │   locally?    │                                 │
│           └───────┬───────┘                                 │
│           No      │       Yes                               │
│           │       └────────────────┐                        │
│           ▼                        │                        │
│  3. Pulls the image from Docker Hub│                        │
│           │                        │                        │
│           └────────────────────────┤                        │
│                                    ▼                        │
│  4. Creates a container from the image                      │
│                    │                                        │
│                    ▼                                        │
│  5. Runs the container, prints "Hello from Docker!"         │
│                    │                                        │
│                    ▼                                        │
│  6. Container finishes and stops automatically              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# Search for nginx images
docker search nginx

# Pull the official nginx image
docker pull nginx:latest

# List local images
docker images

# Inspect image details
docker inspect nginx:latest

# View image layer history
docker history nginx:latest

# Remove an image
docker rmi nginx:latest

# Run an nginx container
# -d: detached (background)
# -p: port mapping (host:container)
# --name: container name
docker run -d -p 8080:80 --name my-nginx nginx

# List running containers
docker ps

# View logs
docker logs my-nginx

# Follow logs in real time
docker logs -f my-nginx

# Open a shell inside the container
docker exec -it my-nginx bash

# Run a single command inside the container
docker exec my-nginx cat /etc/nginx/nginx.conf

# Stop the container
docker stop my-nginx

# Start it again
docker start my-nginx

# Stop and remove
docker stop my-nginx && docker rm my-nginx

# Force-remove a running container
docker rm -f my-nginx

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

# Frequently used OPTIONS
-d, --detach          # Run in background
-p, --publish         # Port mapping (host_port:container_port)
-v, --volume          # Mount a volume (host_path:container_path)
-e, --env             # Set environment variable
--name                # Assign a container name
--restart             # Restart policy: no, on-failure, always, unless-stopped
--network             # Specify a network
-it                   # Interactive terminal (-i keeps STDIN open, -t allocates a pseudo-TTY)
--rm                  # Automatically remove the container when it stops

# Create a volume
docker volume create my-data

# List volumes
docker volume ls

# Use a volume
docker run -d \
  --name mysql-db \
  -v my-data:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

# Inspect a volume
docker volume inspect my-data

# Remove a volume
docker volume rm my-data

# Remove all unused volumes
docker volume prune

# Mount the current directory
docker run -d \
  --name nginx-web \
  -p 8080:80 \
  -v $(pwd)/html:/usr/share/nginx/html \
  nginx

# Read-only mount (container cannot write)
docker run -d \
  --name nginx-web \
  -p 8080:80 \
  -v $(pwd)/html:/usr/share/nginx/html:ro \
  nginx

# List networks
docker network ls

# Create a custom network
docker network create my-network

# Run a container on a specific network
docker run -d --name app --network my-network nginx

# Connect an existing container to a network
docker network connect my-network container_name

# Inspect a network
docker network inspect my-network

# Remove a network
docker network rm my-network

# Create a network
docker network create app-network

# Start MySQL
docker run -d \
  --name mysql \
  --network app-network \
  -e MYSQL_ROOT_PASSWORD=123456 \
  mysql:8.0

# Start the app — it can reach the database using the hostname "mysql"
docker run -d \
  --name app \
  --network app-network \
  -e DATABASE_HOST=mysql \
  my-app

# A simple Dockerfile example
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "app.js"]

# Official Node.js image
FROM node:18-alpine

# Official Python image
FROM python:3.11-slim

# Minimal Alpine image
FROM alpine:3.18

# Build from scratch (empty base)
FROM scratch

# Shell form
RUN apt-get update && apt-get install -y curl

# Exec form
RUN ["apt-get", "install", "-y", "curl"]

# Multi-line (recommended — fewer layers)
RUN apt-get update && \
    apt-get install -y \
    curl \
    vim \
    git && \
    rm -rf /var/lib/apt/lists/*

# COPY — straightforward file copy
COPY package.json /app/
COPY . /app/

# ADD — also supports auto-extraction and remote URLs (not recommended; prefer COPY)
ADD archive.tar.gz /app/
ADD https://example.com/file.txt /app/

WORKDIR /app
# All subsequent commands run inside /app

ENV NODE_ENV=production
ENV APP_PORT=3000

# Multiple variables
ENV NODE_ENV=production \
    APP_PORT=3000

# Document which ports the container listens on
EXPOSE 3000
EXPOSE 80 443

# CMD — default command (easily overridden by docker run arguments)
CMD ["node", "app.js"]
CMD ["npm", "start"]

# ENTRYPOINT — fixed command (arguments are appended, not replaced)
ENTRYPOINT ["python", "app.py"]

ENTRYPOINT ["python", "app.py"]
CMD ["--port", "8080"]

# docker run myapp                  -> python app.py --port 8080
# docker run myapp --port 3000      -> python app.py --port 3000

# Stage 1: Build
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-alpine
WORKDIR /app
# Copy only the build output
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm install --production
EXPOSE 3000
CMD ["node", "dist/index.js"]

# 1. Use alpine base images
FROM node:18-alpine  # instead of node:18

# 2. Use multi-stage builds (see above)

# 3. Combine RUN commands and clean up caches
RUN apt-get update && \
    apt-get install -y curl && \
    rm -rf /var/lib/apt/lists/*

# 4. Use .dockerignore to exclude unnecessary files

node_modules
npm-debug.log
.git
.gitignore
README.md
.env
*.md

FROM node:18-alpine
WORKDIR /app

# Copy package.json first (rarely changes)
COPY package*.json ./
RUN npm install

# Then copy source code (changes often)
COPY . .

RUN npm run build

# 1. Don't run as root
FROM node:18-alpine
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

# 2. Never store secrets in the image
# Use environment variables or a secrets manager instead

# 3. Pin specific version tags, not "latest"
FROM node:18.19.0-alpine  # instead of node:latest

# The nightmare of managing multiple containers by hand
docker network create myapp
docker run -d --name mysql --network myapp -e MYSQL_ROOT_PASSWORD=123456 mysql:8.0
docker run -d --name redis --network myapp redis:alpine
docker run -d --name app --network myapp -p 3000:3000 -e DB_HOST=mysql -e REDIS_HOST=redis myapp

docker compose version

# Version declaration (optional in modern Docker Compose)
version: "3.8"

# Service definitions
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 123456

# Network definitions (optional)
networks:
  default:
    driver: bridge

# Volume definitions (optional)
volumes:
  db-data:

services:
  # Service name
  app:
    # Use a pre-built image
    image: node:18-alpine

    # Or build from a Dockerfile
    build:
      context: .
      dockerfile: Dockerfile

    # Container name
    container_name: my-app

    # Port mappings
    ports:
      - "3000:3000"      # host_port:container_port
      - "3001:3001"

    # Environment variables
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql
    # Or load from a file
    env_file:
      - .env

    # Volume mounts
    volumes:
      - ./src:/app/src        # bind mount
      - node_modules:/app/node_modules  # named volume

    # Service dependencies
    depends_on:
      - mysql
      - redis

    # Restart policy
    restart: unless-stopped

    # Network
    networks:
      - app-network

    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

services:
  app:
    networks:
      - frontend
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # internal only, no external access

services:
  mysql:
    volumes:
      - db-data:/var/lib/mysql

volumes:
  db-data:
    driver: local

version: "3.8"

services:
  app:
    build: .
    container_name: my-app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DB_HOST: mysql
      DB_PORT: 3306
      DB_NAME: myapp
      REDIS_HOST: redis
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_started
    volumes:
      - ./logs:/app/logs
    networks:
      - app-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    container_name: mysql-db
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-123456}
      MYSQL_DATABASE: myapp
    volumes:
      - mysql-data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: redis-cache
    volumes:
      - redis-data:/data
    networks:
      - app-network
    restart: unless-stopped

networks:
  app-network:
    driver: bridge

volumes:
  mysql-data:
  redis-data:

project/
├── docker-compose.yml
└── html/
    └── index.html

version: "3.8"

services:
  nginx:
    image: nginx:alpine
    container_name: nginx-web
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

<!DOCTYPE html>
<html>
<head>
    <title>Hello Docker</title>
</head>
<body>
    <h1>Hello from Docker!</h1>
</body>
</html>

docker compose up -d
# Visit http://localhost

version: "3.8"

services:
  wordpress:
    image: wordpress:latest
    container_name: wordpress
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress_password
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wordpress-data:/var/www/html
    depends_on:
      mysql:
        condition: service_healthy
    networks:
      - wp-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    container_name: wordpress-db
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress_password
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - wp-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

networks:
  wp-network:
    driver: bridge

volumes:
  wordpress-data:
  mysql-data:

docker compose up -d
# Visit http://localhost:8080 to complete the WordPress setup wizard

project/
├── docker-compose.yml
├── .env
├── Dockerfile
├── package.json
└── src/
    └── index.js

version: "3.8"

services:
  app:
    build: .
    container_name: node-app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      DB_HOST: mysql
      DB_PORT: 3306
      DB_NAME: ${DB_NAME:-myapp}
      DB_USER: ${DB_USER:-root}
      DB_PASSWORD: ${DB_PASSWORD:-123456}
      REDIS_HOST: redis
      REDIS_PORT: 6379
    volumes:
      - ./src:/app/src          # hot reload: mount source code
      - /app/node_modules       # protect node_modules
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - dev-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    container_name: mysql-db
    ports:
      - "3306:3306"  # expose for local dev tools
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-123456}
      MYSQL_DATABASE: ${DB_NAME:-myapp}
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - dev-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: redis-cache
    ports:
      - "6379:6379"  # expose for local dev tools
    volumes:
      - redis-data:/data
    networks:
      - dev-network
    restart: unless-stopped

networks:
  dev-network:
    driver: bridge

volumes:
  mysql-data:
  redis-data:

FROM node:18-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm install

# Copy source code
COPY . .

EXPOSE 3000

# Use nodemon for hot reload in development
CMD ["npm", "run", "dev"]

DB_NAME=myapp
DB_USER=root
DB_PASSWORD=123456

version: "3.8"

services:
  # Log aggregation
  loki:
    image: grafana/loki:2.9.0
    container_name: loki
    ports:
      - "3100:3100"
    volumes:
      - ./loki-config.yml:/etc/loki/local-config.yaml
      - loki-data:/loki
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - monitoring
    restart: unless-stopped

  # Log collection agent
  promtail:
    image: grafana/promtail:2.9.0
    container_name: promtail
    volumes:
      - ./promtail-config.yml:/etc/promtail/config.yml
      - /var/log:/var/log:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
    command: -config.file=/etc/promtail/config.yml
    networks:
      - monitoring
    restart: unless-stopped

  # Visualization dashboard
  grafana:
    image: grafana/grafana:10.0.0
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin123
    volumes:
      - grafana-data:/var/lib/grafana
    depends_on:
      - loki
    networks:
      - monitoring
    restart: unless-stopped

  # Demo app (generates logs)
  app:
    image: nginx:alpine
    container_name: demo-app
    ports:
      - "80:80"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - monitoring
    restart: unless-stopped

networks:
  monitoring:
    driver: bridge

volumes:
  loki-data:
  grafana-data:

auth_enabled: false

server:
  http_listen_port: 3100

ingester:
  lifecycler:
    ring:
      kvstore:
        store: inmemory
      replication_factor: 1
  chunk_idle_period: 5m
  chunk_retain_period: 30s

schema_config:
  configs:
    - from: 2020-10-24
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

storage_config:
  boltdb_shipper:
    active_index_directory: /loki/index
    cache_location: /loki/cache
    shared_store: filesystem
  filesystem:
    directory: /loki/chunks

limits_config:
  enforce_metric_name: false
  reject_old_samples: true
  reject_old_samples_max_age: 168h

chunk_store_config:
  max_look_back_period: 0s

table_manager:
  retention_deletes_enabled: false
  retention_period: 0s

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: containers
    static_configs:
      - targets:
          - localhost
        labels:
          job: containerlogs
          __path__: /var/lib/docker/containers/*/*log
    pipeline_stages:
      - json:
          expressions:
            output: log
            stream: stream
            time: time
      - output:
          source: output

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "100m"   # max size per log file
        max-file: "5"      # number of files to retain

services:
  app:
    # Run as non-root user
    user: "1000:1000"

    # Read-only filesystem
    read_only: true

    # Writable temp directory
    tmpfs:
      - /tmp

    # Security options
    security_opt:
      - no-new-privileges:true

# Check container logs
docker logs container_name

# Inspect container details
docker inspect container_name

# Common causes:
# 1. Port conflict
# 2. Volume permission issues
# 3. Dependency services not ready

# Check networks
docker network ls
docker network inspect network_name

# Test connectivity between containers
docker exec container1 ping container2

# Common causes:
# 1. Containers not on the same network
# 2. Typo in service name
# 3. Port not exposed

# Check disk usage
docker system df

# Clean up unused resources
docker system prune

# Clean everything (including unused images)
docker system prune -a

# Clean up volumes
docker volume prune

# Initialize Swarm
docker swarm init

# Deploy a stack
docker stack deploy -c docker-compose.yml myapp