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.

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

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

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

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

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.