Hoja de referencia Docker Compose: Servicios, volúmenes y redes

Docker Compose permite definir y ejecutar aplicaciones multi-contenedor con un solo archivo YAML.

Estructura del archivo

Un archivo docker-compose.yml consta de cuatro secciones principales:

# docker-compose.yml
services:      # Container definitions
  web:
    image: nginx:alpine
  api:
    build: ./api

volumes:       # Persistent storage
  db-data:

networks:      # Custom networks
  frontend:
  backend:

Configuración de servicios

Image vs Build

services:
  # Use a pre-built image
  db:
    image: postgres:16

  # Build from Dockerfile
  api:
    build: ./api

  # Build with custom options
  web:
    build:
      context: ./frontend
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production

Mapeo de puertos

services:
  web:
    ports:
      - "80:80"         # host:container
      - "443:443"
      - "3000:3000"     # Expose to localhost
      - "127.0.0.1:8080:80"  # Bind to specific interface

Variables de entorno

services:
  api:
    # Inline environment variables
    environment:
      - NODE_ENV=production
      - DB_HOST=db
      - DB_PORT=5432

    # From external file
    env_file:
      - .env
      - .env.production

Políticas de reinicio

services:
  web:
    restart: "no"             # Default: never restart
  api:
    restart: always           # Always restart
  db:
    restart: unless-stopped   # Restart unless manually stopped
  worker:
    restart: on-failure       # Restart only on failure
    # restart: on-failure:5   # Max 5 retries

Health Checks

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

Volúmenes

services:
  db:
    volumes:
      # Bind mount (host path : container path)
      - ./data:/var/lib/postgresql/data

      # Named volume
      - db-data:/var/lib/postgresql/data

      # Read-only mount
      - ./config:/etc/app/config:ro

volumes:
  db-data:           # Named volume declaration
    driver: local

Redes

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true    # No external access

Ejemplos de stacks completos

Node.js + MongoDB + Redis

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MONGO_URL=mongodb://mongo:27017/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      - mongo
      - redis

  mongo:
    image: mongo:7
    volumes:
      - mongo-data:/data/db
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  mongo-data:

Django + PostgreSQL

services:
  web:
    build: .
    command: gunicorn myapp.wsgi:application --bind 0.0.0.0:8000
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgres://postgres:secret@db:5432/myapp
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - static:/app/static

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pg-data:
  static:

WordPress + MySQL + phpMyAdmin

services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wp_user
      WORDPRESS_DB_PASSWORD: wp_pass
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp-content:/var/www/html
    depends_on:
      - db

  db:
    image: mysql:8
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wp_user
      MYSQL_PASSWORD: wp_pass
      MYSQL_ROOT_PASSWORD: root_secret
    volumes:
      - db-data:/var/lib/mysql

  phpmyadmin:
    image: phpmyadmin:latest
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db

volumes:
  wp-content:
  db-data:

Comandos CLI esenciales

Archivos de entorno (.env)

Docker Compose lee automáticamente un archivo .env:

# .env file
POSTGRES_VERSION=16
POSTGRES_PASSWORD=my_secret_pass
APP_PORT=3000

# docker-compose.yml
services:
  db:
    image: postgres:${POSTGRES_VERSION}
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  app:
    ports:
      - "${APP_PORT}:3000"

Errores comunes

FAQ