Desplegar la nightly

Especificado. El camino está en el repositorio, pero ningún nightly ha corrido todavía y la aplicación de Coolify no existe. Lo que hay: el job deploy de .github/workflows/nightly.yml y el script scripts/ci/coolify-deploy.ts (recurso nightly), probado con un Coolify y un GHCR falsos y, en local, con la comprobación de privacidad contra GHCR real. Falta una pieza para el extremo a extremo: el compose de Coolify de Desplegar Styx en Coolify (ticket #24) construye las imágenes desde el clon, o lleva los digests literales que escribe styx render --runtime coolify; ninguno de los dos lee todavía STYX_IMAGE_* (ver Lo que falta). Los nombres de la UI y de la API son los de Coolify v4 y pueden cambiar.

Qué se despliegaCopiar enlace

El contrato con la aplicación de CoolifyCopiar enlace

Antes del webhook, el job fija en la aplicación:

1. El commit que clona: PATCH /api/v1/applications/<uuid> con git_commit_sha=<STYX_COMMIT>. La aplicación es Git (compose en /deploy); sin esto Coolify clonaría la cabeza de master en el momento del webhook, y si master se movió tras el preflight, los digests de este nightly arrancarían con el compose, las redes y las migraciones de otro commit.
2. Las variables (PATCH /api/v1/applications/<uuid>/envs/bulk):

El compose de la aplicación usa image: ${STYX_IMAGE_CATALOG_SVC:?} y así para cada servicio: sin la variable, compose se niega a arrancar en vez de usar otra imagen. Si el job no puede fijar el commit o las variables (token sin permiso write, campo rechazado), falla y no dispara el webhook: desplegar sin ellos repetiría el nightly anterior, o mezclaría commits, en silencio. El campo git_commit_sha y el formato de envs/bulk salen de la API de Coolify v4 y no se han probado contra una instancia.

Antes de empezarCopiar enlace

• El sitio de docs desplegado en Coolify (Desplegar la documentación): mismo Coolify, mismo proyecto styx, mismo token de API si quieres reutilizarlo.
• La pila preparada como en Desplegar Styx en Coolify: secretos del host con deploy:coolify-secrets, Base Directory /deploy, styx-edge con el proxy en 10.254.254.2 y el cortafuegos del host. Este runbook sólo añade lo propio de la nightly.
• Acceso de administrador a MKS2508/styx en GitHub (environments y secretos).
• Acceso SSH al servidor de Coolify (para la credencial de pull).
• Un compose de Coolify que lea STYX_IMAGE_* (ver Lo que falta). Hasta entonces todo lo de abajo se puede preparar, y el job sale en verde con aviso mientras falten los secretos.

1. Imágenes privadas en GHCRCopiar enlace

release-build.yml publica en ghcr.io/<owner>/ con el GITHUB_TOKEN. Con el repositorio privado, cada paquete nuevo nace privado y enlazado al repositorio.

• No cambies su visibilidad a pública mientras dure la alfa: el job deploy lo comprueba en cada nightly para cada imagen, su -bin y el árbol styx-release, en dos pasos:
  1. existe: con el GITHUB_TOKEN del job (packages: read) el manifiesto se sirve. GHCR contesta 403 DENIED igual a un paquete privado que a uno que no existe, así que sin este paso "anónimo denegado" no prueba nada. Si falla: … no se sirve con credenciales: no publicado, o HTTP 403 (¿falta packages: read o el acceso del repo al paquete?);
  2. es privado: pide a GHCR un token anónimo; si lo da y el manifiesto se sirve, el paquete es público y corta el despliegue con … se baja sin credenciales: el nightly es privado hasta la AppSec seca.
• Los paquetes que publica release-build.yml de este repositorio ya dan acceso de lectura a sus Actions. Si uno se creó a mano, añade el repositorio en Package settings → Manage Actions access.
• Si algún día se decide publicarlas (decisión de waxin, tras la AppSec seca), la comprobación se levanta con la variable STYX_ALLOW_PUBLIC_IMAGES=1 en el paso del job.

2. Credencial de pull en el servidor de CoolifyCopiar enlace

Coolify baja las imágenes con el Docker del servidor, así que el login va en el servidor:

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Nombre: coolify-ghcr-pull. Scope: sólo read:packages. Caducidad: la que uses para tus otras credenciales. GHCR no acepta los tokens fine-grained.

2. En el servidor, como el usuario con el que Coolify habla con Docker (normalmente root):

   Copiar

   echo '<token>' | docker login ghcr.io -u <tu-usuario-de-github> --password-stdin
   docker pull ghcr.io/<owner>/styx-catalog-svc:nightly   # tras el primer promote: tiene que bajar

3. El token no va nunca en Coolify ni en el repositorio. Para rotarlo, repite el paso 2 con el nuevo.

3. Aplicación de CoolifyCopiar enlace

La aplicación es la de Desplegar Styx en Coolify, con estas diferencias:

1. Proyecto styx → + New Environment nightly (separado del de docs: comparte host, no datos).
2. El compose no construye: cada servicio con image: ${STYX_IMAGE_<COMPONENTE>:?} y ninguno con build: (el validate() de Coolify ya rechaza un build:).
3. Raw Compose Deployment, como en ese runbook (DS8-01, deploy/README.md): en el modo normal Coolify mete su red <uuid> en todos los servicios y deshace las redes internas.
4. Dominios con .vpn. en las labels de Traefik (STYX_PUBLIC_HOST, por ejemplo styx.vpn.<tu-dominio>): el hook de Tailscale los limita a la tailnet. Ningún puerto de Postgres, Valkey o NATS se publica.
5. Advanced → Auto Deploy: desactivado. Despliega el job, no los pushes.
6. Recurso → Webhooks: copia el Deploy Webhook (https://<tu-coolify>/api/v1/deploy?uuid=<uuid>&force=false). El uuid es el de la aplicación: el job lo usa también para fijar sus variables.

4. Token de API y environment de GitHubCopiar enlace

1. Coolify → Keys & Tokens → API Tokens → Create. Nombre: github-actions-nightly. Permisos: deploy, write (para fijar las variables) y read (para seguir el despliegue).
2. GitHub → MKS2508/styx → Settings → Environments → New environment coolify-nightly:
   • Deployment branches and tags → Selected branches: master. El job sólo corre desde la nightly de master.
   • Environment secrets:
     • COOLIFY_TOKEN: el token del paso 1.
     • COOLIFY_NIGHTLY_WEBHOOK: el webhook del paso 3.
3. Sin esos dos secretos el job termina en verde con COOLIFY_TOKEN / COOLIFY_NIGHTLY_WEBHOOK no configurados: no se despliega.

5. Primer despliegueCopiar enlace

1. Actions → nightly → Run workflow sobre master (con force si ya hubo un nightly verde de ese commit).
2. El job deploy tiene que imprimir, en este orden:
   • deploy-nightly: N paquetes publicados y privados (con credenciales se sirven, sin ellas no);
   • git_commit_sha=<commit del nightly>;
   • una línea STYX_IMAGE_…=ghcr.io/…@sha256:… por componente, más STYX_TRAIN y STYX_COMMIT;
   • despliegue <id> encolado, los estados de Coolify y finished.
3. En Coolify, la aplicación tiene que tener ese commit, esas variables con esos valores, y los contenedores Running (healthy).

6. VerificaciónCopiar enlace

Desde una máquina dentro de la tailnet:

curl -s https://styx.vpn.<tu-dominio>/version     # el tren y el commit del run

El tren y el commit tienen que ser los de STYX_TRAIN y STYX_COMMIT del job. En el servidor, tras cada despliegue, el guard del endurecimiento vivo:

bun run check:infra-live -- --project <proyecto compose de la aplicación>

Desde fuera de la tailnet la URL no tiene que servir nada. Los runners de GitHub tampoco llegan (el dominio es privado): por eso el job sólo verifica lo que Coolify le dice (finished), no el /version.

RollbackCopiar enlace

• A un nightly anterior: GitHub → Actions → nightly → el run del nightly bueno → Re-run jobs → deploy. Un re-run de un job reutiliza las salidas de los jobs de los que depende en ese run, así que vuelve a fijar el commit y los digests de ese nightly (compose y bytes del mismo commit) y redespliega. Sigue pasando las comprobaciones de GHCR. Sin probar todavía, y GitHub sólo deja re-ejecutar runs recientes (la ventana la pone GitHub): para uno más viejo, el camino a mano.
• A mano, sin GitHub: en la aplicación de Coolify, pon el commit (Git Commit SHA) y cada STYX_IMAGE_* en los valores que imprimió el job del nightly bueno (están en su log) y pulsa Redeploy.
• El siguiente nightly verde vuelve a fijar sus digests. Para quedarse en uno, desactiva el job quitando COOLIFY_NIGHTLY_WEBHOOK del environment.

Dónde están los logsCopiar enlace

Problemas frecuentesCopiar enlace

Lo que faltaCopiar enlace

• Que el compose de Coolify lea las imágenes de STYX_IMAGE_*. Hoy styx render --runtime coolify escribe los digests del manifiesto en literal y deploy/docker-compose.apps.yml construye. La propuesta es que el render emita image: ${STYX_IMAGE_<COMPONENTE>:-<repo>@<digest del manifiesto>}: el mismo compose sirve pegado a mano (digests del manifiesto) y desde la nightly (digests del build). Es del adapter Coolify (ticket #24) y está sin decidir.
• Ningún nightly ha corrido: ni el build publicado, ni los gates, ni este despliegue (ticket #18).
• Los runners de §9 Q8 de dec-0123 para las filas por runtime de la matriz.