netgescon-day0/docs/support/RUNBOOK-157-DEMO-UPDATE.md

Runbook .157 DEMO Docker Update

Questo runbook descrive come portare demo.netgescon.it sulla macchina 192.168.0.157 allo stesso livello funzionale gia verificato su staging, mantenendo il modello Docker multisito e i dati demo persistenti.

Perimetro corretto

• host: 192.168.0.157 (svr-netgescon)
• domini serviti: www.netgescon.it, app.netgescon.it, demo.netgescon.it
• stack: docker/docker-compose.multisite.yml
• checkout host atteso: ~/netgescon/netgescon-day0-git
• container demo: netgescon_demo_app, netgescon_demo_db, netgescon_demo_nginx

Regola pratica:

• staging locale .200 usa il flusso netgescon:git-sync verso /var/www/netgescon
• la .157 non va trattata allo stesso modo, perche prod_app e demo_app sono container Docker e non repository Git aggiornabili da dentro /var/www
• sulla .157 il codice si aggiorna dal checkout host e poi si ricostruiscono/riavviano i container applicativi

Cosa c e gia nella DEMO

Nel compose multisito la demo e gia predisposta con:

• NETGESCON_SITE_MODE=demo
• RUN_SEEDERS=demo
• volume archivi legacy montato in sola lettura su /mnt/gescon-archives/gescon
• DB, storage, cache, public e redis separati da produzione

Seeder demo aggregato:

• Database\\Seeders\\DemoEnvironmentSeeder

Componenti richiamati:

• DemoUsersSeeder
• DocumentiDemoSeeder
• DemoTicketsSeeder

Quindi utenti demo, documenti demo persistenti e ticket demo sono gia parte del bootstrap atteso del container demo.

Percorso preferito: launcher web del nodo

Se il nodo demo/app e raggiungibile, il percorso da preferire resta l interfaccia web:

• https://demo.netgescon.it/admin-filament/supporto/aggiornamento-nodo
• in alternativa, se operativamente piu comodo e condiviso con APP: https://app.netgescon.it/admin-filament/supporto/aggiornamento-nodo

Ordine corretto:

1. fare commit e push su Gitea dal repository Day0 locale
2. aprire il launcher update sul nodo .157
3. verificare stato commit/remote e che l update punti al branch giusto
4. lanciare il refresh nodo dal browser
5. attendere la maintenance page completa e il ritorno automatico
6. rileggere lo stato nodo fino a ahead 0 / behind 0

Nota: anche sulla .157 la UI deve restare il punto di accesso dell operatore. L intervento shell/agent sull host serve quando vuoi automatizzare il rollout Docker o quando il launcher non puo ancora governare il build/update del multisito host-side.

Percorso agent/host .157

Usare questo percorso se vuoi far procedere un agent direttamente sulla macchina 192.168.0.157.

Obiettivo agente

Aggiornare la stack multisito Docker dal checkout host, mantenendo intatti i dati persistenti demo/prod e verificando che la DEMO torni online con il nuovo commit.

Pre-check obbligatori sull host

cd ~/netgescon/netgescon-day0-git
git status --short
test -f docker/.env.multisite
docker compose --env-file docker/.env.multisite -f docker/docker-compose.multisite.yml ps

Se il checkout host e sporco, l agent non deve fare reset distruttivi. Deve prima fermarsi e riportare quali file locali impediscono un pull --ff-only pulito.

Update standard host-side

cd ~/netgescon/netgescon-day0-git
GIT_REF=main ./scripts/update-multisite.sh

Questo script esegue gia:

• backup DB prod e demo
• git fetch, checkout, pull --ff-only
• build immagini prod_app e demo_app
• up -d di prod_app, prod_nginx, demo_app, demo_nginx
• php artisan optimize:clear nei container app
• docker compose ps finale

Nota operativa per capire perche la DEMO puo non mostrare i dati/codice attesi:

• se la .157 non e stata aggiornata dal checkout host ~/netgescon/netgescon-day0-git, la DEMO puo mostrare ancora immagini vecchie anche se Gitea contiene gia il fix;
• la DEMO non legge il codice da /var/www/netgescon come lo staging .200;
• quindi il passaggio corretto dopo il push su Gitea e sempre rebuild host-side con GIT_REF=main ./scripts/update-multisite.sh oppure launcher nodo equivalente.

Verifiche post-update minime

curl -kI --resolve app.netgescon.it:443:127.0.0.1 https://app.netgescon.it/admin-filament/login
curl -kI --resolve demo.netgescon.it:443:127.0.0.1 https://demo.netgescon.it/admin-filament/login
docker exec netgescon_demo_app php artisan about | head -40
docker exec netgescon_demo_app php artisan tinker --execute="dump([
 'users' => \App\\Models\\User::count(),
 'demo_docs' => \App\\Models\\Documento::query()->where('is_demo', true)->count(),
 'tickets' => class_exists(\App\\Models\\Ticket::class) ? \App\\Models\\Ticket::count() : null,
]);"

La validazione applicativa minima sulla demo e:

• login 200 su https://demo.netgescon.it/admin-filament/login
• nessun container in stato restart loop
• documenti demo presenti (documenti.is_demo = 1)
• utente demo presenti
• commit host allineato al commit appena pushato su Gitea
• presenza delle ultime modifiche import GESCON nel container netgescon_demo_app

Per il ramo import GESCON appena corretto conviene aggiungere questa verifica nel container demo:

