Dominando la Configuración de Nginx: Directivas Esenciales Explicadas

La configuración de Nginx se vuelve mucho más fácil una vez que entiendes dónde puede vivir cada directiva. Si tu regla proxy_pass, root o try_files está en el contexto incorrecto, Nginx puede rechazar la configuración o manejar las solicitudes de una manera que no esperabas.

Esta guía explica las directivas esenciales que utilizarás al servir archivos estáticos, hacer proxy inverso de una aplicación, habilitar la compresión y recargar cambios de forma segura.

La Estructura de Configuración de Nginx

Los archivos de configuración de Nginx generalmente se encuentran en /etc/nginx/ en los paquetes de Linux. El archivo principal suele ser /etc/nginx/nginx.conf, y a menudo incluye archivos de /etc/nginx/conf.d/. Los paquetes de Debian y Ubuntu comúnmente usan sites-available/ y sites-enabled/; muchas otras distribuciones no.

La configuración es jerárquica, organizada en bloques o directivas. Los bloques clave incluyen:

events: Configura el procesamiento de conexiones.
http: Contiene configuraciones HTTP generales y servidores virtuales.
server: Define un servidor virtual para un puerto y nombre de host.
location: Elige cómo manejar las URI de solicitud coincidentes.

Las directivas son pares clave-valor que controlan el comportamiento de Nginx. Pueden ser globales o estar anidadas dentro de bloques.

Directivas Esenciales Explicadas

El Bloque `http`

El bloque http engloba configuraciones que se aplican globalmente al tráfico HTTP. Aquí es donde definirás configuraciones comunes para tu servidor web.

include: Esta directiva te permite incluir otros archivos de configuración, ayudando a modularizar tu configuración. Se usa comúnmente para separar configuraciones para diferentes sitios web o aplicaciones.
```
http {
    include       mime.types;
    default_type  application/octet-stream;

    # Incluir configuraciones de servidor desde el directorio conf.d
    include /etc/nginx/conf.d/*.conf;
}
```

log_format: Define formatos de registro personalizados para los registros de acceso y error de Nginx. Esto es esencial para un registro y análisis detallados.

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;
    error_log   /var/log/nginx/error.log;
    # ... otras directivas http
}

sendfile: Optimiza las transferencias de archivos permitiendo que el kernel envíe archivos directamente desde el disco al cliente, evitando el espacio de usuario. Establécelo en on para rendimiento.
```
http {
    sendfile        on;
    # ...
}
```
tcp_nopush y tcp_nodelay: Ajustan el comportamiento de TCP para respuestas HTTP. tcp_nopush se usa comúnmente con sendfile para optimizar el envío de paquetes, mientras que tcp_nodelay ayuda a evitar retrasos en conexiones persistentes.
```
http {
    tcp_nopush     on;
    tcp_nodelay    on;
    # ...
}
```

El Bloque `server`

Cada bloque server define un servidor virtual, permitiendo que Nginx maneje solicitudes para diferentes nombres de dominio o direcciones IP en el mismo servidor.

listen: Especifica la dirección IP y/o el puerto en el que el servidor escuchará las conexiones entrantes.
```
server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    # ...
}
```
server_name: Define los nombres del servidor. Nginx usa esto para coincidir con el encabezado Host de la solicitud entrante.
```
server {
    listen 80;
    server_name mydomain.org *.mydomain.org;
    # ...
}
```
root: Establece la raíz del documento. Nginx construye la ruta del archivo añadiendo la URI de solicitud a este directorio.
```
server {
    listen 80;
    server_name localhost;
    root /var/www/html;
    index index.html index.htm;
    # ...
}
```
index: Especifica el archivo predeterminado a servir cuando se solicita un directorio.
```
server {
    # ...
    index index.html index.htm default.html;
    # ...
}
```

error_page: Define páginas de error personalizadas para códigos de estado HTTP específicos.

server {
    # ...
    error_page 404 /404.html;
    location = /404.html {
        root /usr/share/nginx/html;
        internal;
    }
    # ...
}

El Bloque `location`

