Práctica 3.1: Despliegue de NGINX + PHP-FPM

Objetivos

• Instalar y configurar NGINX + PHP-FPM en un servidor Ubuntu.
• Desplegar una aplicación PHP mediante SFTP.
• Configurar NGINX como proxy inverso para PHP-FPM.
• Gestionar virtual hosts y permisos de archivos.
• Verificar que la aplicación funciona correctamente.
• Diagnosticar y resolver problemas comunes del stack.

Requisitos previos

• Un servidor (físico, virtual o en la nube) con Ubuntu 22.04 o 24.04 LTS y acceso por SSH.
• Usuario con privilegios de sudo en dicho servidor.
• Conexión SSH funcional desde tu máquina local al servidor.
• Aplicación PHP local en el directorio running-zones/.
• Configuración de NGINX local en nginx/runningzones.conf.

Transferencia de archivos con SFTP

¿Para qué necesitamos SFTP en esta práctica?

En esta práctica necesitas transferir ficheros desde tu máquina local al servidor remoto. Específicamente: - Los ficheros de tu aplicación PHP (running-zones/) - El fichero de configuración de NGINX (nginx/runningzones.conf)

SFTP (SSH File Transfer Protocol) es el método estándar y seguro para transferir ficheros a servidores Linux. Funciona sobre la misma conexión SSH que ya estás usando para acceder al servidor, por lo que: - No requiere instalar software adicional en el servidor - Todo el tráfico va cifrado (ficheros, contraseñas, nombres de archivo) - Usa el mismo puerto 22 que SSH, facilitando la configuración de firewalls

Comandos básicos de SFTP

Para conectarte al servidor desde tu máquina local:

sftp -i nginx-php-daw.pem ubuntu@<IP_SERVIDOR>

Una vez conectado, verás el prompt sftp>. Los comandos más importantes son:

Paso 1: Actualizar el sistema

Lo primero que hay que hacer siempre antes de instalar nada es actualizar los índices de paquetes y los propios paquetes del sistema. Esto garantiza que se instalan las últimas versiones disponibles y con sus parches de seguridad.

sudo apt update
sudo apt upgrade -y

• apt update: descarga los índices de paquetes desde los repositorios configurados. No instala nada, solo actualiza la lista de software disponible y sus versiones.
• apt upgrade -y: actualiza todos los paquetes instalados a sus últimas versiones. El flag -y responde afirmativamente a la confirmación.

Paso 2: Instalar NGINX y PHP-FPM

2.1. ¿Qué es NGINX?

NGINX (pronunciado "engine-x") es un servidor web y proxy inverso de alto rendimiento desarrollado por Igor Sysoev en 2004. A diferencia de Apache (que usa un modelo basado en procesos/hilos), NGINX usa una arquitectura orientada a eventos que le permite manejar miles de conexiones concurrentes con muy bajo consumo de memoria.

Funciones principales de NGINX: - Servir contenido estático (HTML, CSS, JavaScript, imágenes) - Actuar como proxy inverso para aplicaciones dinámicas - Balanceo de carga entre múltiples servidores - Caché de respuestas - Terminación SSL/TLS

2.2. ¿Qué es PHP-FPM y por qué existe?

NGINX no puede ejecutar PHP directamente. A diferencia de Apache con mod_php, NGINX necesita un procesador externo que interprete el código PHP y devuelva HTML.

¿Qué es mod_php?

mod_php era el módulo tradicional de Apache para ejecutar PHP. PHP se integraba directamente dentro de Apache como un módulo más. Esto tenía problemas: - Cada proceso de Apache cargaba PHP aunque solo sirviera imágenes o CSS - Consumo de memoria muy alto - Difícil de escalar en entornos compartidos

¿Qué hace PHP-FPM?

PHP-FPM (FastCGI Process Manager) es un gestor de procesos PHP que mantiene un pool de workers (procesos PHP) listos para procesar peticiones. Funciona como un "servidor de aplicaciones PHP" independiente:

graph LR
    Cliente[Cliente HTTP] -->|Petición PHP| NGINX
    NGINX -->|FastCGI| FPM[PHP-FPM]
    FPM -->|HTML generado| NGINX
    NGINX -->|Respuesta| Cliente