docker exec netgescon_demo_app php artisan gescon:import-gestioni --stabile=0026 --root=/mnt/gescon-archives/gescon --dry-run
docker exec netgescon_demo_app php artisan tinker --execute="dump([
 'casse_0026' => \Illuminate\Support\Facades\DB::table('casse')->where('stabile_id', \App\Models\Stabile::where('codice_stabile','0026')->value('id'))->orderBy('cod_cassa')->pluck('cod_cassa')->all(),
 'banche_0026' => \App\Models\DatiBancari::where('stabile_id', \App\Models\Stabile::where('codice_stabile','0026')->value('id'))->get(['legacy_cod_cassa','iban','is_nostro_conto'])->toArray(),
]);"

Risultato atteso:

• casse_0026 = ['CON']
• legacy_cod_cassa = 'CCB' sul conto bancario reale
• is_nostro_conto = true

Chiusura incidente login DEMO

Esito confermato al 2026-05-27:

• la causa reale del mancato login DEMO non era la password;
• durante il flusso web la richiesta degradava da https a http;
• questo impediva il corretto mantenimento di sessione/cookie e quindi l autenticazione Filament risultava sempre fallita lato utente;
• le verifiche e il materiale di handoff inviato all altro agent sono stati utili a isolare il punto reale del guasto sulla macchina .157.

Conclusione operativa:

• il runbook DEMO va ora considerato sbloccato sul fronte accesso web;
• per i prossimi test con utenti esterni la regola e mantenere il percorso interamente in https senza downgrade;
• se il problema si ripresenta, il primo controllo non deve essere la password ma la catena reverse proxy -> redirect -> schema finale -> cookie/sessione.

Cosa NON deve fare l agent .157

• non continuare con copie manuali sparse di file PHP dentro /var/www come strategia primaria;
• non fidarsi di una sola verifica CLI (php artisan tinker, reflection, grep file) per dichiarare risolto il login;
• non fare docker compose down -v, git reset --hard o altre operazioni distruttive senza esplicita approvazione;
• non trattare il problema come password sbagliata finche non e stato rifatto almeno un rebuild completo del servizio demo.

Sequenza consigliata se il login DEMO ricade

1. lavorare dal checkout host dichiarato ~/netgescon/netgescon-day0-git;
2. verificare che il working tree host sia pulito o almeno compatibile con pull --ff-only;
3. verificare subito redirect e schema finale con curl -kI --resolve demo.netgescon.it:443:127.0.0.1 https://demo.netgescon.it/admin-filament/login;
4. confermare che non esista alcun passaggio applicativo o proxy da https a http;
5. solo dopo eseguire GIT_REF=main ./scripts/update-multisite.sh se serve davvero riallineare il nodo;
6. validare via HTTPS reale GET /admin-filament/login e login browser;
7. se il problema persiste anche senza downgrade di schema, passare allora a rebuild/runtime PHP-FPM invece di tornare alle hot patch applicative.

Evidenze utili da tenere a memoria

• il sintomo applicativo poteva sembrare un errore credenziali, ma la causa era infrastrutturale sul percorso https;
• nelle indagini DEMO conviene controllare presto redirect, proxy e cookie secure per evitare debug applicativo superfluo;
• l handoff tra agent ha permesso di chiudere il caso piu rapidamente della sola analisi locale.

Quando rilanciare esplicitamente il bootstrap demo

Nella maggior parte dei casi non serve un passaggio extra: la demo e gia configurata con RUN_SEEDERS=demo.

Se dopo l update la demo torna online ma mancano utenti/documenti/ticket demo, usare questo controllo mirato:

docker exec netgescon_demo_app php artisan db:seed --class=Database\\Seeders\\DemoEnvironmentSeeder --force
docker exec netgescon_demo_app php artisan optimize:clear

Usarlo solo se la verifica applicativa mostra davvero dati demo mancanti o incompleti.

Archivi gia compilati della DEMO

Per la .157 il concetto operativo corretto e:

• gli archivi legacy restano montati lato host via LEGACY_ARCHIVES_PATH in sola lettura
• i documenti demo persistenti sono generati/mantenuti da DocumentiDemoSeeder
• il deploy codice non deve cancellare i volumi demo_storage, demo_public, demo_db

Quindi l agent non deve eseguire docker compose down -v e non deve rimuovere volumi demo, altrimenti perderebbe i dati persistenti che oggi vuoi conservare.

Prompt operativo per un agent sulla .157

Usa questo testo come incarico sintetico per l altro agent/macchina:

Lavora sulla macchina 192.168.0.157, checkout host ~/netgescon/netgescon-day0-git. Non fare reset distruttivi e non cancellare volumi Docker. Obiettivo: aggiornare la stack multisito NetGescon demo/prod al branch main con lo script host-side previsto dal repo, mantenendo i dati persistenti demo e verificando che demo.netgescon.it torni online.

Passi richiesti:
1. verifica git status del checkout host e fermati se il working tree e sporco;
2. verifica presenza di docker/.env.multisite;
3. esegui GIT_REF=main ./scripts/update-multisite.sh come percorso primario; evita hot patch manuali nel container salvo debug strettamente temporaneo;
4. valida con docker compose ps e curl HTTPS locali verso app.netgescon.it e demo.netgescon.it;
5. verifica se la login DEMO web continua a fallire anche dopo rebuild pulito; se si, segnala esplicitamente mismatch runtime/deploy invece di insistere solo sulle credenziali;
6. controlla nel container netgescon_demo_app che utenti demo e documenti demo esistano ancora;
7. se mancano dati demo, esegui solo allora php artisan db:seed --class=Database\Seeders\DemoEnvironmentSeeder --force nel container demo e poi optimize:clear;
8. restituisci commit deployato, stato container, esito login HTTPS demo, conteggio documenti demo e se il comportamento web coincide davvero con il codice dell immagine appena rebuildata.

Check finale da riportare all operatore

• commit host deployato
• esito docker compose ps
• esito login HTTPS app e demo
• conferma mantenimento documenti demo persistenti
• eventuale rilancio seed demo si/no