Configuración de Nginx

Esta guía explica cómo configurar Nginx como proxy inverso para tu instancia de Gigantics. Nginx proporciona terminación SSL, balanceo de carga y mejor rendimiento para tu despliegue de Gigantics.

Descripción General

Gigantics se ejecuta en el puerto 5000 por defecto y puede ser accedido directamente o a través de Nginx como proxy inverso. La configuración incluye:

• Terminación SSL/TLS
• Redirección de HTTP a HTTPS
• Soporte WebSocket para características en tiempo real
• Soporte para carga de archivos grandes
• Reenvío correcto de cabeceras

Instalación

Nginx no se proporciona con el software, puedes descargarlo desde:

Sitio Web Oficial: https://nginx.org/

Comandos de Instalación

Ubuntu/Debian:

sudo apt update
sudo apt install nginx

CentOS/RHEL/Rocky Linux:

sudo yum install nginx
# o para versiones más nuevas
sudo dnf install nginx

macOS (con Homebrew):

brew install nginx

Windows: Descarga la versión para Windows desde el sitio web oficial y sigue el asistente de instalación.

Iniciar y Habilitar Nginx

# Iniciar Nginx
sudo systemctl start nginx
 
# Habilitar Nginx para que inicie con el sistema
sudo systemctl enable nginx
 
# Verificar estado
sudo systemctl status nginx

Conexión Directa vs Proxy Nginx

Conexión Directa al Puerto 5000

Puedes acceder a Gigantics directamente conectándote a http://tuserver:5000 sin ningún proxy inverso (es decir, Nginx). Esta es la configuración más simple y funciona para:

• Entornos de desarrollo
• Redes internas donde la seguridad se maneja a nivel de red
• Pruebas rápidas y evaluación

Qué hay detrás del puerto 5000: Gigantics se ejecuta en un servidor Node.js Express que proporciona:

• Capacidades de servidor web HTTP/HTTPS
• Endpoints de API REST
• API GraphQL con soporte WebSocket
• Servido de archivos estáticos para la interfaz web
• Gestión de sesiones y autenticación incorporada
• Manejo de carga de archivos
• Comunicación en tiempo real vía WebSockets

Usar Nginx como Proxy Inverso

Aunque la conexión directa funciona, usar Nginx como proxy inverso ofrece ventajas significativas:

Cuándo Usar Cada Enfoque

Usa Conexión Directa cuando:

• Configurando para desarrollo o pruebas
• Ejecutando en una red interna segura
• Necesitas la configuración más simple posible
• SSL es manejado por un balanceador de carga o servicio en la nube

Usa Proxy Nginx cuando:

• Desplegando a producción
• Necesitas terminación SSL/TLS
• El rendimiento y escalabilidad son importantes
• Quieres características de seguridad avanzadas
• Necesitas servir múltiples aplicaciones
• Quieres mejor monitoreo y registro

Configuración de Producción

Aquí está la configuración recomendada de Nginx para Gigantics:

server {
    server_name tuserver.com;
    listen 80;
    listen 443 ssl;
 
    # Configuración SSL
    ssl_certificate /etc/nginx/certs/tu_certificado.crt;
    ssl_certificate_key /etc/nginx/certs/tu_clave_privada.key;
 
    # Cabeceras de seguridad
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
 
    # Configuración de cliente para cargas de archivos grandes
    client_max_body_size 500m;
    client_body_buffer_size 4m;
    large_client_header_buffers 4 32k;
 
    # Bloque de location principal
    location / {
        proxy_pass http://localhost:5000;
        proxy_redirect off;
 
        # Cabeceras esenciales
        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-Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
 
        # Configuración de tiempo de espera
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
        proxy_read_timeout 90;
 
        # Configuración de buffer
        proxy_buffer_size 4k;
        proxy_buffers 4 32k;
        proxy_busy_buffers_size 64k;
        proxy_temp_file_write_size 64k;
    }
}

Parámetros de Configuración Explicados

Configuración del Bloque del Servidor

Configuración SSL

Configuración de Carga del Cliente

Cabeceras del Proxy

Configuración de Tiempo de Espera

Configuración de Buffer

Redirección de HTTP a HTTPS

Para redirigir automáticamente el tráfico HTTP a HTTPS:

server {
    listen 80;
    server_name tuserver.com;
    return 301 https://$server_name$request_uri;
}

Cabeceras de Seguridad

