netgescon-day0/docs/01-git-machine-blueprint-2026.md

NetGescon - Macchina Git e Distribuzione (Blueprint 2026)

Questo file e un blueprint evolutivo. Non descrive il processo operativo minimo gia in uso oggi, ma la direzione target verso cui convergere senza confondere lo stato attuale del progetto.

1. Stato reale attuale

Oggi la situazione concreta e questa:

• esiste un workspace autorevole Day0;
• il repository sorgente canonico e Gitea;
• il branch operativo e main;
• staging deve ricevere gli aggiornamenti partendo da cio che e stato prima pubblicato su Gitea;
• il motore update Laravel esiste gia ed e utilizzabile anche da browser;
• la distinzione free e licensed e tecnica e preparatoria, non un prodotto commerciale formalizzato.

Per il flusso operativo quotidiano fare riferimento prima alla documentazione Day0/Gitea e ai runbook di distribuzione, non a questo blueprint.

2. Obiettivo del blueprint

L obiettivo 2026 resta costruire una piattaforma unica per piu progetti con:

• repository Git self-hosted;
• distribuzione aggiornamenti centralizzata;
• controllo accessi e abilitazioni per nodo;
• moduli opzionali e, se necessario in futuro, gestione commerciale separata.

3. Stack consigliato

Stack consigliato per l evoluzione:

• Gitea o Forgejo per Git, issue, release e accessi team;
• API update/licensing separata in Laravel per manifest, package, autorizzazioni e audit;
• storage oggetti dedicato, ad esempio MinIO, per pacchetti release e asset;
• reverse proxy Nginx o Caddy con TLS e domini separati;
• Keycloak solo se emergera una reale esigenza SSO multi-progetto.

4. Architettura target

Separazione logica consigliata:

• git.netgescon.it: repository, review, release, chiavi SSH;
• updates.netgescon.it: manifest, package, audit applicazione update;
• storage.netgescon.it: bucket privati per pacchetti e snapshot pubblicabili;
• registry.netgescon.it: opzionale, solo se entrano in gioco immagini container.

Questa architettura va letta come destinazione, non come prerequisito immediato per il flusso corrente Day0 -> Gitea -> staging.

5. Modello canali update

I canali oggi esistono nel codice per compatibilita tecnica:

• free: percorso standard attuale;
• licensed: percorso riservato per futuri controlli piu stretti.

Se e quando il modello verra attivato davvero, i controlli consigliati sono:

• scadenza licenza expires_at;
• limite nodi max_nodes;
• moduli abilitati modules[];
• versione minima supportata min_supported;
• revoca immediata revoked_at.

Fino a quel momento il canale free non deve essere comunicato come offerta commerciale finale.

6. Governance minima da mantenere gia ora

Anche prima della piattaforma completa, conviene mantenere da subito queste regole:

1. Gitea come unica sorgente canonica dei rilasci approvati.
2. Backup giornaliero di repository e snapshot applicativi.
3. Backup pre-update obbligatorio sui nodi sensibili.
4. Seconda copia su Google Drive dove il nodo ha gia integrazione Google disponibile.
5. Separazione netta fra ambiente Day0, staging e futuri siti cliente.

7. Evoluzioni consigliate

Passi coerenti con il codice gia presente:

1. pipeline Gitea per creare zip release e manifest in modo ripetibile;
2. firma manifest e validazione lato nodo;
3. audit centralizzato di check, download e apply;
4. retention formalizzata dei backup pre-update locali e Drive;
5. eventuale catalogo moduli/licenze solo dopo stabilizzazione del flusso tecnico.

8. Tema commerciale

Il progetto e predisposto per scenari con moduli o accessi differenziati, ma al momento non bisogna confondere predisposizione tecnica e modello commerciale attivo.

Se in futuro servira davvero una gestione commerciale, le entita minime lato backend saranno probabilmente:

• customers;
• licenses;
• license_modules;
• payments;
• entitlements_audit.

Fino ad allora la priorita resta consolidare il flusso tecnico unico:

1. sviluppo in Day0;
2. push su Gitea;
3. aggiornamento controllato di staging;
4. solo dopo, eventuale estensione verso altri nodi o clienti.