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

8.8 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 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.

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

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"

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 da remoto

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.