7. Explicación código descargado

 

7: Explicación del Código Descargado

Duración estimada: 30 minutos

---

7.1 Introducción

En este tutorial vamos a explorar en detalle la estructura del proyecto que descargaste. Entender cada componente y su propósito es fundamental para que puedas modificar, extender y mantener tu aplicación con confianza.

---

7.2 Estructura General del Proyecto

📁 Árbol de directorios principal

text

📂 proyecto-desarrollo/
├── 📄 docker-compose.yml      # Orquestación principal de Docker
├── 📂 docker/                 # Configuraciones de cada contenedor
│   ├── 📂 app/               # Configuración de PHP
│   ├── 📂 nginx/             # Configuración del servidor web
│   ├── 📂 vite/              # Configuración del servidor de desarrollo
│   └── 📂 supervisor/        # Configuración de procesos en segundo plano
├── 📂 laravel/               # Proyecto Laravel (el código de tu app)
│   ├── 📂 app/
│   ├── 📂 config/
│   ├── 📂 database/
│   ├── 📂 resources/
│   ├── 📂 routes/
│   └── 📄 .env.example
├── 📂 node_modules/          # Dependencias de Node (se genera al instalar)
└── 📄 .env.local            # Variables de entorno locales

💡 Nota: La carpeta laravel/ contiene el proyecto que construiremos paso a paso. Si quieres tener un respaldo del código completo, haz una copia de seguridad antes de empezar a modificar.

---

7.3 Análisis del docker-compose.yml

🐳 Orquestación de contenedores

El archivo docker-compose.yml es el corazón de nuestro entorno de desarrollo. Define todos los servicios que necesitamos.

📋 Resumen de servicios:

Servicio	Contenedor	Propósito
app	PHP-FPM 8.4	Procesa el código PHP de Laravel
nginx	Nginx	Servidor web y proxy
postgres	PostgreSQL 15	Base de datos
pgadmin	phpPgAdmin	Gestor visual de BD
localstack	LocalStack	Emulador de AWS
vite	Node + Vite	Servidor de desarrollo frontend

🔍 Detalle de cada servicio

1️⃣ Servicio app (PHP-FPM)

yaml

app:
  build:
    context: .
    dockerfile: docker/app/Dockerfile
  container_name: laravel_app
  ports:
    - "8001:8001"
  networks:
    custom_network:
      ipv4_address: 172.20.0.10
  volumes:
    - ./laravel:/var/www/html
  environment:
    - TZ=America/Santiago

¿Qué hace?

• Usa PHP 8.4 (última versión estable)

• Instala extensiones necesarias (PostgreSQL, GD, etc.)

• Configura el huso horario

• Monta el código de Laravel en el contenedor

2️⃣ Servicio nginx (Servidor Web)

yaml

nginx:
  build:
    context: .
    dockerfile: docker/nginx/Dockerfile
  container_name: laravel_nginx
  ports:
    - "8080:80"
  depends_on:
    - app
  networks:
    - custom_network

¿Qué hace?

• Sirve los archivos estáticos (CSS, JS, imágenes)

• Redirige las peticiones PHP a PHP-FPM

• Configuración en docker/nginx/default.conf

3️⃣ Servicio postgres (Base de Datos)

yaml

postgres:
  image: postgres:15
  container_name: laravel_postgres
  environment:
    POSTGRES_DB: laravel
    POSTGRES_USER: user
    POSTGRES_PASSWORD: sql
  ports:
    - "5432:5432"
  volumes:
    - pgdata:/var/lib/postgresql/data

Credenciales por defecto:

• Base de datos: laravel

• Usuario: user

• Contraseña: sql

4️⃣ Servicio pgadmin (Gestor de BD)

yaml

pgadmin:
  image: dockage/phppgadmin:latest
  container_name: laravel_pgadmin
  environment:
    POSTGRES_HOST: postgres
    POSTGRES_USER: user
    POSTGRES_PASSWORD: sql
  ports:
    - "5050:80"

Acceso: http://localhost:5050

5️⃣ Servicio localstack (Emulador AWS)

yaml

localstack:
  image: localstack/localstack:latest
  container_name: laravel_localstack
  environment:
    - SERVICES=s3,sqs,lambda,ses,dynamodb
    - AWS_DEFAULT_REGION=us-east-1
  ports:
    - "4566:4566"

Servicios disponibles:

• ✅ S3 (Almacenamiento)

• ✅ SQS (Colas)

• ✅ Lambda (Funciones serverless)

• ✅ SES (Email)

• ✅ DynamoDB (NoSQL)

6️⃣ Servicio vite (Desarrollo Frontend)

yaml

vite:
  build:
    context: .
    dockerfile: docker/vite/Dockerfile
  container_name: laravel_vite
  ports:
    - "5173:5173"
  command: npm run dev

