6: Creación de Contenedores con Docker (Nginx, LocalStack, PostgreSQL, phpPgAdmin y Vite)

Duración estimada: 25 minutos (más tiempo de espera según conexión)

6.1 Introducción

En este tutorial vamos a levantar nuestro entorno de desarrollo completo utilizando Docker. Esto nos permitirá tener un ambiente consistente y aislado con todos los servicios que necesitamos para nuestro proyecto.

6.2 ¿Qué servicios vamos a levantar?

📦 Contenedores incluidos en nuestra arquitectura:

Servicio	Propósito	Puerto
Nginx	Servidor web y proxy inverso	80, 443
PostgreSQL	Base de datos relacional	5432
phpPgAdmin	Administrador visual de PostgreSQL	8080
LocalStack	Emulación de servicios AWS (S3)	4566
Vite	Servidor de desarrollo para assets	5173
PHP-FPM	Procesador de PHP	9000

6.3 Requisitos Previos

🛠️ Verifica que tienes instalado:

# Verificar Docker
docker --version
# Ejemplo: Docker version 28.0.0

# Verificar Docker Compose
docker-compose --version
# Ejemplo: Docker Compose version v2.24.0

# Verificar Node.js
node --version
# Ejemplo: v20.11.0

# Verificar NPM
npm --version
# Ejemplo: 10.2.4

⚠️ Importante: Node.js 20+ es necesario para que Inertia y Vite funcionen correctamente con la orquestación de Docker.

6.4 Levantando los Contenedores

🚀 Comandos para iniciar el entorno

Opción 1: Construcción y levantamiento completo (Recomendado para primera vez)

# Detener contenedores existentes y reconstruir todo
docker compose down && docker compose up --build -d

Opción 2: Solo levantamiento (si ya construiste antes)

# Levantar los contenedores en segundo plano
docker compose up -d

Opción 3: Con modo de desarrollo (para ver logs en tiempo real)

# Levantar mostrando los logs en la terminal
docker compose up --build

🔍 Explicación de las banderas:

Banda	Significado	Uso
`--build`	Reconstruir las imágenes	Cuando hay cambios en Dockerfile
`-d`	Modo detached (segundo plano)	Para que no bloquee la terminal
`--no-cache`	Sin caché de construcción	Cuando hay problemas de caché

6.5 Estructura del docker-compose.yml

📄 Archivo de configuración principal:

version: '3.8'

services:
  # 1. Servidor Web
  nginx:
    build:
      context: .
      dockerfile: .docker/nginx/Dockerfile
    ports:
      - "80:80"
    volumes:
      - ./:/var/www/html
    depends_on:
      - app
      - postgres
      - localstack

  # 2. Procesador PHP con Laravel
  app:
    build:
      context: .
      dockerfile: .docker/php/Dockerfile
    volumes:
      - ./:/var/www/html
    environment:
      - DB_HOST=postgres
      - DB_DATABASE=laravel
      - DB_USERNAME=laravel
      - DB_PASSWORD=secret

  # 3. Base de Datos PostgreSQL
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: laravel
      POSTGRES_USER: laravel
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  # 4. Administrador de PostgreSQL (phpPgAdmin)
  phppgadmin:
    image: dockage/phppgadmin:latest
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_USER: laravel
      POSTGRES_PASSWORD: secret
    ports:
      - "8080:80"
    depends_on:
      - postgres

  # 5. Emulador de AWS
  localstack:
    image: localstack/localstack:latest
    environment:
      - SERVICES=s3
      - AWS_DEFAULT_REGION=us-east-1
      - EDGE_PORT=4566
    ports:
      - "4566:4566"
    volumes:
      - localstack_data:/var/lib/localstack

  # 6. Servidor de Desarrollo Vite
  vite:
    build:
      context: .
      dockerfile: .docker/vite/Dockerfile
    ports:
      - "5173:5173"
    volumes:
      - ./:/var/www/html
    command: npm run dev

volumes:
  postgres_data:
  localstack_data:

6.6 ¿Qué está pasando en cada contenedor?

🔹 1. Nginx (Servidor Web)

Función: Recibe peticiones HTTP y las redirige a PHP-FPM
Archivos estáticos: Sirve CSS, JS, imágenes
Configuración: .docker/nginx/default.conf

