Estructura de configuración de Nginx y jerarquía de directivas

Sintaxis de configuración: cómo “lee” Nginx tus archivos

La configuración de Nginx se compone de directivas (instrucciones) y contextos (bloques). La sintaxis es consistente: cada directiva termina en ; y cada bloque abre con { y cierra con }.

# Directiva simple (termina en punto y coma)user nginx;worker_processes auto;# Bloque (contexto)http {    # directivas y sub-bloques aquí}

Reglas rápidas para evitar errores:

• Siempre termina directivas con ;.
• Los bloques siempre usan llaves { } balanceadas.
• Las rutas suelen ser absolutas (por ejemplo /var/www/site), y deben existir y tener permisos correctos.
• Los comentarios empiezan con # y van hasta el final de la línea.

Directivas comunes que verás en este capítulo

• include: inserta otros archivos de configuración.
• listen: puerto/IP donde el servidor acepta conexiones.
• server_name: nombres de host que hacen match con el bloque server.
• root: directorio base para servir archivos.
• index: archivo(s) por defecto cuando se solicita un directorio.

Jerarquía de contextos y herencia de valores

Nginx organiza la configuración en una jerarquía. Los contextos más relevantes para servir HTTP son:

• main: nivel global (fuera de cualquier bloque). Controla aspectos generales (usuario, procesos, logs globales, etc.).
• http: configuración para el tráfico HTTP/HTTPS. Aquí se definen defaults y se agrupan servidores virtuales.
• server: un “virtual host”. Define cómo responder para un conjunto de server_name y listen.
• location: reglas dentro de un server para rutas específicas (por ejemplo /, /images/, ~ \.php$).

Muchas directivas se heredan: si defines un valor en http, los server y location lo usan como valor por defecto, a menos que lo sobrescribas en un nivel más específico.

Precedencias: qué pasa si hay valores distintos

Regla práctica: si una directiva es válida en varios contextos y aparece en varios niveles, el nivel más específico suele prevalecer. Por ejemplo, root puede definirse en http, server y location. Si defines root en server y luego otro root en un location, para las peticiones que entren a ese location se usará el root del location.

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

http {    root /var/www/default;    server {        server_name ejemplo.local;        root /var/www/ejemplo;        location /assets/ {            root /var/www/estaticos;        }    }}

En el ejemplo, una petición a / usará /var/www/ejemplo, pero una petición a /assets/logo.png usará /var/www/estaticos (ojo: con root en location, Nginx concatena el URI completo; esto puede sorprender. En muchos casos alias es más apropiado para mapear rutas, pero aquí nos enfocamos en entender la jerarquía).

Cómo decide Nginx qué server y qué location usar

Primero, Nginx elige el bloque server según listen (IP/puerto) y server_name (host). Luego, dentro de ese server, selecciona el location que mejor coincide con la URL solicitada.

Reglas típicas de location (simplificadas):

• location = /ruta: coincidencia exacta (muy específica).
• location /ruta: prefijo (coincide con todo lo que empiece por ese prefijo).
• location ^~ /ruta: prefijo con prioridad sobre regex.
• location ~ patron: regex sensible a mayúsculas/minúsculas.
• location ~* patron: regex insensible a mayúsculas/minúsculas.

