🐳 Guía de Docker y Docker Compose para Entornos de Desarrollo Local

Esta guía enseña paso a paso cómo configurar y virtualizar un entorno de desarrollo local completo para aplicaciones Next.js que requieran bases de datos como PostgreSQL y servidores de mensajería o caché como Redis, todo automatizado con Docker Compose.

🏗️ 1. ¿Por qué usar Docker en Desarrollo Local?

• Evita el "en mi máquina funciona": Todo el equipo de desarrollo corre exactamente la misma versión de base de datos, Node.js y dependencias del sistema.
• Aislamiento: No necesitas instalar Postgres, Redis o MySQL directamente en tu sistema operativo local, evitando conflictos de puertos y servicios en segundo plano.
• Inicio instantáneo: Puedes destruir y recrear la base de datos o el entorno entero con una sola línea de comandos.

📄 2. Creando el archivo docker-compose.yml

El archivo docker-compose.yml define los contenedores que forman parte de la arquitectura de la aplicación. Crea este archivo en la raíz de tu proyecto:

version: "3.8"

services:
  # Servicio 1: Base de datos PostgreSQL
  postgres-db:
    image: postgres:15-alpine
    container_name: mi_proyecto_postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: mi_password_secreto
      POSTGRES_DB: mi_base_datos
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  # Servicio 2: Servidor Redis
  redis-cache:
    image: redis:7-alpine
    container_name: mi_proyecto_redis
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

# Volúmenes persistentes para no perder los datos al apagar los contenedores
volumes:
  postgres_data:
    driver: local
  redis_data:
    driver: local

💡 Nota: Usamos las versiones con el sufijo -alpine porque son imágenes optimizadas y sumamente ligeras (pesan hasta un 80% menos que las imágenes estándar).

🛠️ 3. Comandos Esenciales para el Día a Día

A continuación se listan los comandos de Docker Compose más comunes que utilizarás en tu flujo de trabajo diario:

Levantar los Servicios

Levanta los contenedores en segundo plano (modo detached):

docker compose up -d

Si es la primera vez que los corres, Docker descargará automáticamente las imágenes oficiales.

Ver el Estado de los Contenedores

Verifica que tus contenedores se encuentren levantados y en qué puertos están escuchando:

docker compose ps

Ver Logs en Vivo

Útil para monitorear consultas entrantes a la base de datos o depurar errores de conexión:

docker compose logs -f

Si solo quieres ver los logs de la base de datos: docker compose logs -f postgres-db

Apagar los Servicios

Detiene y apaga los contenedores activos sin perder los datos de la base de datos (los volúmenes se preservan):

docker compose down

Limpieza Completa (Resetear Base de Datos)

Si necesitas hacer pruebas con un esquema de base de datos vacío o limpiar inconsistencias, puedes apagar los servicios y eliminar sus volúmenes asociados:

docker compose down -v

⚠️ Advertencia: Esto borrará de forma permanente todos los datos guardados en PostgreSQL y Redis.

🖥️ 4. Conectando tu Aplicación Next.js (.env.local)

Una vez que los contenedores están corriendo, puedes conectar tu aplicación Next.js local editando tus variables de entorno en tu archivo .env.local:

# Conexión a la base de datos de Docker
DATABASE_URL="postgresql://postgres:mi_password_secreto@127.0.0.1:5432/mi_base_datos?schema=public"

# Conexión al Redis de Docker
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

⚠️ 5. Solución de Problemas Comunes

1. El Puerto ya está en uso (port is already allocated)

• Causa: Tienes otra instancia local de Postgres o Redis instalada directamente en tu sistema operativo que ya está ocupando el puerto 5432 o 6379.
• Solución: Detén el servicio local de tu máquina.
  • En Windows (PowerShell Administrador):

    Stop-Service -Name "postgresql-x64-15" # Cambia la versión según corresponda
    

  • En Linux / macOS:

    sudo systemctl stop postgresql
    

2. Los datos desaparecen al apagar el contenedor

• Causa: Olvidaste declarar la sección de volumes en tu docker-compose.yml. Al apagarse el contenedor, todo lo que no esté en un volumen persistente se destruye.
• Solución: Asegúrate de mapear /var/lib/postgresql/data a un volumen local tal como se detalla en la sección 2.