Documentazione operativa

Fonte di verita'

La fonte di verita' tecnica per Obelica VPS e':

bona/obelica-docs
/opt/obelica/repos/obelica-docs

Runtime privato:

/opt/obelica/apps/obelica-docs
http://127.0.0.1:3334

Accesso:

obelica tunnel docs --open

Per lavorare sul repo docs come su GitHub privato:

obelica tunnel all
cd ~/Developer/obelica-docs
git pull
git push

Il remote Forgejo privato usa http://127.0.0.1:3333/..., quindi richiede il tunnel attivo. Se Cursor/VS Code mostra errore di connessione a 127.0.0.1:3333, aprire obelica tunnel all e riprovare.

Cosa non e' fonte di verita'

Questi luoghi non devono contenere documentazione tecnica duplicata:

Path	Ruolo
`/opt/obelica/docs`	deprecato, solo puntatore a Fumadocs
framework locale Mac	bootstrap per agenti e note di lavoro, rimanda a Fumadocs
chat Codex/Claude	contesto temporaneo, da consolidare qui

Regola operativa

Ogni modifica infrastrutturale deve aggiornare questa documentazione nello stesso ciclo di lavoro.

Esempi:

cambio Traefik -> aggiornare pagina Traefik e runbook DNS/TLS;
cambio router o dominio applicativo -> aggiornare la scheda in content/docs/applications;
cambio database -> aggiornare Database e Sicurezza se tocca privilegi;
cambio backup -> aggiornare Backup, Restore e Roadmap;
nuovo servizio -> aggiornare Servizi, Inventario, Operations;
decisione architetturale -> aggiornare Decisioni architetturali.

Schede applicative obbligatorie

Ogni progetto gestito su obelica-prod deve avere una pagina in:

content/docs/applications

La scheda progetto deve contenere almeno:

stato produzione/staging;
owner del dominio e del DNS;
provider DNS, nameserver e record critici;
router Traefik, TLS e certificati;
deploy e rollback;
database, storage e backup;
path segreti senza valori;
smoke test e punti aperti.

Se si lavora dal framework locale Mac /Users/bona/Documents/OBELICA SERVER, la regola non cambia: il framework locale e' bootstrap operativo, mentre le schede Fumadocs sono la memoria tecnica persistente.

Quando una modifica riguarda un'app, non basta aggiornare un runbook temporaneo in migrations: aggiornare anche la scheda stabile in applications.

Workflow consigliato

Fare il cambio o audit.
Aggiornare le pagine Fumadocs rilevanti.
Eseguire build/typecheck se possibile.
Commit su Forgejo.
Verificare deploy obelica-docs.

Comandi:

cd /opt/obelica/repos/obelica-docs
npm run build
git status --short

Deploy manuale:

cd /opt/obelica/apps/obelica-docs
docker compose up -d --build
curl -I http://127.0.0.1:3334/docs

Regole contenuto

Non salvare valori secret.
Salvare path, nomi variabili e responsabilita'.
Scrivere lo stato reale, anche quando e' incompleto.
Distinguere produzione, staging e piano futuro.
Tenere aggiornate le schede applicative come registro stabile dei progetti.
Preferire runbook brevi e verificabili.