Añade estas cabeceras de seguridad para protección mejorada:

add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Balanceo de Carga (Opcional)

Para configuraciones de alta disponibilidad, puedes configurar balanceo de carga:

upstream gigantics_backend {
    server 192.168.0.7:5000;
    server 192.168.0.8:5000;
    server 192.168.0.9:5000;
}
 
server {
    # ... otra configuración ...
 
    location / {
        proxy_pass http://gigantics_backend;
        # ... otra configuración del proxy ...
    }
}

Probando Tu Configuración

Probando Conexión Directa

Antes de configurar Nginx, prueba que Gigantics es accesible directamente:

1. Verifica si Gigantics está funcionando:

   curl http://localhost:5000
   # o
   curl http://tuserver:5000

2. Prueba conexión WebSocket:

   # Probar endpoint GraphQL
   curl -X POST http://localhost:5000/graphql \
     -H "Content-Type: application/json" \
     -d '{"query":"{ __schema { types { name } } }"}'

Probando Configuración de Nginx

1. Probar configuración de Nginx:

   sudo nginx -t

2. Recargar Nginx:

   sudo systemctl reload nginx

3. Verificar estado de Nginx:

   sudo systemctl status nginx

4. Probar a través de Nginx:

   curl https://tuserver.com

Solución de Problemas

Problemas Comunes

Archivos de Registro

Verifica estos archivos de registro para depuración:

• Registro de errores de Nginx: /var/log/nginx/error.log
• Registro de acceso de Nginx: /var/log/nginx/access.log
• Registros de Gigantics: Verifica tu ubicación configurada de registros

Integración con la Configuración de Gigantics

Al configurar Gigantics con Nginx, asegúrate:

1. Habilitar Nginx en configuración: Marca la opción "Habilitar Nginx" en la configuración avanzada
2. Configurar SSL: Proporciona tus rutas de certificado y clave SSL
3. Establecer puerto de redirección: Configura redirección HTTP a HTTPS si es necesario
4. Actualizar configuración del servidor: Asegúrate que Gigantics escuche en la interfaz correcta

El proceso de configuración generará la configuración apropiada de Nginx basada en tus ajustes.

Opcional: Bloque de Location Dedicado para GraphQL

Aunque el bloque de location principal maneja todas las solicitudes incluyendo GraphQL, opcionalmente puedes añadir un bloque de location dedicado /graphql para soporte WebSocket mejorado y optimizaciones específicas.

Cuándo Usar un Bloque GraphQL Dedicado

Usa esta configuración opcional cuando:

• Necesitas rendimiento WebSocket mejorado para suscripciones GraphQL
• Quieres diferentes configuraciones de tiempo de espera para operaciones GraphQL
• Necesitas reglas de caché específicas para consultas GraphQL
• Quieres separar tráfico GraphQL del tráfico web regular
• Estás experimentando problemas de conexión WebSocket con el bloque de location principal

Configuración GraphQL Opcional

Puedes añadir este bloque de location después de tu bloque de location principal:

server {
    # ... toda la otra configuración va aquí ...
 
    # Opcional: Bloque de location dedicado para GraphQL
    location /graphql {
        proxy_pass http://192.168.0.7:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 
        # Optimizaciones específicas para GraphQL
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 300s;  # Más largo para suscripciones
 
        # Configuraciones específicas para WebSocket
        proxy_cache_bypass $http_upgrade;
        proxy_no_cache $http_upgrade;
    }
}

Opciones de Configuración para Bloque GraphQL

Por Qué Esto es Opcional

El bloque de location principal ya maneja GraphQL porque:

• Incluye proxy_http_version 1.1
• Tiene cabeceras Upgrade y Connection para soporte WebSocket
• Gigantics maneja el enrutamiento GraphQL internamente

Usa el bloque dedicado solo si necesitas:

• Diferentes configuraciones de tiempo de espera para GraphQL vs solicitudes regulares
• Rendimiento WebSocket mejorado para características en tiempo real
• Comportamiento de caché específico para consultas GraphQL
• Solución de problemas de conexión WebSocket

Probando Configuración GraphQL

Prueba endpoints regulares y GraphQL:

# Probar GraphQL regular (a través del location principal)
curl -X POST https://tuserver.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { types { name } } }"}'
 
# Probar conexión WebSocket (si usas bloque dedicado)
# Esto requiere un cliente WebSocket o herramientas de desarrollador del navegador