Cómo funciona: 1. NGINX recibe una petición para un archivo .php 2. NGINX envía la petición a PHP-FPM a través de un socket (Unix o TCP) 3. PHP-FPM asigna la petición a un worker PHP disponible 4. El worker ejecuta el código PHP y genera HTML 5. PHP-FPM devuelve el HTML a NGINX 6. NGINX envía la respuesta al cliente

Ventajas sobre mod_php: - Menos memoria: Solo los workers PHP consumen RAM, no todo el servidor web - Mejor rendimiento: NGINX sirve archivos estáticos (CSS, JS, imágenes) directamente sin pasar por PHP - Escalabilidad: El pool de workers se ajusta dinámicamente según la carga - Aislamiento: Cada sitio web puede tener su propio pool con configuración independiente

2.3. ¿Cómo se comunican NGINX y PHP-FPM?

graph LR
    NGINX[NGINX] -->|FastCGI| FPM[PHP-FPM]
    FPM -->|Respuestas| NGINX

Dos modos de comunicación:

1. Socket Unix (recomendado para mismo servidor):
2. Fichero especial en disco: /run/php/php8.5-fpm.sock
3. Más rápido que TCP (no hay overhead de red)
4. Solo funciona si NGINX y PHP-FPM están en la misma máquina

5. Permisos controlados via sistema de archivos

6. Socket TCP (para servidores separados):

7. Puerto de red: típicamente 9000 o 9001
8. Permite separar NGINX y PHP-FPM en máquinas diferentes
9. Útil para arquitecturas escalables
10. Requiere configuración de firewall

2.4. Instalación de los paquetes

Instala NGINX, PHP 8.5 y las extensiones necesarias:

sudo apt install -y \
  nginx \
  php8.5 \
  php8.5-fpm \
  php-cli \
  php-mbstring \
  php-xml \
  php-curl

Descripción de cada paquete:

2.5. Verificar que los servicios están activos

Tras la instalación, ambos servicios deberían haber arrancado automáticamente. Compruébalo:

sudo systemctl status nginx
sudo systemctl status php8.5-fpm

En la salida deberías ver active (running) en verde. Si no es así, arráncalos manualmente:

sudo systemctl start nginx
sudo systemctl start php8.5-fpm

Paso 3: Copiar la aplicación al servidor

3.1. Transferencia desde la máquina local con sftp

Desde tu terminal local (no desde dentro del servidor), transfiere los archivos de tu aplicación usando sftp.

Opción A: Modo interactivo

Conecta al servidor con SFTP:

sftp -i nginx-php-daw.pem ubuntu@<IP_SERVIDOR>

Una vez dentro de la sesión SFTP, verás un prompt sftp>. Desde ahí ejecuta:

mkdir /tmp/running-zones
cd /tmp/running-zones
lcd ruta/relativa/del/codigo
put -r *
exit

Explicación de cada comando:

Opción B: Modo batch (automatizado)

Crea un fichero llamado upload_app.txt con los comandos:

mkdir /tmp/running-zones
cd /tmp/running-zones
put -r ruta/relativa/del/codigo/*
exit

Y ejecútalo con el flag -b:

sftp -i nginx-php-daw.pem -b upload_app.txt ubuntu@<IP_SERVIDOR>

3.2. Mover los ficheros al directorio definitivo

Desde dentro del servidor, crea el directorio web y mueve los ficheros:

sudo apt install rsync -y

sudo mkdir -p /var/www/running-zones
sudo rsync -av /tmp/running-zones/* /var/www/running-zones/

El flag -p en mkdir crea los directorios padres si no existen y no da error si el directorio ya existe.

3.3. Ajustar permisos y propietario

Esto es crítico para que NGINX (que corre como usuario www-data) pueda leer los ficheros:

sudo chown -R www-data:www-data /var/www/running-zones
sudo chmod -R 755 /var/www/running-zones

• chown -R www-data:www-data: cambia recursivamente el propietario y grupo de todos los ficheros al usuario www-data, que es el que usa NGINX y PHP-FPM en Debian/Ubuntu.
• chmod -R 755: establece permisos rwxr-xr-x:
  • Propietario (www-data): lectura, escritura y ejecución.
  • Grupo (www-data): lectura y ejecución.
  • Otros: lectura y ejecución.
• 755 es el permiso estándar para directorios web: todo el mundo puede leer, pero solo el propietario puede modificar.

Paso 4: Instalar la configuración de NGINX

4.1. Transferir el fichero de configuración desde la máquina local

Desde tu terminal local, usa sftp para enviar el fichero al servidor:

sftp -i nginx-php-daw.pem ubuntu@<IP_SERVIDOR>

Una vez dentro de la sesión SFTP (sftp>):

put nginx/runningzones.conf /tmp/runningzones.conf
exit

O en un solo comando usando el modo batch:

echo "put nginx/runningzones.conf /tmp/runningzones.conf" | sftp -i nginx-php-daw.pem ubuntu@<IP_SERVIDOR>

put transfiere el fichero local al directorio remoto especificado.

4.2. Colocar el fichero en sites-available

Desde dentro del servidor:

sudo cp /tmp/runningzones.conf /etc/nginx/sites-available/runningzones

NGINX en Debian/Ubuntu usa una convención muy cómoda para gestionar los sitios web (virtual hosts):

Esta separación permite activar/desactivar sitios simplemente creando o borrando enlaces, sin tocar los ficheros originales.

4.3. Contenido del fichero runningzones.conf

server {
    listen 80;
    server_name _;

    root /var/www/running-zones;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
    }

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

Explicación directiva por directiva:

4.4. Activar el sitio

Crea un enlace simbólico desde sites-available a sites-enabled:

sudo ln -s \
  /etc/nginx/sites-available/runningzones \
  /etc/nginx/sites-enabled/

El comando ln -s crea un enlace simbólico (un acceso directo). NGINX, al arrancar, lee todo lo que haya en sites-enabled/.

4.5. Eliminar el sitio por defecto

Para evitar conflictos con el server_name _ de la configuración por defecto:

sudo rm -f /etc/nginx/sites-enabled/default

No borres el fichero de sites-available/default, solo el enlace de sites-enabled/. Así podrás reactivarlo si lo necesitas.

4.6. Verificar la sintaxis

Este paso es obligatorio antes de reiniciar. NGINX puede validar su propia configuración:

sudo nginx -t

Salida esperada:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Paso 5: Asegurar que el firewall permite el tráfico HTTP

El servidor debe tener los puertos necesarios abiertos en cualquier firewall que haya (firewall del sistema operativo, Security Groups del proveedor cloud, reglas de red de la VPC, etc.).

Los puertos que deben estar abiertos son:

Paso 6: Reiniciar servicios y verificar

6.1. Reiniciar los servicios

Reinicia ambos servicios para aplicar la nueva configuración:

sudo systemctl restart nginx
sudo systemctl restart php8.5-fpm

Alternativamente, puedes usar reload en lugar de restart. La diferencia:

Para NGINX es preferible usar reload:

sudo systemctl reload nginx

6.2. Verificar que NGINX responde

Desde dentro del servidor, comprueba que NGINX sirve contenido:

curl -s -o /dev/null -w "%{http_code}" http://localhost

• curl: herramienta de línea de comandos para hacer peticiones HTTP.
• -s: modo silencioso (no muestra la barra de progreso).
• -o /dev/null: descarta el cuerpo de la respuesta.
• -w "%{http_code}": muestra solo el código HTTP de estado.

Debe devolver 200.

6.3. Verificar que PHP se ejecuta correctamente

La prueba más importante: comprueba que un fichero .php se ejecuta y no se descarga como texto plano:

curl -s http://localhost/index.php | head -20

• Si ves HTML renderizado → PHP-FPM funciona correctamente.
• Si ves código PHP crudo (<?php ...) → NGINX no está pasando las peticiones a PHP-FPM. Revisa la directiva fastcgi_pass.
• Si ves 502 Bad Gateway → PHP-FPM no está corriendo o el socket no existe.

6.4. Comprobar qué sockets de PHP-FPM existen

Si tienes dudas sobre si el socket existe, puedes listarlo:

ls -la /run/php/

Deberías ver algo como:

srw-rw---- 1 www-data www-data 0 ... php8.5-fpm.sock

La s al principio indica que es un socket Unix.

Paso 7: Verificación final en el navegador

Abre un navegador y accede a:

http://<IP_SERVIDOR>/

Deberías ver tu aplicación Running Zones funcionando correctamente.

7.1. Verificación completa con curl

Para hacer pruebas más exhaustivas sin necesidad de un navegador, puedes usar curl con diferentes opciones:

Probar que el sitio responde correctamente:

# Ver código de estado HTTP
curl -I http://localhost

# Ver headers completos de la respuesta
curl -v http://localhost

# Descargar y mostrar solo las primeras líneas
curl -s http://localhost/index.php | head -30

Probar con un nombre de dominio específico:

Si tu configuración de NGINX usa server_name runningzones.daw, necesitas indicar a curl que use ese nombre de dominio, aunque accedas por IP:

# Usando el header Host
curl -H "Host: runningzones.daw" http://<IP_SERVIDOR>/

# Usando --resolve (recomendado)
curl --resolve runningzones.daw:80:<IP_SERVIDOR> http://runningzones.daw/

7.2. Verificación desde un contenedor Docker

En entornos donde no tienes acceso a /etc/hosts del sistema host (por ejemplo, en ordenadores corporativos con restricciones, o cuando trabajas en equipos compartidos), puedes usar un contenedor Docker para hacer las pruebas.

Opción 1: Usar --resolve dentro del contenedor

docker run --rm curlimages/curl \
  --resolve runningzones.daw:80:<IP_SERVIDOR> \
  http://runningzones.daw/

Opción 2: Usar --add-host en el contenedor

Docker permite inyectar entradas DNS en el contenedor sin modificar el /etc/hosts del host:

docker run --rm \
  --add-host runningzones.daw:<IP_SERVIDOR> \
  curlimages/curl \
  http://runningzones.daw/

Verificar múltiples aspectos desde Docker:

# Crear un alias para simplificar
alias test-runningzones='docker run --rm --add-host runningzones.daw:<IP_SERVIDOR> curlimages/curl'

# Probar código de estado
test-runningzones -I http://runningzones.daw/

# Probar que PHP se ejecuta
test-runningzones -s http://runningzones.daw/index.php | head -20

# Probar un recurso estático
test-runningzones -I http://runningzones.daw/css/style.css

docker run --rm \
  --add-host runningzones.daw:host.docker.internal \
  curlimages/curl \
  http://runningzones.daw/

Paso 8: Diagnóstico y resolución de problemas

Cuando algo falla, los logs son tu mejor aliado. Aquí tienes una tabla de síntomas, causas y soluciones:

Comandos para revisar logs

# Logs de errores de NGINX (en tiempo real)
sudo tail -f /var/log/nginx/error.log

# Logs de acceso de NGINX (quién visita tu web)
sudo tail -f /var/log/nginx/access.log

# Logs de PHP-FPM (errores de la aplicación PHP)
sudo journalctl -u php8.5-fpm -n 50 --no-pager

# Log específico de PHP-FPM si está configurado
sudo tail -f /var/log/php8.5-fpm.log

Arquitectura del conjunto

Para que quede claro cómo encajan las piezas:

graph LR
    Navegador[Navegador] -->|HTTP :80| NGINX[NGINX]
    NGINX -->|lee ficheros| WWW[/var/www/running-zones/]
    NGINX -->|FastCGI| FPM[PHP-FPM]
    FPM -->|Salida PHP| NGINX
    WWW -.->|también los ejecuta| FPM

1. El cliente pide http://servidor/index.php.
2. NGINX recibe la petición, ve que termina en .php, y la pasa por el socket FastCGI a PHP-FPM.
3. PHP-FPM ejecuta index.php en uno de sus procesos worker y genera HTML.
4. NGINX recibe ese HTML y se lo devuelve al cliente.

Para ficheros estáticos (CSS, JS, imágenes), NGINX los sirve directamente sin pasar por PHP-FPM, lo que lo hace muy eficiente.

Propuesta: Despliegue con PHP-FPM en una máquina distinta

Como extensión de esta práctica, realiza el mismo despliegue pero con NGINX y PHP-FPM en máquinas separadas.

Configuración básica

En la máquina con PHP-FPM:

Edita /etc/php/8.5/fpm/pool.d/www.conf y cambia el socket Unix por TCP:

listen = 0.0.0.0:9000

Reinicia PHP-FPM:

sudo systemctl restart php8.5-fpm

En la máquina con NGINX:

Modifica la configuración del virtual host para apuntar a la IP de la máquina con PHP-FPM.

Recarga NGINX:

sudo systemctl reload nginx

Consideraciones adicionales:

• Sube los ficheros de la aplicación a la máquina con PHP-FPM usando SFTP.
• Abre el puerto 9000 en el firewall de la máquina con PHP-FPM (solo desde el SG de la máqina de NGINX).
• Verifica con curl que la aplicación funciona correctamente.