# Runbook server update `.53` - 2026-05-09

## Scopo

Questo file serve come handoff operativo per l agent che lavora direttamente sulla macchina `192.168.0.53`, che ospita il server interno `updates.netgescon.it`.

La `.53` va trattata anche come primo nodo di coordinamento documentale di rete, perche ospita Gitea e quindi puo distribuire la stessa base `docs/` agli altri host.

## Stato trovato

Verifiche gia concluse:

- il client Day0/demo/prod raggiunge la `.53` solo se usa `NETGESCON_UPDATE_RESOLVE=updates.netgescon.it:443:192.168.0.53`;
- `GET /api/v1/distribution/health` sulla `.53` risponde `200 OK`;
- `GET /api/v1/distribution/updates/manifest?channel=free` sulla `.53` risponde `404 Not Found`;
- il checkout `/var/www/netgescon` sulla `.53` e sporco;
- nel checkout `.53` risultano solo le route distribution per health/import/sync/backup amministratori;
- non risultano deployate le route pubbliche `updates/manifest` e `updates/package`;
- `storage/app/distribution` non mostra manifest pubblicati.

## Diagnosi

Il nodo client non e piu il blocco principale.

Il vero problema e il server update `.53`, che oggi appare su una versione incompleta o non riallineata del motore distribution.

## File da confrontare con Day0

L agent `.53` deve confrontare questi file con il workspace Day0:

1. `/var/www/netgescon/routes/api.php`
2. `/var/www/netgescon/app/Http/Controllers/Api/DistributionController.php`
3. `/var/www/netgescon/config/distribution.php`

## Dati da pubblicare sul server update

Oltre al codice, il server update deve avere:

1. `storage/app/distribution/free/manifest.json`
2. il pacchetto zip referenziato dal manifest

Senza questi file, anche con le route corrette il client non puo ricevere il manifest.

## Ordine di lavoro consigliato

1. fare backup o snapshot del checkout sporco sulla `.53`;
2. confrontare i tre file chiave con Day0;
3. portare solo il blocco distribution mancante se non e possibile riallineare tutto il checkout;
4. pubblicare il manifest `free` e il pacchetto zip;
5. eseguire `php artisan optimize:clear`;
6. validare localmente.

## Istruzioni immediate per la `.53`

Prima di toccare l update server, la `.53` deve diventare anche nodo allineato della documentazione distribuita.

Sequenza pratica consigliata:

1. creare o aggiornare un mirror pulito del repository Day0 dedicato ai manuali;
2. usare il mirror come sorgente locale per `docs/`;
3. non modificare i manuali solo dentro `/var/www/netgescon` se quel checkout resta sporco e operativo;
4. riportare ogni esito nel repository Day0 e poi propagare agli altri nodi.

Comando consigliato per bootstrap docs sulla `.53`:

```bash
cd /tmp
bash /home/michele/netgescon/netgescon-day0/scripts/ai/bootstrap_docs_mirror.sh /var/www/netgescon-docs
```

Se lo script non e ancora presente sulla `.53`, copiarlo dal workspace Day0 o eseguire gli stessi passi manualmente con clone sparse del repository Gitea.

Output minimo richiesto dall agent `.53` dopo il bootstrap:

1. path del mirror documentale usato;
2. commit corrente del mirror;
3. conferma che `docs/README.md` e `docs/00-INDICE-LAVORO-DISTRIBUITO.md` sono leggibili sulla macchina;
4. conferma se il checkout `/var/www/netgescon` resta separato oppure viene riallineato.

## Comandi di validazione locale sulla `.53`

```bash
cd /var/www/netgescon

php artisan route:list | grep -E 'distribution|updates/manifest|updates/package|distribution/health'

find storage/app/distribution -maxdepth 3 \( -type d -o -type f \) | sort

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/health.out
head -n 80 /tmp/manifest.out
```

## Criterio di successo

Il runbook puo essere considerato chiuso solo quando:

1. `updates/manifest` risponde `200` o `404` JSON applicativo coerente, non piu la pagina HTML Laravel `Not Found`;
2. il manifest `free` esiste sul filesystem;
3. il client demo/prod riesce a completare il `check connettivita` senza timeout DNS.