michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
248bdd032c
netgescon-day0/docs/distribuzione-update-netgescon.md

7.9 KiB
Executable File
Raw Blame History

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.

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:

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:

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.

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