# 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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```text
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