🌐 NGINX con Laravel en Docker (Alpine)

Este documento explica cómo instalar, configurar y validar NGINX en un contenedor Alpine, integrándolo con Laravel + PHP-FPM, aplicando buenas prácticas como separación de archivos de configuración (sites-available y sites-enabled), gestión de errores personalizados y (opcional) redirección HTTPS. Está alineado con los criterios de evaluación de la UF2 (Implementación) y UF4 (Documentación).

🧱 1. Acceder al contenedor `nginx`

Primero accedemos al contenedor NGINX para comenzar la instalación y configuración:

docker exec -it nginx sh

🔍 Este comando nos abre un shell interactivo dentro del contenedor, desde donde ejecutaremos los siguientes pasos.

🛠️ 2. Instalar NGINX

Dentro del contenedor ejecutamos:

apk update
apk add --no-cache nginx nano

nginx: instala el servidor HTTP.
nano: editor de texto para modificar configuraciones.

📌 El flag --no-cache evita guardar temporalmente los archivos de instalación, lo que ahorra espacio en Alpine.

📁 3. Crear estructura de configuración modular

Creamos los directorios para seguir buenas prácticas de configuración:

mkdir -p /etc/nginx/sites-available
mkdir -p /etc/nginx/sites-enabled

🔍 Esto permite tener archivos separados por proyecto o aplicación y luego enlazarlos fácilmente.

📝 4. Crear el archivo `laravel.conf`

Creamos un archivo personalizado de configuración en:

nano /etc/nginx/sites-available/laravel.conf

Contenido del archivo:

server {
    listen 80;
    server_name localhost;

    root /var/www/html/josue-app/public;
    index index.php index.html;

    error_log /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;

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

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

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

🧠 Explicación:

root: apunta al public/ de Laravel, donde está el index.php.
fastcgi_pass laravel:9000;: indica que PHP-FPM se ejecuta en el contenedor laravel por el puerto 9000.
try_files: permite que Laravel controle las rutas no físicas.

🔗 5. Activar la configuración

Creamos un enlace simbólico para activar el sitio:

ln -s /etc/nginx/sites-available/laravel.conf /etc/nginx/sites-enabled/

Luego editamos el archivo global de configuración de NGINX:

nano /etc/nginx/nginx.conf

Dentro del bloque http {}, añadimos:

include /etc/nginx/sites-enabled/*.conf;

🔁 Esto permite que se lean automáticamente todos los archivos activos desde sites-enabled.

🧪 6. Validar y reiniciar NGINX

Validamos que todo esté bien configurado:

nginx -t

Si el mensaje indica “syntax is ok”, reiniciamos NGINX:

pkill nginx
nginx

🧠 En Alpine no se usa systemctl, así que pkill mata el proceso anterior y nginx lo inicia de nuevo.

🔐 7. Gestión de errores personalizados (HTML)

Creamos una carpeta para páginas de error:

mkdir -p /var/www/html/errors

Creamos el archivo 404.html:

<!-- /var/www/html/errors/404.html -->
<!DOCTYPE html>
<html lang="es">
<head><meta charset="UTF-8"><title>Error 404</title></head>
<body>
  <h1>❌ Error 404 - Página no encontrada</h1>
  <a href="/">Volver al inicio</a>
</body>
</html>

En laravel.conf, añadimos dentro del bloque server:

error_page 404 /errors/404.html;
location = /errors/404.html {
    root /var/www/html;
    internal;
}

🔍 Esto hace que, cuando ocurra un 404, se muestre tu propia página HTML.

🧠 8. Gestión dinámica de errores con JavaScript

Puedes capturar errores con JS en el frontend y mostrar mensajes:

fetch('/admin')
  .then(res => {
    if (!res.ok) {
      document.querySelector('#error').innerText = `Código de error: ${res.status}`;
    }
  });

Esto permite mejorar la experiencia de usuario en apps SPA o en Laravel + Vue/React.

📡 9. (Opcional) Redirección de HTTP a HTTPS

Para simular SSL o redirigir tráfico de forma segura, añade al inicio del archivo laravel.conf:

server {
    listen 80;
    return 301 https://$host$request_uri;
}

⚠️ Solo funciona si tienes certificados SSL o estás usando un entorno de pruebas con HTTPS.

🎉 10. Laravel visible en navegador

Si todo está correctamente configurado, podrás abrir tu navegador y acceder a:

http://localhost:8080

Deberías ver la página de bienvenida de Laravel servida por NGINX a través de PHP-FPM.

📸 COLOCA AQUÍ ESTA CAPTURA:

![Laravel funcionando correctamente](img/laravel-acceso.png)

Este es el momento clave para documentar que el sistema completo Laravel + NGINX + PHP-FPM funciona correctamente.

✅ Checklist Evaluación UF2/UF4

Requisito	Cumplido
NGINX instalado y funcional en Docker	✅
sites-available + sites-enabled usados	✅
Laravel servido correctamente	✅
Gestión de errores HTML personalizada	✅
Gestión de errores dinámica vía JS	✅
Redirección HTTP → HTTPS (simulada)	✅
Documentación clara con capturas	✅