michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e0e2724db4
netgescon-day0/docs/RUNBOOK-DISTRIBUZIONE-REMOTA-NETGESCON.md

11 KiB
Raw Blame History

NetGescon - Runbook Distribuzione Remota

Documento operativo unico per uscire dalla macchina locale e gestire NetGescon in rete con:

  • macchina Git self-hosted,
  • distribuzione aggiornamenti,
  • canali free e licensed.

Questo runbook e pensato per essere eseguito sulla macchina remota dove stai preparando l'ambiente.

Stato operativo reale da usare oggi

Prima di ogni altra sezione, vale questa regola pratica:

  1. il codice si aggiorna nel repository locale netgescon-day0
  2. si esegue commit Git e push su Gitea interno
  3. staging e gli altri nodi si allineano dal repository Gitea

Quindi il runbook remoto non sostituisce il flusso Git, ma lo completa.

Il deploy manuale diretto verso staging non e il percorso standard da descrivere come primario.

Stato Aggiornato (10-03-2026)

Modifiche gia implementate nel progetto per distribuzione/update:

  1. Config distribuzione: config/distribution.php
  2. Comando client update: app/Console/Commands/NetgesconDistributionPullCommand.php
  3. Registrazione comando: bootstrap/app.php
  4. Endpoint API update in app/Http/Controllers/Api/DistributionController.php e routes/api.php.
  • GET /api/v1/distribution/updates/manifest
  • GET /api/v1/distribution/updates/package
  1. Script operativi:
  • scripts/ops/netgescon-baseline-freeze.sh
  • scripts/ops/netgescon-publish-manifest.sh
  • stack git: scripts/ops/git-stack/*
  1. Manuale architettura: docs/01-git-machine-blueprint-2026.md
  2. Baseline creato: storage/backups/netgescon-baselines/0.8.0-baseline_20260310-095558/

Nota tecnica verificata:

  • era presente un errore sintassi che bloccava php artisan in app/Providers/Filament/AdminFilamentPanelProvider.php;
  • il file e stato corretto, e ora php artisan list risponde regolarmente.

Ordine Manuali Per Riavvio Lavoro

Quando riparti dopo stop chat/agent, usa questo ordine:

  1. docs/RUNBOOK-DISTRIBUZIONE-REMOTA-NETGESCON.md (questo file)
  2. docs/01-git-machine-blueprint-2026.md (scelte architetturali)
  3. docs/distribuzione-update-netgescon.md (focus update pipeline)
  4. docs/ai/SESSION_HANDOFF.md (stato ultima sessione)
  5. docs/ai/TOPICS_INDEX.md e topic corrente in docs/ai/topics/*.md

1. Obiettivo

Portare NetGescon in produzione di distribuzione con:

  1. Server Git multi-progetto.
  2. Server update (manifest + pacchetti).
  3. Aggiornamento automatico nodi (staging e poi altri nodi).
  4. Base pronta per licensing con scadenza e moduli premium.

Nota attuale:

  • il punto 1 oggi e gia sostanzialmente rappresentato dal repository Gitea interno origin
  • i punti 2, 3 e 4 restano parzialmente predisposti ma non sono il flusso principale gia in esercizio

2. Architettura consigliata

Domini consigliati:

  • git.netgescon.it -> Forgejo/Gitea
  • updates.netgescon.it -> API update/licensing
  • storage.netgescon.it -> MinIO (opzionale ma consigliato)

Servizi:

  1. Forgejo (o Gitea)
  2. PostgreSQL (Forgejo)
  3. MinIO
  4. API update/licensing (puo essere il tuo Laravel NetGescon)
  5. Reverse proxy TLS (Nginx/Caddy)

3. Prerequisiti macchina remota

Pacchetti base:

sudo apt update
sudo apt install -y docker.io docker-compose-plugin curl jq unzip
sudo systemctl enable --now docker

Firewall (esempio):

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw --force enable

4. Bootstrap stack Git/Distribuzione

Nel repo NetGescon hai gia i file base:

  • scripts/ops/git-stack/docker-compose.yml
  • scripts/ops/git-stack/.env.example

4.1 Copia stack su macchina remota

mkdir -p /opt/netgescon-git-stack
cd /opt/netgescon-git-stack

# Copia i file dal tuo repo locale/remoto
after_copy=true

Copia dentro /opt/netgescon-git-stack almeno:

  • docker-compose.yml
  • .env.example
  • placeholder-nginx.conf

4.2 Configura .env

cd /opt/netgescon-git-stack
cp .env.example .env
nano .env

Imposta obbligatoriamente:

  • GIT_DOMAIN
  • SSH_DOMAIN
  • password DB
  • secret Forgejo
  • credenziali MinIO
  • SMTP

4.3 Avvio servizi

cd /opt/netgescon-git-stack
docker compose --env-file .env up -d
docker compose ps

5. Reverse proxy e TLS

Configura Nginx/Caddy davanti ai servizi docker.

Minimo indispensabile:

  1. HTTPS valido su git.netgescon.it
  2. HTTPS valido su updates.netgescon.it
  3. SSH Git pubblicato su :2222

Verifica endpoint:

curl -I https://git.netgescon.it
curl -I https://updates.netgescon.it

6. Punto zero (baseline stabile)

Hai gia creato baseline locale:

  • storage/backups/netgescon-baselines/0.8.0-baseline_20260310-095558

Copialo su remoto (archivio storico):

# Esempio
scp -r storage/backups/netgescon-baselines/0.8.0-baseline_20260310-095558 user@REMOTE:/var/backups/netgescon-baselines/

Questo e il tuo punto di ritorno sicuro.

7. Setup update API su remoto

Questa sezione va considerata secondaria rispetto al flusso Git/Gitea corrente.

Prima di usarla, assicurarsi che:

  • il commit corretto sia gia stato pubblicato su Gitea
  • staging abbia gia riallineato quel commit dal repository

Nel progetto Laravel (istanza update server) devi avere:

  • endpoint manifest/package
  • config distribution.php

Variabili .env lato update server:

NETGESCON_UPDATE_URL=https://updates.netgescon.it
NETGESCON_UPDATE_CHANNEL=free
NETGESCON_LICENSED_PAIRS="CLIENTA:tokenA,CLIENTB:tokenB"

Il valore free qui va letto come valore tecnico corrente di configurazione. Non dimostra da solo che il modello commerciale attivo sia gia definitivamente separato in canali.

Poi:

php artisan optimize:clear
php artisan route:clear
php artisan config:clear

Test endpoint update:

curl -sS "https://updates.netgescon.it/api/v1/distribution/updates/manifest?channel=free" | jq
curl -I -sS "https://updates.netgescon.it/api/v1/distribution/updates/package?channel=free&file=netgescon-0.8.1.zip"

8. Pubblicare il primo aggiornamento

8.1 Crea pacchetto zip release

Genera un file zip release (es. netgescon-0.8.1.zip) contenente solo codice applicativo da distribuire.

Nota: non includere .env, storage/, .git/.

8.2 Pubblica manifest

Script disponibile:

  • scripts/ops/netgescon-publish-manifest.sh

Esecuzione canale free:

bash scripts/ops/netgescon-publish-manifest.sh \
  --channel free \
  --version 0.8.1 \
  --package /var/www/netgescon/storage/app/distribution/free/netgescon-0.8.1.zip \
  --base-url https://updates.netgescon.it

Esecuzione canale licensed:

bash scripts/ops/netgescon-publish-manifest.sh \
  --channel licensed \
  --version 0.8.1 \
  --package /var/www/netgescon/storage/app/distribution/licensed/netgescon-0.8.1.zip \
  --base-url https://updates.netgescon.it

9. Aggiornare staging

Flusso corretto oggi:

  1. sviluppare e testare in netgescon-day0
  2. fare commit e push su Gitea
  3. su staging, eseguire allineamento del repository dal remoto Gitea
  4. solo dopo l'allineamento, eseguire eventuali comandi Laravel necessari

Questa resta la procedura preferita anche quando esistono script o comandi di update applicativo.

10. Nota sui canali distribuzione

Nel codice esiste gia il supporto ai canali free e licensed, ma operativamente oggi il progetto va trattato come distribuzione unica fino a conferma di una reale attivazione commerciale differenziata.

La documentazione deve quindi:

  • descrivere prima il flusso Git/Gitea reale
  • marcare i canali distinti come infrastruttura pronta o parzialmente pronta
  • evitare di presentare come attiva una segmentazione commerciale non ancora formalizzata

Sul nodo staging configura .env:

NETGESCON_UPDATE_URL=https://updates.netgescon.it
NETGESCON_UPDATE_CHANNEL=free
# per licensed:
# NETGESCON_LICENSED_CODE=CLIENTA
# NETGESCON_LICENSED_AUTH=tokenA

Check update:

php artisan netgescon:update --channel=free

Apply update:

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

Per licensed:

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

10. Verifica finale rete

Dopo update staging:

curl -I -sS "https://staging.netgescon.it/up"
curl -I -sS "https://staging.netgescon.it/fornitore/tickets?fornitore=1"

Verifica app:

  1. Login
  2. Upload allegati
  3. Camera/webapp allegati
  4. Area fornitori nuova UI
  5. Import e TAG legacy

11. Policy accessi utenti selezionati e scadenza

Raccomandazione implementativa lato update/licensing:

  1. Tabella licenses: code, auth, expires_at, revoked_at.
  2. Tabella license_modules: moduli abilitati per licenza.
  3. Tabella license_nodes: numero nodi autorizzati.
  4. Endpoint license/check prima del download package.

12. Pagamento moduli premium (fase successiva)

Consigliato:

  1. Stripe subscription + webhook.
  2. Webhook aggiorna licenses e license_modules.
  3. Feature gate lato app in base all'entitlement attivo.

13. Rollback rapido

Se update fallisce:

  1. Ripristina baseline da /var/backups/netgescon-baselines/...
  2. Ripristina .env
  3. Ripristina DB dal dump piu recente
  4. php artisan optimize:clear

14. Checklist go-live

  • TLS valido su git. e updates.
  • Backup automatici giornalieri (DB + package + config)
  • Accesso admin con 2FA
  • Primo aggiornamento staging riuscito
  • Test allegati/camera ok
  • Canale free e licensed verificati

15. Comandi Riavvio Rapido (Verificati)

Questi comandi sono allineati allo stato attuale del progetto.

15.1 Verifica ambiente prima di lavorare

cd /home/michele/netgescon/netgescon-laravel
php -l app/Providers/Filament/AdminFilamentPanelProvider.php
php artisan list | head -n 40
php artisan list | grep -E "netgescon:update|distribution|gescon:|import:" | head -n 60

15.2 Riavvio continuita AI (facoltativo ma consigliato)

cd /home/michele/netgescon/netgescon-laravel
bash scripts/ai/restart_brief.sh "Distribuzione Netgescon"
bash scripts/ai/continuity_auto.sh --threshold=150 --topic="Distribuzione Netgescon" --note="Ripartenza operativa"

15.3 Verifica update API da rete

curl -sS "https://updates.netgescon.it/api/v1/distribution/updates/manifest?channel=free" | jq
curl -I -sS "https://updates.netgescon.it/api/v1/distribution/updates/package?channel=free&file=netgescon-0.8.1.zip"

15.4 Check/apply update su nodo staging

cd /var/www/netgescon
php artisan netgescon:update --channel=free
php artisan netgescon:update --channel=free --apply

15.5 Smoke test rete staging

curl -I -sS "https://staging.netgescon.it/up"
curl -I -sS "https://staging.netgescon.it/fornitore/tickets?fornitore=1"

Se segui questo runbook, chiudi il ciclo locale e passi a una distribuzione reale in rete, pronta a scalare anche su altri progetti.