netgescon-day0/docs/distribuzione-update-netgescon.md

# Distribuzione e Aggiornamenti NetGescon

Questo documento descrive il flusso operativo reale oggi in uso e separa chiaramente cio che e gia attivo da cio che resta roadmap.

## 1. Flusso attivo oggi

La catena corretta e una sola:

1. sviluppo e verifica in Day0;
2. commit e push su Gitea `main`;
3. staging allineato dal contenuto pubblicato su Gitea;
4. controllo e applicazione aggiornamento dal pannello browser oppure via comando `php artisan`;
5. backup pre-update locale, con seconda copia opzionale o obbligatoria su Google Drive secondo configurazione del nodo.

Questo significa che Day0 e il workspace autorevole, mentre staging va trattato come nodo remoto anche quando gira sulla stessa macchina fisica.

## 2. Cosa e gia implementato

Sono gia presenti e funzionanti i seguenti componenti:

- comando `php artisan netgescon:update` per controllare e applicare un pacchetto pubblicato;
- comando `php artisan netgescon:preupdate-backup` per creare snapshot ripristinabile prima di ogni update;
- pagina browser Supporto > Modifiche, che esegue prima il backup e poi l update in background con file di progresso persistente;
- supporto Google Drive per la seconda copia del backup pre-update;
- esclusione di `.env`, `storage/` e `.git/` dalla sovrascrittura del pacchetto;
- verifica hash SHA256 e pulizia cache a fine applicazione.

## 3. Significato del canale `free`

Nel sistema attuale il canale `free` e un segnaposto tecnico di compatibilita, non una decisione commerciale definitiva.

In pratica oggi esiste una sola distribuzione operativa. La distinzione `free` e `licensed` rimane nel codice per non rompere il motore update e per preparare scenari futuri, ma non va interpretata come modello commerciale gia definito.

## 4. Preparazione baseline e backup manuale

Se serve congelare una baseline completa del nodo attuale, usare:

```bash
bash scripts/ops/netgescon-baseline-freeze.sh \
  --app-dir /var/www/netgescon \
  --version 0.8.0-baseline
```

Produce:

- archivio codice;
- copia `.env`;
- dump database best-effort;
- metadati baseline.

Per il backup pre-update applicativo usare invece:

```bash
php artisan netgescon:preupdate-backup --differential --tag=manuale
```

Con copia anche su Google Drive:

```bash
php artisan netgescon:preupdate-backup \
  --differential \
  --tag=manuale \
  --drive \
  --admin-id=ID_AMMINISTRATORE
```

Se il nodo richiede obbligatoriamente la seconda copia Drive:

```bash
php artisan netgescon:preupdate-backup \
  --differential \
  --tag=manuale \
  --drive \
  --require-drive \
  --admin-id=ID_AMMINISTRATORE
```

## 5. Pubblicazione da Day0 verso Gitea

Prima di aggiornare staging, il contenuto deve essere allineato a Gitea.

Sequenza minima:

```bash
git status
git add .
git commit -m "Messaggio coerente con il lotto Day0"
git push origin main
```

Solo dopo il push il nodo staging deve essere considerato aggiornabile tramite il suo flusso di pull/apply.

## 6. Configurazione del nodo staging

Le variabili principali sono:

```env
NETGESCON_UPDATE_URL=https://updates.netgescon.it
NETGESCON_UPDATE_CHANNEL=free
NETGESCON_NODE_CODE=staging-01
NETGESCON_PREUPDATE_DRIVE_ENABLED=true
NETGESCON_PREUPDATE_REQUIRE_DRIVE=false
NETGESCON_UPDATE_RESOLVE=
```

Note:

- `NETGESCON_UPDATE_CHANNEL=free` oggi indica il percorso operativo standard, non la licenza del cliente;
- `NETGESCON_PREUPDATE_DRIVE_ENABLED=true` abilita il tentativo di seconda copia su Drive quando l amministratore del nodo ha credenziali Google valide;
- `NETGESCON_PREUPDATE_REQUIRE_DRIVE=true` blocca l update se la seconda copia non viene completata;
- `NETGESCON_UPDATE_RESOLVE` serve solo in casi DNS particolari, ad esempio `updates.netgescon.it:443:192.168.0.53`.

## 6.1 Diagnostica reale 2026-05-09

Stato verificato sul nodo Day0 e sui container demo/prod live:

- `updates.netgescon.it` via DNS pubblico risolve a `195.110.133.76` ma il client va in timeout su `443`;
- forzando `updates.netgescon.it:443 -> 192.168.0.53` il `health` risponde correttamente;
- per questo motivo sui nodi live va mantenuto `NETGESCON_UPDATE_RESOLVE=updates.netgescon.it:443:192.168.0.53` finche il DNS interno o il routing non sono riallineati.

Comando rapido di verifica dal nodo client:

```bash
curl -I -sS --max-time 12 \
  --resolve updates.netgescon.it:443:192.168.0.53 \
  https://updates.netgescon.it/api/v1/distribution/health
```

Se il `health` risponde ma il manifest no, il problema non e piu DNS client ma server update interno.

## 6.2 Segnale di errore da riconoscere

Caso osservato sulla macchina `192.168.0.53`:

- `GET /api/v1/distribution/health` -> `200 OK`
- `GET /api/v1/distribution/updates/manifest?channel=free` -> `404 Not Found`

Questo indica uno di questi casi:

1. il checkout deployato sulla `.53` non include ancora le route `updates/manifest` e `updates/package`;
2. il controller `DistributionController` e una versione vecchia che espone solo `health` e le route migrazione amministratori;
3. `storage/app/distribution/<channel>/manifest.json` non esiste ancora sul server update.

Finche uno di questi tre punti resta aperto, il client non puo completare il controllo aggiornamenti anche se `NETGESCON_UPDATE_RESOLVE` e corretto.

## 7. Aggiornamento da browser

Il percorso operativo preferito per staging e il pannello browser in Supporto > Modifiche.

La pagina esegue questa sequenza:

1. verifica permessi utente;
2. crea backup pre-update locale;
3. se configurato, carica anche la copia Google Drive;
4. avvia `netgescon:update --apply` in background;
5. salva avanzamento e log in `storage/app/support/update-jobs/`;
6. aggiorna il riepilogo ultimo backup e l esito dell operazione.

Questo e il percorso da preferire per l accettazione operativa lato staging, perche lascia traccia applicativa e stato avanzamento leggibile da interfaccia.

## 8. Aggiornamento da comando

Se serve eseguire la stessa procedura senza browser:

```bash
php artisan netgescon:update --channel=free
php artisan netgescon:update --channel=free --apply
```

La modalita `licensed` rimane disponibile solo come compatibilita tecnica o scenario futuro:

```bash
php artisan netgescon:update --channel=licensed --apply --code=CLIENTA --auth=tokenA
```

## 9. Sicurezza minima gia coperta

- hash SHA256 del pacchetto verificato prima dell apply;
- backup `.env` locale durante l update;
- snapshot pre-update con manifest file e indice record;
- esclusione dei percorsi sensibili dalla sovrascrittura;
- `composer install --no-dev --optimize-autoloader` quando il pacchetto contiene file Composer;
- `php artisan optimize:clear` sempre a fine apply;
- `php artisan migrate --force` se il manifest dichiara `migrate_required=true`.

## 10. Roadmap reale

I passaggi sotto restano obiettivi successivi, non prerequisiti del flusso attuale:

1. firma manifest con chiave privata e verifica lato nodo;
2. audit centralizzato di download e apply;
3. packaging/release automatizzati da pipeline Gitea;
4. rollback completo codice piu database con retention formalizzata.

## 11. Checklist server update `.53`

Quando si lavora direttamente sulla macchina `192.168.0.53`, l agent remoto deve verificare in questo ordine:

1. `routes/api.php` contiene sia `GET /updates/manifest` sia `GET /updates/package` nel gruppo `Route::prefix('v1/distribution')`.
2. `app/Http/Controllers/Api/DistributionController.php` contiene i metodi `updatesManifest()` e `updatesPackage()` oltre a `health()`.
3. `config/distribution.php` esiste ed e coerente con il motore update del workspace Day0.
4. `storage/app/distribution/free/manifest.json` esiste.
5. il pacchetto zip referenziato dal manifest esiste davvero sotto `storage/app/distribution/free/`.
6. dopo ogni modifica: `php artisan optimize:clear`.
7. validazione finale:

```bash
curl -sS -D - --max-time 12 https://updates.netgescon.it/api/v1/distribution/health -o /tmp/health.out
curl -sS -D - --max-time 12 'https://updates.netgescon.it/api/v1/distribution/updates/manifest?channel=free' -o /tmp/manifest.out
head -n 40 /tmp/manifest.out
```