Despliegue en nginx

Una receta de producción para poner un site construido con Chinaski detrás de nginx: servir el output estático, hacer proxy de las pocas rutas dinámicas de vuelta al daemon del CMS, agregar TLS, y dejar que los deploys mantengan todo en sync.

Prerequisitos

Una instancia del CMS corriendo (la unidad chinaski@<N>) con el daemon atado a loopback.
Un directorio de output construido en /var/www/chinaski<N>/output/<lang> (u output/ para un site monolingüe sin prefix de idioma).
El ejemplo de vhost del repo (deploy/chinaski.nginx.example para un site estático mínimo; chinaski.nginx.conf.example para el patrón por instancia más completo).

Los tres valores a reemplazar

En el vhost copiado, define:

YOUR_DOMAIN: el hostname público del site.
OUTPUT_PATH: el directorio de output por idioma de arriba.
CMS_PORT: el puerto que coincide con LISTEN_URL en /etc/chinaski<N>/env (3001 para la instancia 1 por defecto).

Activación:

ln -s /etc/nginx/sites-available/YOUR_DOMAIN /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Luego agrega TLS:

certbot --nginx -d YOUR_DOMAIN

Los dos bloques de proxy que no debes omitir

Un site Chinaski “estático” tiene exactamente dos familias de URLs que tienen que llegar al daemon del CMS:

/forms/: los placeholders de formularios se embeben en las páginas construidas, pero los envíos hacen POST de vuelta al CMS. Sin este bloque, cada envío de formulario devuelve 404.
/documents/: las descargas de documentos las sirve el CMS (conteos de descarga rastreados, ventanas de publicación). Sin este bloque, cada URL de documento devuelve 404.

Ambos bloques reenvían los headers estándar (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) para que el CMS vea al cliente real, necesario para que su rate limiting y logging funcionen por visitante.

Trata el tráfico del admin por separado: la interfaz de admin vive en su propio vhost (o en el puerto de loopback propio del CMS si no lo expones públicamente). El patrón del checklist de hacer proxy desde loopback mantiene simple la lógica de trusted-proxy del CMS: no se necesita ningún setting extra de CHINASKI_TRUSTED_PROXIES porque la conexión viene de loopback. Si tu arquitectura hace que nginx llegue al daemon desde una dirección no loopback (por ejemplo, un puente de contenedor), agrega esa red a CHINASKI_TRUSTED_PROXIES.

Caching y headers

El ejemplo de vhost fija vidas de cache afinadas al ritmo de publicación de Chinaski:

HTML: cache corto (revalidar rápido después de cada build).
sw.js: no-cache, must-revalidate.
Fonts: caching inmutable de un año.
Otros assets: cache de un día.
Security headers (X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, HSTS 1y), doble seguro junto a los headers que la app ya fija.

Vhosts de idioma

Para sites multilingües, duplica el server block por idioma: el subdominio o vhost de path de cada idioma sirve su propio directorio de output (por ejemplo es.example.com → /var/www/chinaski1/output/es), cada uno con su propio bloque /forms/ apuntando al mismo upstream.

El sync de root en el momento del deploy

deploy/deploy.sh barre las configs de nginx después de cada deploy: encuentra las directivas root que apuntan al árbol de output de esta instancia y las reescribe a lo que el modo de idioma actual requiera (output/ para sites monolingües, output/<default language>/ en caso contrario), corre nginx -t, y recarga en caso de éxito; con un warning (sin recarga) cuando el test de config falla, para que el error pueda corregirse a mano. Si sigues el layout del ejemplo, gran parte del mantenimiento de nginx se vuelve zero-touch en cada deploy.