Un server Git tutto suo.
Il repository è l'organigramma.

Quasi ogni discussione sul self-hosting di Git è in realtà una discussione sul codice sorgente, ed è proprio il codice sorgente la parte che conta meno. Gran parte di esso è poco notevole, buona parte è un sottile strato sopra librerie open source, e se trapelasse domani il danno pratico sarebbe di solito imbarazzo più che un vero danno. Questo è il motivo per cui "il mio codice non è segreto" sembra una risposta completa, e il motivo per cui non lo è.

Ciò che circonda il codice è la parte interessante. Un repository è un registro del lavoro datato, attribuito e ad alta risoluzione: i timestamp dei commit descrivono quando dorme, le righe di co-autore descrivono con chi lavora, i nomi dei branch descrivono prodotti che nessuno ha ancora annunciato, un issue tracker descrive cosa è rotto e quanto gravemente, e un primo commit data l'intero progetto. Legga cento repository in questo modo e non starà più leggendo software — starà leggendo un'azienda, la sua roadmap, il suo organico e i suoi guai.

Su una piattaforma, quel registro non è suo in alcun senso significativo. Risiede su un'infrastruttura che non controlla, sotto un account legato a un'identità che ha verificato, in una giurisdizione il cui iter legale può raggiungerlo, scansionato da sistemi il cui ambito è stabilito da un documento che può essere modificato. Niente di tutto ciò richiede malafede da parte di qualcuno: è semplicemente cosa significa affittare il tracker. Quattro configurazioni, e cosa rivela realmente ciascuna:

La terza riga è quella che coglie in fallo i team convinti di aver già risolto il problema. Una forge installata da sé, su una macchina affittata con una carta aziendale sotto un account aziendale verificato, ha spostato l'applicazione fuori dalla piattaforma lasciando l'identità esattamente dov'era. È un guadagno reale in termini di controllo e nessun guadagno in termini di esposizione.

E la quarta riga dichiara apertamente il proprio costo, perché il resto di questa guida riguarda soprattutto il pagarlo. La modalità di fallimento del self-hosting non è la sorveglianza, è la perdita. Una piattaforma mantiene backup a cui lei non pensa mai. Il suo server mantiene i backup che ha configurato lei. Il passo 06 non è la rifinitura opzionale alla fine — è il passo che rende sicuri gli altri cinque.

Prima di tutto ordini il server. Nel pannello: Order → VPS → Sentinel, immagine Debian 12, nel bastione in cui vuole che viva la cronologia — Helsinki, Stockholm, Oslo o Reykjavík. Non è richiesto alcun indirizzo email per aprire l'account e la fattura si salda in Monero, Bitcoin, Lightning o qualsiasi altro asset supportato. Qui questo conta più che per la maggior parte dei carichi di lavoro: una forge è l'unico servizio la cui intera proposta di valore consiste nel fatto che il registro del suo lavoro non è legato a un nome.

Poi esegua la checklist di hardening della prima ora — SSH solo a chiave su una porta spostata, aggiornamenti automatici, un firewall a blocco predefinito — perché tutto ciò che segue presuppone un server che non sia già di qualcun altro.

Punti un hostname sul server — un record A, e un record AAAA se vuole che sia raggiungibile via IPv6 — e lo lasci propagare prima di iniziare, perché il reverse proxy proverà a ottenere un certificato per quel nome al primo avvio, e una challenge fallita è un modo confuso di cominciare. Poi scriva le regole del firewall mentre ancora nulla è in ascolto.

Il problema dei due SSH. Una forge parla SSH per Git, e il suo server parla già SSH per l'amministrazione. Non possono possedere entrambi la porta 22, e mescolarli è il modo in cui si finisce con un demone amministrativo che deve anche capire Git. Li tenga separati: l'amministrazione sulla porta spostata secondo la guida di hardening, Git su una porta pubblica dedicata che si mappa nel container. 2222 è la scelta convenzionale e non ha nulla di sacro.

