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

NetGescon - Macchina Git e Distribuzione (Blueprint 2026)

Obiettivo: una piattaforma unica per piu progetti con:

• repository Git self-hosted,
• distribuzione aggiornamenti,
• accesso selettivo con scadenza,
• moduli premium con pagamento.

Scelta consigliata

Stack consigliato:

• Forgejo (o Gitea) per Git, issue, release e accessi team.
• API Update/Licensing separata (Laravel) per manifest, package, code/auth e policy licenza.
• MinIO per storage pacchetti release e asset aggiornamenti.
• Reverse proxy (Caddy o Nginx) con TLS e domini separati.
• Keycloak opzionale se vuoi SSO enterprise multi-progetto.

Perche Forgejo/Gitea

1. Leggero rispetto a GitLab e facile da mantenere.
2. Multi-progetto nativo con org/team/permessi granulari.
3. Runner CI disponibili per pipeline build package.
4. Facile integrazione con API esterne per licenze e billing.

Architettura consigliata

• git.netgescon.it: Forgejo UI/API/SSH.
• updates.netgescon.it: API update/licensing (manifest/package/license).
• storage.netgescon.it: MinIO S3 (privato, firmato).
• registry.netgescon.it opzionale: container registry.

Modello accessi aggiornamenti

Canali:

• free: accesso manifest/package pubblico o con token base.
• licensed: accesso con code+auth e controlli avanzati.

Controlli raccomandati:

• scadenza licenza (expires_at),
• limite nodi (max_nodes),
• modulo abilitato (modules[]),
• versione minima consentita (min_supported),
• revoca immediata (revoked_at).

Modello commerciale moduli premium

Dati minimi backend licenze:

• customers
• licenses
• license_modules
• payments
• entitlements_audit

Flusso:

1. Cliente acquista piano base o modulo.
2. Payment provider invia webhook.
3. Sistema aggiorna entitlement e scadenza.
4. Nodo client chiama endpoint license-check.
5. Feature gate lato app abilita/disabilita moduli.

Provider pagamento consigliati:

• Stripe (piu rapido per subscription e webhook).
• Paddle se vuoi gestione VAT UE piu assistita.

Sicurezza minima obbligatoria

1. 2FA obbligatoria per admin Forgejo.
2. Backup giornaliero DB+repository+bucket MinIO.
3. Firma manifest release (Ed25519) e verifica lato client.
4. Logging audit su download package e apply update.
5. Secrets solo da vault/env sicuri, mai nel repo.

Setup rapido locale

La base Docker e in:

• scripts/ops/git-stack/docker-compose.yml
• scripts/ops/git-stack/.env.example

Avvio:

cd scripts/ops/git-stack
cp .env.example .env
# modifica password, domini e secret

docker compose --env-file .env up -d

Roadmap operativa consigliata

1. Porta online Forgejo + TLS + backup.
2. Crea org/progetti NetGescon e branch policy.
3. Attiva API update/licensing su updates.netgescon.it.
4. Pubblica primo pacchetto baseline e manifest firmato.
5. Aggiorna staging con php artisan netgescon:update --apply.
6. Integra billing moduli premium (Stripe webhook).
7. Estendi stessa piattaforma agli altri progetti.