netgescon-day0/docs/support/UPDATE-SERVER-53-RUNBOOK-2026-05.md

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:

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

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.