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

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

Con copia anche su Google Drive:

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

Se il nodo richiede obbligatoriamente la seconda copia Drive:

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:

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:

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.

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:

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:

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.