ufw default deny incoming
ufw allow 47222/tcp                  # administrative SSH, moved
ufw allow 80/tcp                     # ACME HTTP-01 challenge
ufw allow 443/tcp                    # the web interface
ufw allow 2222/tcp                   # git over SSH, into the container
ufw enable
ufw status numbered

# Nothing else is open. In particular: PostgreSQL stays on the Docker
# network and is never published to the host, let alone the internet.

Installi Docker dal repository ufficiale anziché dal pacchetto della distribuzione, in modo che Compose v2 sia presente e la versione sia aggiornata. Poi crei una directory per lo stack e la renda l'unico posto sul server che conserva stato — è la directory di cui il passo 06 fa il backup.

curl -fsSL https://get.docker.com | sh
docker compose version

install -d -m 0750 /srv/forgejo
cd /srv/forgejo

Incolli la sua chiave pubblica nelle impostazioni del profilo, poi insegni al suo client dove si trova la forge. Poiché Git è su una porta non standard, una voce nella sua configurazione SSH vale i trenta secondi che richiede — tiene la porta fuori da ogni URL che dovrà mai digitare e rende i remote portabili.

# ~/.ssh/config
Host git.example.com
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519

# Then, in any repository:
git remote set-url origin git@git.example.com:you/project.git
git push -u origin main
ssh -T git@git.example.com        # expect a greeting, not a shell

Quell'ultimo comando è quello che le dice se il mapping della porta, il server SSH del container e la sua chiave sono tutti d'accordo tra loro. Un saluto da parte di Forgejo significa che l'intera catena funziona. Una richiesta di password significa che ha invece raggiunto lo sshd amministrativo dell'host, e il mapping della porta è sbagliato.

Ora firmi i suoi commit. Questo è il passo che la maggior parte delle guide al self-hosting salta, e su una forge self-hosted conta più che su una piattaforma. Il campo autore di un commit è testo libero — chiunque possa fare push può scriverci il suo nome. Una firma è la prova che una chiave specifica ha creato un commit specifico, e resta una prova anche dopo che il server su cui è stato inviato con il push è stato compromesso, migrato o gettato via. Git può firmare con la chiave SSH che ha già, quindi non c'è più bisogno di alcuna deviazione tramite PGP:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

git commit --allow-empty -m "signed"
git log --show-signature -1

Poi aggiunga la stessa chiave pubblica una seconda volta nella forge, come chiave di firma invece che come chiave di autenticazione. Forgejo verifica la firma lato server e mostra il commit come verificato; senza quella seconda voce non ha modo di collegare la firma al suo account, e ogni commit risulta non verificato anche se è firmato correttamente.

Deploy key, per le macchine che si limitano a leggere. Un server di produzione, una macchina di build o un mirror non hanno bisogno di un account utente sulla forge. Le dia invece una deploy key: una coppia di chiavi aggiunta a un repository, di sola lettura a meno che non conceda esplicitamente la scrittura, che non dà accesso a nient'altro sull'istanza. Revocarla significa eliminare una sola voce. Questa è l'abitudine singolarmente più efficace per mantenere ordinata una forge self-hosted, perché gli account utente accumulano permessi, mentre le deploy key non possono.

Migrare da una piattaforma è un buon momento per fare tutto questo per bene. Il flusso New Migration di Forgejo prende un URL di repository e un access token e importa branch, tag, issue, commenti, etichette, milestone, release e pull request. Esegua prima un repository per vedere che forma ha il risultato, si aspetti che i rate limit dell'API rallentino i lotti grandi, e mantenga l'origine in sola lettura per qualche settimana invece di eliminarla lo stesso giorno.

Git qui è insolitamente indulgente, e vale la pena essere precisi sul perché. Ogni clone è una copia completa della cronologia, quindi finché uno sviluppatore ha una copia di lavoro aggiornata, il codice sopravvive al server. Questo è genuinamente rassicurante, e copre esattamente una delle due cose che la sua forge conserva. L'altra — issue, discussioni delle pull request, thread di revisione, release, pagine wiki, utenti, team, permessi, cronologia della CI — esiste solo nel database, nessuno ne ha un clone, ed è di solito la parte che ha richiesto tre anni per accumularsi.