🔹 2. PHP-FPM (Aplicación Laravel)

Función: Procesa el código PHP de Laravel
Framework: Laravel 11
Extensiones: pdo_pgsql, pdo_mysql, mbstring, etc.

🔹 3. PostgreSQL (Base de Datos)

Función: Almacenar datos de la aplicación
Credenciales por defecto:
- Base de datos: laravel
- Usuario: laravel
- Contraseña: secret

🔹 4. phpPgAdmin (Gestor de Base de Datos)

Función: Acceso visual a la base de datos
Acceso: http://localhost:8080
Ventaja: Similar a phpMyAdmin pero para PostgreSQL

🔹 5. LocalStack (Emulador AWS)

Función: Emular servicios de AWS localmente
Servicios disponibles: S3 (por ahora)
Ventaja: Desarrollo sin costos en la nube

🔹 6. Vite (Desarrollo Frontend)

Función: Servir y compilar assets de React/JS
Hot Reload: Recarga automática al guardar cambios
Puerto: 5173

6.7 Flujo de Trabajo del Entorno

6.8 Tiempos de Construcción

⏱️ ¿Cuánto tarda?

Etapa	Tiempo estimado	Depende de
Descarga de imágenes	2-10 minutos	Velocidad de internet
Construcción de imágenes	1-3 minutos	CPU del equipo
Inicio de contenedores	30 segundos	RAM/SSD

💡 Consejo: Mientras esperas, este es un buen momento para preparar un café ☕ o revisar la documentación del proyecto.

6.9 Verificación de Contenedores

📋 Comandos útiles para verificar el estado:

# Ver contenedores en ejecución
docker compose ps

# Ver logs en tiempo real
docker compose logs -f

# Ver logs de un servicio específico
docker compose logs app
docker compose logs postgres

# Acceder a la terminal de un contenedor
docker compose exec app bash
docker compose exec postgres psql -U laravel

✅ Checklist de verificación:

□
nginx está ejecutándose
□
app (PHP-FPM) está ejecutándose
□
postgres está ejecutándose
□
phppgadmin está ejecutándose
□
localstack está ejecutándose
□
vite está ejecutándose

6.10 Acceso a los Servicios

🌐 URLs y credenciales:

Servicio	URL	Credenciales
Aplicación	`http://localhost`	-
phpPgAdmin	`http://localhost:8080`	Usuario: `laravel` Contraseña: `secret`
API	`http://localhost/api`	-
Vite	`http://localhost:5173`	-
LocalStack S3	`http://localhost:4566`	-

6.11 Posibles Errores y Soluciones

❌ Error: "Port is already allocated"

# Solución: Cambiar el puerto en docker-compose.yml
ports:
  - "8081:80"  # Cambiar el puerto izquierdo

❌ Error: "Cannot connect to Docker daemon"

# En Linux
sudo systemctl start docker

# En Windows/Mac
# Reiniciar Docker Desktop

❌ Error: "Docker build failed"

# Limpiar caché y reconstruir
docker compose build --no-cache
docker compose up -d

❌ Error: "LocalStack service not starting"

# Aumentar memoria asignada a Docker
# En Docker Desktop -> Settings -> Resources
# Asignar al menos 4GB de RAM

6.12 Comandos Útiles para el Día a Día

🛠️ Recetario de comandos:

# Iniciar el entorno
docker compose up -d

# Detener el entorno
docker compose down

# Reiniciar un servicio específico
docker compose restart app

# Ver logs de todos los servicios
docker compose logs -f

# Limpiar todo y empezar de cero
docker compose down -v && docker compose up --build -d

# Ejecutar comandos de Laravel dentro del contenedor
docker compose exec app php artisan migrate
docker compose exec app php artisan tinker

# Acceder a PostgreSQL
docker compose exec postgres psql -U laravel -d laravel

📝 Ejercicio de la Clase

Para practicar lo aprendido:

Levanta los contenedores con el comando proporcionado
Verifica que todos los servicios estén en ejecución
Accede a phpPgAdmin y verifica la conexión
Explora los logs de cada contenedor
Prueba detener e iniciar los servicios

📚 Recursos Adicionales

¡Excelente! Has levantado tu entorno de desarrollo. Continúa al Tutorial 7: Configuración de Variables de Entorno y Dependencias

6. Creación contenedores nginx, Localstack,