¿Qué hace?

• Compila assets de React en tiempo real

• Hot Reload automático

• Puerto: 5173

---

7.4 Configuración de la Red

🌐 Red personalizada para evitar conflictos

yaml

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16
          gateway: 172.20.0.1

Ventajas de esta configuración:

• ✅ Evita conflictos con VPNs

• ✅ IPs fijas para cada contenedor

• ✅ Comunicación interna estable

---

7.5 Archivos de Configuración Importantes

📄 Dockerfile de PHP (docker/app/Dockerfile)

dockerfile

FROM php:8.4-fpm

# Instalación de dependencias del sistema
RUN apt-get update && apt-get install -y \
    git \
    curl \
    nano \
    libpq-dev \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# Instalación de extensiones PHP
RUN docker-php-ext-install pdo pdo_pgsql pgsql \
    bcmath ctype fileinfo mbstring gd

# Instalación de Composer
COPY --from=composer:2.6 /usr/bin/composer /usr/bin/composer

# Configuración de huso horario (opcional)
ENV TZ=America/Santiago

📄 Configuración de Nginx (docker/nginx/default.conf)

nginx

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

📄 Configuración de Supervisor (docker/supervisor/supervisor.conf)

ini

[supervisord]
nodaemon=true

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/worker.log

---

7.6 Verificación de Contenedores Levantados

✅ Estado actual

bash

# Ver contenedores activos
docker compose ps

# Resultado esperado:
NAME                STATUS              PORTS
laravel_app         Up 2 hours          8001/tcp
laravel_nginx       Up 2 hours          0.0.0.0:8080->80/tcp
laravel_postgres    Up 2 hours          0.0.0.0:5432->5432/tcp
laravel_pgadmin     Up 2 hours          0.0.0.0:5050->80/tcp
laravel_localstack  Up 2 hours          0.0.0.0:4566->4566/tcp
laravel_vite        Up 2 hours          0.0.0.0:5173->5173/tcp

🔍 Comandos útiles para diagnosticar

bash

# Verificar IPs de los contenedores
docker inspect laravel_app | grep IPAddress

# Probar comunicación entre contenedores
docker compose exec app ping postgres

# Ver logs específicos
docker compose logs app
docker compose logs nginx
docker compose logs postgres

---

7.7 Consideraciones Importantes

⚠️ Puntos clave a recordar

1. Credenciales en duro: Las credenciales en el docker-compose.yml son solo para desarrollo local. Nunca subas estos valores a producción.

2. Carpeta laravel/: Contiene el código de la aplicación. Puedes:

   • Usar el código ya construido (haz una copia)

   • Borrarlo y empezar desde cero

3. Volúmenes persistentes:

   • pgdata: Datos de PostgreSQL

   • localstack_data: Datos de LocalStack

4. Puertos expuestos:

   • 8080: Aplicación web

   • 5050: phpPgAdmin

   • 5432: PostgreSQL

   • 4566: LocalStack

   • 5173: Vite

---

7.8 Solución de Problemas Comunes

❌ Error: "File not found" en Nginx

Causa: La carpeta laravel/ está vacía o no contiene el proyecto.

Solución:

bash

# Crear el proyecto Laravel dentro del contenedor
docker compose exec app composer create-project laravel/laravel .

# O copiar un proyecto existente
cp -r /ruta/a/tu/proyecto/laravel/ .

❌ Error: No se puede conectar a PostgreSQL

Causa: PostgreSQL no está listo cuando la app intenta conectarse.

Solución:

yaml

# Agregar healthcheck en docker-compose.yml
postgres:
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U user"]
    interval: 10s
    timeout: 5s
    retries: 5

❌ Error: Vite no inicia correctamente

Causa: Node_modules no instalados.

Solución:

bash

# Instalar dependencias dentro del contenedor
docker compose exec vite npm install

---

7.9 Próximos Pasos

🎯 Lo que haremos a continuación

1. Configurar variables de entorno (.env)

2. Instalar dependencias de PHP y Node

3. Ejecutar migraciones de base de datos

4. Probar la aplicación en el navegador

---

📝 Ejercicio de la Clase

Para afianzar los conceptos:

1. Explora cada archivo de configuración

2. Modifica el puerto de nginx de 8080 a 8081 y verifica el cambio

3. Agrega una extensión PHP adicional en el Dockerfile

4. Prueba la conexión entre contenedores usando ping

---

📚 Recursos Adicionales

• Documentación oficial de Docker Compose

• Guía de Laravel con Docker

• Documentación de LocalStack

• phpPgAdmin en GitHub

---

¡Excelente! Ahora entiendes la arquitectura de tu proyecto. Continúa al Tutorial 8: Configuración de Variables de Entorno y Dependencias