Prima di tutto, un push mirror. È gratuito e si gestisce da solo. In un repository: Settings → Mirror settings → aggiunga un push mirror con l'URL e un access token per la destinazione. Forgejo replica poi ogni branch e tag dopo ciascun push, verso un secondo Forgejo, verso Codeberg, o verso una piattaforma che ha deciso di mantenere come vetrina anziché come casa. Un avvertimento che vale la pena dichiarare apertamente: un push mirror ripubblica la cronologia fedelmente, incluso un secret che intendeva rimuovere.

Poi un backup vero, che non è l'archivio integrato. Forgejo include un comando forgejo dump che impacchetta configurazione, repository, dati e un dump del database in un unico zip. È una cosa genuinamente utile da consegnare a un maintainer quando si segnala un bug. Non è ciò su cui dovrebbe fare affidamento per tornare in vita dopo un disastro: l'SQL che produce ha problemi noti di lunga data in fase di re-importazione, e l'archivio riscrive l'intero set di repository a ogni esecuzione, il che su un'istanza reale significa un file di grandi dimensioni scritto da zero ogni notte. Usi invece il percorso noioso e verificabile — faccia il dump del database con lo strumento nativo del database, e faccia il backup della directory dei dati come file:

#!/bin/sh
# /usr/local/bin/forgejo-backup — run from a systemd timer, nightly
set -eu
cd /srv/forgejo

# 1. Consistent database dump, written next to the data.
docker compose exec -T db pg_dump -U forgejo -Fc forgejo > ./db.dump

# 2. Everything that matters, to an encrypted offsite repository.
restic backup ./data ./db.dump ./docker-compose.yml ./.env ./Caddyfile

# 3. Retention, then prove the repository is still readable.
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune
restic check

Lo invii a una macchina in una giurisdizione diversa da quella della forge, tramite un repository append-only, in modo che una compromissione della forge non possa cancellare la propria stessa cronologia — la guida ai backup cifrati è la versione estesa delle tre righe sopra, incluso il timer systemd e la restrizione della chiave append-only.

Poi lo ripristini una volta, di proposito. Ordini un VPS usa e getta, ripristini lo snapshot al suo interno, avvii lo stesso file Compose puntato sulla directory dati ripristinata, carichi il dump del database, punti su di esso una voce del file hosts ed effettui l'accesso. Cronometri l'intera operazione. Quel numero — non l'esistenza del job di backup — è la sua reale posizione di recupero, e chiunque abbia fatto questo esercizio ha trovato almeno una cosa mancante dall'elenco degli elementi inclusi la prima volta.

# restic keeps absolute paths, so the stack reappears under the target.
restic restore latest --target /srv/restore
cd /srv/restore/srv/forgejo

docker compose up -d db                # empty volume: the entrypoint creates the database
docker compose exec -T db pg_restore -U forgejo -d forgejo \
  --clean --if-exists --no-owner < db.dump

docker compose up -d                   # then sign in and walk the issue tracker

Aggiornamenti, in breve. Blocchi l'immagine su una versione principale invece che su :latest, così un pull non presidiato non può farla passare attraverso un breaking change mentre dorme. Legga le release notes prima di attraversare un confine di versione principale, prenda prima uno snapshot, e ricordi che una migrazione del database viene eseguita al primo avvio della nuova versione — il che è una porta a senso unico. L'auto-aggiornamento in stile Watchtower è una buona idea per un sito statico e una pessima idea per la macchina che conserva ogni branch che lei possiede.

Quattro controlli prima di dichiararsi soddisfatti. Esca dall'account e verifichi che l'istanza non offra alcun modo per creare un account. Da un browser senza sessione, verifichi che un repository privato risulti invisibile e non semplicemente vietato. Verifichi che il runner non possa leggere la directory dati della forge. E verifichi che l'ultimo restic check sia passato — il job di backup che fallisce in silenzio è quello che hanno tutti, fino al giorno in cui ne hanno bisogno.