Referencia CLI & Server (`cms.pl`)

cms.pl es el daemon del CMS de Chinaski: sirve la interfaz de admin y la API, mientras el site público es HTML estático construido por separado. Esta página explica cómo correr el servidor en desarrollo, en producción y offline, más las herramientas de línea de comandos que vienen con él.

Antes de empezar

El servidor no arrancará sin CHINASKI_SECRET. Es la key de firma de las sesiones de admin y protege las credenciales almacenadas de servicios de terceros: establécela con un valor largo aleatorio y nunca la cambies a la ligera.
La sesión de admin dura 8 horas, y la cookie solo se envía sobre HTTPS.

Correr el servidor

Desarrollo

morbo cms.pl

Morbo es el servidor de desarrollo: se reinicia con los cambios de código. Construye el site estático por separado con perl builder/build.pl.

Producción (systemd, recomendado)

El directorio deploy/ incluye una unidad systemd con template, chinaski@.service, así que un solo conjunto de archivos corre cualquier cantidad de instancias del CMS en el mismo host. Habilita una con el nombre de instancia:

systemctl enable --now chinaski@1

(1 puede ser 2, prod, staging: cualquier cosa alfanumérica.) Lo que la unidad hace por ti:

Corre como un usuario chinaski dedicado con el directorio de trabajo /var/www/chinaski<instance>.
Establece las rutas de base de datos y output automáticamente desde el nombre de instancia (CHINASKI_DB, CHINASKI_OUTPUT): normalmente no las estableces a mano.
Lee un único archivo env con permisos bloqueados, /etc/chinaski<instance>/env, que creas antes de arrancar. Debe contener CHINASKI_SECRET y LISTEN_URL.
Se reinicia automáticamente ante fallos (con backoff), espera las peticiones en vuelo al apagarse (un drain de 30 segundos; un build en vuelo se cancela en lugar de esperarse), y aplica límites de memoria/CPU y hardening estándar para que un build desbocado no inanice al host.
Loguea a journald: véelo con journalctl -u chinaski@<instance>.

Enlaza el servidor a loopback. En este setup un reverse proxy (Caddy o nginx) se sienta delante y el ejemplo de la unidad enlaza LISTEN_URL a http://127.0.0.1:3001. El CMS solo confía en las IPs de cliente reenviadas desde conexiones de loopback: enlazarlo a una interfaz pública permitiría a los visitantes falsificar su IP y derrotar los límites de tasa y los bloqueos de login.

Producción (sin gestor de servicios)

Los deployments point corren durante una ejecución de deploy.sh <instance>, que jala código, instala dependencias, hace checks de sintaxis, reconstruye el output estático y reinicia el servicio. Si un build falla, el deploy aborta por defecto para que nunca reinicies sobre output roto; CHINASKI_ALLOW_BUILD_FAIL=1 anula esto para deploys de emergencia de solo código.

Instalación de servidor con un solo comando

En un servidor Debian/Ubuntu puedes parar una nueva instancia con un solo comando; el instalador maneja paquetes, dependencias, el usuario chinaski, la inicialización de la base de datos, el archivo env y el servicio systemd:

curl -fsSL https://chinaski.net/install | sudo bash -s -- 1 --repo https://github.com/bigjohncobb/chinaski

Reemplaza 1 con tu nombre de instancia; pasa --port PORT para sobrescribir el puerto de escucha por defecto.

Modo offline / "EOTW" (hypnotoad, HTTP plano)

Para máquinas sin acceso a internet (sin DNS, sin autoridades de certificados), hypnotoad puede ser el único servidor, sirviendo HTTP plano en el puerto 8080 para siempre.

Construye u obtén un bundle offline (bash install/make-bundle.sh en una máquina conectada) y sigue la instalación del bundle.
Copia install/hypnotoad.conf al directorio de la aplicación.
Arráncalo:

export CHINASKI_SECRET=$(openssl rand -hex 32)   # once; save the value
export CHINASKI_AIRGAP=1
hypnotoad cms.pl

Gestionar una instancia corriendo:

hypnotoad cms.pl                        # start, or hot-reload a running instance
hypnotoad -s cms.pl                     # graceful stop
kill -USR2 $(cat hypnotoad.pid)         # hot-reload without dropping connections

Dos workers es seguro en una máquina de 1 GB; súbete a 4 en un host de 2+ GB con varios editores concurrentes.

Seguridad sin proxy: fuera de loopback, el CMS ignora los headers X-Forwarded-For y usa la dirección real de la conexión TCP, así que el rate limiting y el bloqueo de login funcionan correctamente sin configuración extra. No hay TLS en este modo: no envíes contraseñas por una red no confiable; usa una VPN o reglas de firewall para restringir quién puede alcanzar el admin.

Variables de entorno

Variable	Propósito
`CHINASKI_SECRET`	Requerida. Key de firma de sesión (32+ bytes aleatorios); también desbloquea las credenciales cifradas que el CMS almacena
`CHINASKI_LISTEN`	Dirección en la que escucha el servidor; default `http://127.0.0.1:8080`
`CHINASKI_WORKERS`	Número de workers del servidor; default `2`. Usa 4 en máquinas de 2+ GB con varios editores simultáneos
`CHINASKI_DB`	Ubicación del archivo de base de datos; usualmente derivada del nombre de instancia por la unidad systemd
`CHINASKI_OUTPUT`	Directorio de output del build estático; usualmente derivado del nombre de instancia
`CHINASKI_AIRGAP`	Establécela a `1` para deshabilitar cada petición saliente: build webhooks, form webhooks y verificación de bot-check (la protección de casilla también se oculta)
`CHINASKI_TRUSTED_PROXIES`	Direcciones IP separadas por comas o rangos CIDR IPv4 autorizados a reenviar IPs de cliente. Loopback siempre es confiable; el default es solo loopback
`CHINASKI_ALLOW_BUILD_FAIL`	Establécela a `1` delante de `deploy.sh` para permitir deploys de solo código cuando un build falla
`CHINASKI_FORCE_FULL`	Usada internamente por el comando de full-rebuild; normalmente no se establece a mano
`MOJO_MODE`	Establécela a `production` en deployments de producción (la unidad systemd lo hace); el modo de prueba cambia el hashing de contraseñas a un coste más rápido, solo de prueba

Otras variables existen en el código (CHINASKI_CMS_URL, CHINASKI_DOCS_DIR, CHINASKI_RELEASE_PUBKEY, CHINASKI_SMTP_INSECURE_NOVERIFY, CHINASKI_UPDATE_MANIFEST_URL, CHINASKI_URL_BASE, CHINASKI_FORCE_PROMOTE) pero sus settings exactamente soportadas no se cubren en estos docs.

Utilidades de línea de comandos

Todas viven en bin/ y leen la misma base de datos que usa el CMS.

Comando	Qué hace
`perl bin/chinaski-setup.pl`	Setup de primer arranque por script. Pasa `--username`, `--site-url` y `--password`, o usa la variable de entorno `CHINASKI_ADMIN_PASSWORD` en su lugar, para que la contraseña no sea visible en la lista de procesos. Aplica el mínimo de 12 caracteres más las reglas de complejidad.
`perl bin/reset-admin.pl [username]`	Pone la cuenta de un administrador de vuelta en el modo de setup de primer arranque para que pueda elegirse una nueva contraseña; requiere acceso shell y una confirmación `YES` tecleada. La próxima visita al site pasa por la pantalla de setup.
`perl bin/chinaski-config.pl get KEY` / `set KEY VALUE`	Lee o escribe cualquier setting del site desde la línea de comandos.
`perl bin/force-full-build.pl`	Limpia la cache de build y corre un rebuild estático completo.
`perl bin/check-schema-sync.pl`	Confirmar que la base de datos coincide con el schema incluido; salida 0 significa sincronizada, 1 significa drift. Útil después de upgrades.
`bin/cron-build-monitor.sh`	Script de cron (pensado cada 5 minutos) que alerta cuando los builds dejan de completarse o las páginas desaparecen del directorio de output.