El bloque location se utiliza para coincidir con las URI de solicitud y determinar cómo Nginx debe procesarlas. Aquí es donde configuras el enrutamiento para diferentes partes de tu aplicación.

Coincidencia de URI: Las ubicaciones pueden coincidir con cadenas exactas, prefijos o expresiones regulares. Las coincidencias exactas usan =, las expresiones regulares usan ~ o ~*, y los prefijos simples coinciden por prefijo de URI.

location /images/ {
    # Directivas para solicitudes que comienzan con /images/
}

location = /favicon.ico {
    # Coincidencia exacta para /favicon.ico
}

location ~ \.php$ {
    # Coincidencia regex para archivos que terminan en .php
}

proxy_pass: Reenvía solicitudes a un servidor ascendente. Ten cuidado con la barra inclinada final porque cambia cómo Nginx reescribe el prefijo coincidente.

location /api/ {
    proxy_pass http://backend-service:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

alias: Asigna una ubicación a una ruta del sistema de archivos sin añadir la URI original completa. A menudo se usa para activos estáticos almacenados fuera de la raíz del documento principal.
```
location /static/ {
    alias /var/www/app/assets/;
}
```
Con alias, incluye la barra inclinada final tanto en la ubicación como en la ruta para asignaciones de directorio. alias reemplaza el prefijo de ubicación coincidente con la ruta del alias, mientras que root añade la URI a la ruta raíz.
try_files: Verifica la existencia de archivos en un orden especificado y sirve el primero que se encuentra, o devuelve un código/URI especificado.
```
location / {
    try_files $uri $uri/ /index.html;
}
```
Esto es común para aplicaciones de una sola página. Si un archivo o directorio solicitado no existe, Nginx sirve index.html para que el enrutador del lado del cliente pueda manejar la ruta.

Directivas de Seguridad y Rendimiento

ssl_certificate y ssl_certificate_key: Esenciales para configurar HTTPS. Estas directivas apuntan a tu certificado SSL y archivos de clave privada.

server {
    listen 443 ssl;
    server_name secure.example.com;

    ssl_certificate /etc/letsencrypt/live/secure.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/secure.example.com/privkey.pem;

    # ... otras configuraciones SSL
}

gzip: Habilita o deshabilita la compresión gzip para tipos de respuesta seleccionados. A menudo reduce el tamaño de transferencia de activos de texto, pero evita comprimir archivos ya comprimidos como la mayoría de las imágenes.

http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    # ...
}

expires: Controla los encabezados de caché para activos estáticos. Usa tiempos de vida de caché largos para archivos con huella digital, y tiempos más cortos para archivos que mantienen la misma URL entre implementaciones.
```
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 30d;
    add_header Cache-Control "public";
}
```

Comandos Comunes de Nginx

Para gestionar Nginx y aplicar cambios de configuración, usarás frecuentemente estos comandos:

Probar configuración: Verifica errores de sintaxis en tus archivos de configuración de Nginx.
```
sudo nginx -t
```
Recargar configuración: Recarga la configuración de Nginx de forma segura sin cerrar conexiones activas.
```
sudo systemctl reload nginx
# o
sudo service nginx reload
```

Reiniciar Nginx: Detiene y luego inicia el servicio de Nginx.

sudo systemctl restart nginx
# o
sudo service nginx restart

Verificar estado: Muestra el estado actual del servicio de Nginx.
```
sudo systemctl status nginx
# o
sudo service nginx status
```

Un Ejemplo Mínimo Funcional

Este ejemplo sirve una aplicación de una sola página desde el disco y hace proxy de las solicitudes de API a un servidor de aplicaciones:

server {
    listen 80;
    server_name example.com;

    root /var/www/example.com;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Ejecuta sudo nginx -t antes de cada recarga. Ese único hábito detecta errores de sintaxis antes de que se conviertan en tiempo de inactividad.

Conclusión

La mayoría de los errores de Nginx provienen del manejo del contexto y las rutas. Coloca las configuraciones HTTP generales en http, las reglas específicas del host en server, el enrutamiento de URI en location, y prueba cada cambio con nginx -t antes de recargar.