server {    listen 80;    server_name ejemplo.local;    location = /health { return 200; }    location / {        # sitio normal    }    location ~* \.(png|jpg|css|js)$ {        # estáticos por extensión    }}

Organización de archivos: buenas prácticas para crecer sin caos

En distribuciones comunes, el archivo principal suele incluir otros archivos. Un patrón típico es:

# Dentro de nginx.conf (en el contexto http)http {    include /etc/nginx/mime.types;    include /etc/nginx/conf.d/*.conf;    # o en Debian/Ubuntu: include /etc/nginx/sites-enabled/*;}

Separar virtual hosts (un archivo por sitio)

Objetivo: que cada sitio tenga su propio archivo, fácil de habilitar/deshabilitar y de revisar.

• Ejemplo de convención: /etc/nginx/conf.d/mi-sitio.conf
• O en Debian/Ubuntu: /etc/nginx/sites-available/mi-sitio y un enlace simbólico en sites-enabled

# /etc/nginx/conf.d/mi-sitio.confserver {    listen 80;    server_name mi-sitio.local;    root /var/www/mi-sitio/public;    index index.html index.htm;    location / {        try_files $uri $uri/ =404;    }}

Reutilizar fragmentos con include

Cuando repites bloques (cabeceras, reglas de estáticos, parámetros comunes), crea fragmentos reutilizables. Esto reduce errores y hace cambios masivos más seguros.

# /etc/nginx/snippets/estaticos.conflocation ~* \.(css|js|png|jpg|jpeg|gif|svg|ico)$ {    expires 7d;    add_header Cache-Control "public";}

# En tu server { ... }include /etc/nginx/snippets/estaticos.conf;

Buenas prácticas al usar include:

• Usa nombres claros: snippets/estaticos.conf, snippets/seguridad-basica.conf, etc.
• Mantén los fragmentos pequeños y con un propósito.
• Evita fragmentos “misteriosos” que cambian demasiadas cosas a la vez.

Comentarios útiles (y cuáles evitar)

Comenta para explicar por qué existe una regla, no para repetir lo obvio.

# Bien: explica intención y riesgo# Evitamos listar directorios por seguridad (no hay index en /uploads)location /uploads/ {    autoindex off;}

# Evitar: no aporta# Esto es un locationlocation / {    try_files $uri $uri/ =404;}

Guía práctica: leer y modificar un virtual host de forma controlada

En los siguientes ejercicios, trabajarás con un bloque server simple. La idea es hacer cambios pequeños, validar, y recargar sin cortar conexiones.

Paso 0: ubica el archivo correcto

Busca dónde se incluyen los sitios desde el contexto http. En el archivo principal (a menudo /etc/nginx/nginx.conf) localiza líneas include como:

include /etc/nginx/conf.d/*.conf;

Luego abre el archivo del sitio que vas a modificar (por ejemplo /etc/nginx/conf.d/mi-sitio.conf).

Paso 1: cambiar el puerto de escucha (listen)

Escenario: quieres probar el sitio en un puerto alternativo sin tocar el puerto 80.

server {    listen 8080;    server_name mi-sitio.local;    root /var/www/mi-sitio/public;    index index.html;    location / {        try_files $uri $uri/ =404;    }}

Notas:

• Si ya existe otro server escuchando en 8080 con configuración incompatible, tendrás conflicto.
• Si hay firewall, puede bloquear el puerto aunque Nginx escuche correctamente.

Paso 2: definir server_name correctamente

server_name determina qué hostnames atiende el bloque. Puedes poner varios:

server_name mi-sitio.local www.mi-sitio.local;

Errores típicos:

• Dejar server_name _; o un comodín demasiado amplio y “capturar” tráfico que no esperabas.
• Olvidar que el navegador debe enviar el Host correcto (en local, puedes usar /etc/hosts o probar con herramientas que permitan especificar Host).

Paso 3: ajustar root e index

root apunta al directorio desde el que se sirven archivos. index define el archivo por defecto al pedir un directorio.

root /var/www/mi-sitio/public;index index.html index.htm;

Checklist rápido:

• El directorio existe: /var/www/mi-sitio/public.
• El usuario con el que corre Nginx puede leerlo (y ejecutar permisos en directorios).
• Existe el archivo de índice (por ejemplo index.html).

Ejemplo de estructura esperada:

/var/www/mi-sitio/public/    index.html    css/    js/

Validación y recarga segura: evita caídas por un punto y coma

Validar sintaxis y rutas con nginx -t

Antes de recargar, valida:

sudo nginx -t

Salida esperada cuando todo está bien:

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

Si falla, Nginx suele indicar archivo y línea aproximada. Corrige y vuelve a ejecutar nginx -t hasta que pase.

Recarga segura (sin cortar conexiones)

Cuando la validación es correcta, recarga la configuración:

sudo nginx -s reload

En sistemas con systemd, también es común:

sudo systemctl reload nginx

La recarga aplica cambios sin detener el proceso maestro; las conexiones existentes suelen completarse con la configuración anterior mientras las nuevas usan la nueva.

Errores típicos y cómo diagnosticarlos rápido

1) Llaves desbalanceadas o ; faltante

Síntoma: nginx -t falla con mensajes como unexpected "}" o directive ... is not terminated by ";".

Acción:

• Revisa la línea indicada y las anteriores.
• Busca directivas sin ;.
• Verifica que cada { tenga su }.

2) Archivo incluido no existe o patrón include incorrecto

Síntoma: error mencionando open() ... failed sobre un archivo de configuración.

Acción:

• Comprueba la ruta exacta del include.
• Si usas comodines (*.conf), asegúrate de que el directorio exista.

3) Rutas de root incorrectas

Síntoma: el sitio responde 404 para archivos que “deberían existir”.

Acción:

• Confirma el root efectivo (¿está definido en server o sobrescrito en algún location?).
• Verifica la ruta final que Nginx construye: root + URI.

4) Permisos insuficientes

Síntoma: respuestas 403 (Forbidden) o errores en logs sobre permission denied.

Acción:

• Asegura permisos de lectura para archivos y de ejecución (traversal) para directorios.
• Revisa propietario/grupo del contenido y el usuario efectivo de Nginx.

Ejercicios guiados (lectura y modificación)

Ejercicio 1: identifica contextos y herencia

Dado este fragmento, responde: ¿cuál es el root efectivo para / y para /app/?

http {    root /var/www/default;    server {        listen 8080;        server_name practica.local;        root /var/www/practica/public;        location /app/ {            root /var/www/practica/app_public;        }    }}

• Escribe tu respuesta indicando la ruta base usada en cada caso.
• Explica en una frase por qué (herencia vs sobrescritura).

Ejercicio 2: cambio controlado de puerto

Objetivo: mover un sitio de 8080 a 8081 sin romper la configuración.

• Edita el archivo del sitio y cambia listen 8080; por listen 8081;.
• Ejecuta sudo nginx -t y corrige si hay errores.
• Recarga con sudo nginx -s reload.

Pregunta: si al recargar obtienes error de “address already in use”, ¿qué significa y qué revisarías primero?

Ejercicio 3: definir server_name y comprobar selección de servidor

Objetivo: hacer que el bloque responda solo a practica.local.

• En el server, establece server_name practica.local;.
• Valida con nginx -t y recarga.

Pregunta: si tienes otro server en el mismo puerto con default_server, ¿qué comportamiento esperarías cuando el Host no coincide con ningún server_name?

Ejercicio 4: ajustar root e index para servir un nuevo directorio

Objetivo: servir contenido desde /var/www/practica/nuevo_public y usar home.html como índice.

• Cambia root a /var/www/practica/nuevo_public.
• Cambia index a home.html index.html;.
• Verifica que exista /var/www/practica/nuevo_public/home.html y que tenga permisos de lectura.
• Ejecuta sudo nginx -t y recarga.

Pregunta: si obtienes 403 tras el cambio, enumera dos causas probables relacionadas con permisos o con ausencia del archivo índice.