Autodeploy Obelica Docs

Stato

Autodeploy configurato il 2026-06-17 per il repo:

bona/obelica-docs

La configurazione finale usa un solo runner account-level dell'utente bona, dedicato al deploy docs tramite label unica:

obelica-docs-deploy

Il runner non e' repo-scoped nel database Forgejo, perche' e' stato registrato con registration token globale/account di bona. Resta comunque dedicato operativamente a obelica-docs perche' solo questo workflow deve usare la label obelica-docs-deploy.

Perche account-level ma dedicato

Il runner puo' accedere a:

• /opt/obelica;
• Docker socket host;
• script deploy;
• compose runtime di obelica-docs.

Questo accesso e' privilegiato. Per ridurre il rischio operativo:

• la label obelica-docs-deploy non deve essere riutilizzata in altri repo;
• il workflow deploy docs e' l'unico autorizzato a usarla;
• il runner resta privato sul server;
• Forgejo resta locale su 127.0.0.1:3333.

Incidente risolto 2026-07-03: credenziali git del runner

Tutti i deploy Actions dal 2026-06-26 al 2026-07-03 (task 65-68, 70) fallivano con lo stesso pattern: git fetch chiedeva Username for 'http://127.0.0.1:3333': in interattivo e moriva per timeout (exit 124) dopo 120 secondi. Nessuna notifica: i fallimenti erano visibili solo nei log del runner, e i deploy reali avvenivano a mano.

Causa: il runner gira con HOME=/data (volume /opt/obelica/infra/forgejo-runner/obelica-docs/data), quindi non vede il ~/.git-credentials dell'utente bona sul host. Nel suo HOME non era mai stato creato un credential store.

Fix applicato: creati /data/.gitconfig (credential.helper = store) e /data/.git-credentials con il token scoped server-git-ops-20260703 (scope write:repository), permessi 600. Verificato con workflow_dispatch: task 71 verde, container ricreato dall'autodeploy.

Nota di manutenzione: alla prossima rotazione del token va aggiornato anche il file del runner, non solo ~/.git-credentials del host. Gap ancora aperto: nessun alert sui deploy Actions falliti.

Componenti

Flusso

push su main
  -> Forgejo Actions
  -> runner obelica-docs-deploy
  -> /opt/obelica/infra/scripts/deploy-obelica-docs.sh
  -> /opt/obelica/infra/bin/obelica deploy docs
  -> git fetch origin main dal bare repo locale Forgejo
  -> git merge --ff-only origin/main
  -> docker compose build
  -> docker compose up -d --no-build
  -> container check obelica-docs
  -> smoke test http://127.0.0.1:3334/docs

Script deploy

Dal 2026-06-24 lo script deploy e' un wrapper sottile intorno al deploy centralizzato Rust.

Lo script:

• usa lock file per evitare deploy concorrenti;
• entra in /opt/obelica;
• esegue /opt/obelica/infra/bin/obelica deploy docs.

La logica di git, build, restart, verifica container, smoke test e timeout vive nel modulo Rust deploy, configurato tramite:

/opt/obelica/infra/config/deploy-apps.tsv

Questo evita di mantenere una seconda procedura shell separata per le docs.

Comandi runner

Check operativo:

/opt/obelica/infra/scripts/check-actions-runner.sh

Stato:

cd /opt/obelica/infra/forgejo-runner/obelica-docs
docker compose ps

Log:

docker logs forgejo-runner-obelica-docs --tail=200

Restart manuale runner:

cd /opt/obelica/infra/forgejo-runner/obelica-docs
docker compose restart forgejo-runner-obelica-docs

Test manuale deploy

docker exec forgejo-runner-obelica-docs /opt/obelica/infra/scripts/deploy-obelica-docs.sh

Remote del checkout server

Il checkout server in /opt/obelica/repos/obelica-docs deve usare come origin il bare repository locale di Forgejo:

git -C /opt/obelica/repos/obelica-docs remote -v

Output atteso:

origin  /opt/obelica/data/forgejo/app/git/repositories/bona/obelica-docs.git (fetch)
origin  /opt/obelica/data/forgejo/app/git/repositories/bona/obelica-docs.git (push)

Motivo: il runner non deve usare http://127.0.0.1:3333/... per il fetch del checkout server, perche' Forgejo richiede autenticazione HTTP e un git fetch non interattivo puo' restare appeso in attesa di credenziali.

Correzione:

git -C /opt/obelica/repos/obelica-docs remote set-url origin \
  /opt/obelica/data/forgejo/app/git/repositories/bona/obelica-docs.git

Questa regola vale solo per il checkout deploy server. I push di sviluppo devono continuare a passare da Forgejo HTTP/UI/SSH, non dal bare repo.

Test autodeploy

Da un checkout locale:

git pull --rebase origin main
git commit --allow-empty -m "test: verify forgejo runner"
git push origin main

Sul server:

docker logs forgejo-runner-obelica-docs --tail=100
/opt/obelica/infra/scripts/check-actions-runner.sh

Comportamento atteso:

• la run viene creata da Forgejo;
• il runner prende il job entro pochi secondi;
• nei log compare task X repo is bona/obelica-docs;
• il deploy termina con smoke test 200.

Run arancione che non parte

Sintomo:

Forgejo mostra la run pending/arancione, ma il job non inizia.

Verifica:

/opt/obelica/infra/scripts/check-actions-runner.sh
docker logs forgejo-runner-obelica-docs --tail=200

Recovery manuale:

cd /opt/obelica/infra/forgejo-runner/obelica-docs
docker compose restart forgejo-runner-obelica-docs

Questo riavvia solo il runner forgejo-runner-obelica-docs. Non riavvia Forgejo, Postgres, Traefik o l'app obelica-docs.

Note storiche

Durante il bootstrap sono stati creati runner repo-scoped e un watchdog temporaneo. Il comportamento non era corretto: i job restavano pending finche' il runner non rifaceva Declare dopo un restart.

La configurazione stabile e' stata ottenuta registrando manualmente un runner account-level per bona con file .runner. Il test workflow_dispatch successivo ha confermato assegnazione del job in circa 2 secondi senza watchdog.

I runner precedenti risultano marcati come deleted in Forgejo e non vanno riutilizzati.

Regole

• Non riusare la label obelica-docs-deploy in altri repo.
• Non montare altri path host senza aggiornare questa pagina.
• Non mettere token runner nel repo.
• Non committare /opt/obelica/infra/forgejo-runner/obelica-docs/data/.runner.
• Se il runner viene compromesso, ruotare il registration token e ricreare .runner.