netgescon-day0/docs/RUNBOOK-DISTRIBUZIONE-REMOTA-NETGESCON.md

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

## Macchine da non confondere

Prima di tutto fissare il perimetro corretto:

1. `192.168.0.157` (`svr-netgescon`) e il nodo produzione Docker per `www.netgescon.it`, `app.netgescon.it`, `demo.netgescon.it`
2. `.200` resta macchina di sviluppo (`:8000`) e staging (`:80/:443`)
3. non usare `.200` per portare online la stack Docker multisito di produzione

Verifica operativa confermata il `2026-05-18`:

- sul nodo `192.168.0.157` Traefik pubblica `80/443`
- `195.110.133.78` inoltra correttamente verso quel nodo
- `www/app/demo` rispondono con `307` su HTTP e `200` su HTTPS

## 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`
1. 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:

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

Firewall (esempio):

```bash
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

```bash
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`

```bash
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

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

```bash
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):

```bash
# 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:

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

```bash
php artisan optimize:clear
php artisan route:clear
php artisan config:clear
```

Test endpoint update:

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

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

Check update:

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

Apply update:

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

Per licensed:

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

## 10. Verifica finale rete

Dopo update staging:

```bash
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

```bash
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)

```bash
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

```bash
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

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

### 15.5 Smoke test rete staging

```bash
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.