Come eseguire il self-hosting di Gitea nel 2026: repository, SSH e sicurezza degli upgrade

Se hai già provato a eseguire il self-hosting di Gitea, probabilmente conosci bene questa situazione frustrante: l'interfaccia è visibile, ma ROOT_URL genera link di clone localhost oppure la porta SSH non viene inoltrata. Ricreare il container risolve raramente un'incoerenza tra URL, stato e dipendenze.

Questa guida utilizza un unico criterio concreto per considerare l'installazione completata: eseguire il clone tramite HTTPS e SSH, fare il push di un commit e di un oggetto LFS, aprire una issue ed eseguire un job su un Actions runner registrato separatamente. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base a un badge verde del container.

Individua ogni byte persistente in Gitea

Elenca lo stato prima di creare il primo record reale: repository, oggetti LFS, allegati, configurazione e database. Monta /data prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è realmente persistente. Conferma il mount scrivendo dati innocui, sostituendo Gitea e rileggendoli.

Gli snapshot sono utili per un rollback rapido, ma serve un backup indipendente quando l'host o il volume scompare. Esegui il restore in un ambiente vuoto con l'immagine fissata a una versione specifica e verifica che i repository superino fsck, che gli oggetti LFS possano essere scaricati e che issue, release e permessi degli utenti corrispondano allo stato precedente al backup. Usa volumi persistenti e snapshot per mantenere distinti questi due meccanismi di ripristino.

Crea un container Gitea sostituibile

Il comando seguente rende visibile il confine del container senza fingere di predisporre ogni servizio esterno.

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

Prima di aprire l'ingress, controlla l'ambiente risolto, i mount e il listener. Per un'installazione più impegnativa, aggiungi le impostazioni di connessione verificate per Postgres o MySQL e, se necessario, un percorso SSH; usa nomi privati per i servizi privati. Un avvio riuscito si conclude quando puoi eseguire il clone tramite HTTPS e SSH, fare il push di un commit e di un oggetto LFS, aprire una issue ed eseguire un job su un Actions runner registrato separatamente, non quando docker ps stampa Up.

Separa Gitea dalle sue dipendenze

Per Gitea, lo stato del processo e lo stato del prodotto sono due cose diverse. La porta 3000 può rispondere mentre la transazione rivolta all'utente continua a fallire. Il contratto di rete per Gitea prevede Postgres o MySQL per un'installazione più impegnativa e un percorso SSH, se necessario. Mantieni gli endpoint privati sul DNS interno, consenti solo le chiamate in uscita necessarie e assegna a Gitea una credenziale di servizio con autorizzazioni limitate.

Usa questo test di readiness dopo modifiche significative alla configurazione: esegui il clone tramite HTTPS e SSH, fai il push di un commit e di un oggetto LFS, apri una issue ed esegui un job su un Actions runner registrato separatamente. Non inserire controlli esterni costosi nelle probe di liveness, così un'interruzione del provider non causa un loop di riavvii. Il lavoro sulla capacità dovrebbe monitorare il numero di repository, il packing degli oggetti Git, lo storage LFS, la latenza del database e il carico dei runner invece delle normali richieste alle pagine: questi indicatori riflettono meglio la pressione reale su Gitea rispetto alle richieste alle pagine.

Il TLS è semplice; gli URL generati no

Esponi un unico hostname HTTPS per Gitea e mantieni privata la porta 3000 non elaborata. Imposta ROOT_URL e SSH_DOMAIN sugli indirizzi da cui gli utenti eseguono effettivamente il clone. In questo modo impedisci a browser e client API di apprendere due indirizzi in conflitto.

Da un client pulito, esegui la transazione verificata e analizza la prima richiesta che fallisce. Usa la guida ai domini personalizzati quando il problema riguarda DNS o TLS. Considera “ROOT_URL genera link di clone localhost oppure la porta SSH non viene inoltrata” come una diagnosi applicativa distinta una volta verificato il percorso.

Verifica il deploy di Gitea end to end

Non usare il traffico del primo utente come test di accettazione per Gitea. Prepara uno stato di esempio innocuo ed esegui l'azione completa “clone tramite HTTPS e SSH, push di un commit e di un oggetto LFS, apertura di una issue ed esecuzione di un job su un Actions runner registrato separatamente”. Annota l'URL pubblico esatto, il risultato, il riferimento all'immagine e l'intervallo dei log associati all'esecuzione.

Sostituisci il container e ripeti l'operazione senza ricreare i dati. Poi esegui il ripristino su un host vuoto; la condizione di ripristino è che i repository superino fsck, che gli oggetti LFS possano essere scaricati e che issue, release e permessi degli utenti corrispondano allo stato precedente al backup. A ogni esecuzione, osserva il numero di repository, il packing degli oggetti Git, lo storage LFS, la latenza del database e il carico dei runner invece delle normali richieste alle pagine, e definisci un alert basato sul degrado della transazione anziché sulle metriche di inattività del container.

Un ultimo controllo dovrebbe fallire intenzionalmente: nega temporaneamente all'identità di test l'accesso a Postgres o MySQL per un'installazione più impegnativa e a un percorso SSH, se necessario. Verifica che il messaggio risultante di Gitea identifichi il confine rilevante invece di attivare l'eliminazione dei dati o un riavvio infinito. Ripristina la condizione valida e conferma che la stessa transazione di esempio vada a buon fine. Mantieni questo breve esercizio nella checklist di release.

Prova la modifica rischiosa di Gitea

Per Gitea, monitora una transazione invece di un processo: esegui il clone tramite HTTPS e SSH, fai il push di un commit e di un oggetto LFS, apri una issue ed esegui un job su un Actions runner registrato separatamente. Combina la latenza e il tasso di errore della transazione con il numero di repository, il packing degli oggetti Git, lo storage LFS, la latenza del database e il carico dei runner invece delle normali richieste alle pagine, così un alert possa identificare il componente sotto pressione.

La prova di upgrade deve tenere conto del fatto che le migrazioni dello schema, gli hook dei repository, i package e i runner di terze parti richiedono un upgrade di Gitea graduale. Esegui il restore, la migrazione e la transazione prima della sostituzione in produzione. Se ROOT_URL genera link di clone localhost oppure la porta SSH non viene inoltrata, non cancellare i dati per rendere verde l'avvio; confronta versione, variabili, mount e raggiungibilità delle dipendenze, in quest'ordine.

Proteggi la parte preziosa di Gitea

Dopo il primo accesso, verifica cosa possono fare un visitatore anonimo, un utente normale e un amministratore. Il problema da evitare in Gitea è lasciare l'installer o il primo account amministratore raggiungibile più a lungo del necessario. La policy prevista consiste nel chiudere l'installer dopo il bootstrap, limitare l'amministrazione del sito e mantenere brevi i token di registrazione dei runner.

Gestisci GITEA__security__SECRET_KEY in base al suo ruolo in Gitea: mantieni i valori sensibili fuori da Git, documenta gli effetti della rotazione e non sostituire mai un esempio pubblico in produzione. Mantieni separati gli account delle dipendenze dagli account umani, nega quando possibile l'egress non utilizzato e limita il lavoro influenzato dal numero di repository, dal packing degli oggetti Git, dallo storage LFS, dalla latenza del database e dal carico dei runner invece delle normali richieste alle pagine.

Cosa dovrebbe automatizzare Dockup per Gitea

Per Gitea, Dockup può creare il percorso e il certificato TLS, preservare i mount, distribuire i secret e collocare Postgres o MySQL per un'installazione più impegnativa e un percorso SSH, se necessario, sulla rete privata, eseguendo il deploy su Dockup o su server collegati.

Il gate di release resta comunque la transazione concreta di Gitea: eseguire il clone tramite HTTPS e SSH, fare il push di un commit e di un oggetto LFS, aprire una issue ed eseguire un job su un Actions runner registrato separatamente. Verifica inoltre la condizione di ripristino: i repository superano fsck, gli oggetti LFS possono essere scaricati e issue, release e permessi degli utenti corrispondono allo stato precedente al backup. Questi due controlli mostrano se il deploy funziona e se può essere ripristinato.

Domande frequenti

Di cosa ha bisogno Gitea per un deploy in produzione?

Instrada il container Gitea sulla porta 3000 attraverso un'unica origine HTTPS. Il requisito di rete di supporto è Postgres o MySQL per un'installazione più impegnativa e un percorso SSH, se necessario. Non considerare Gitea pronto finché non puoi eseguire il clone tramite HTTPS e SSH, fare il push di un commit e di un oggetto LFS, aprire una issue ed eseguire un job su un Actions runner registrato separatamente.

Quali dati di Gitea devono essere inclusi in un backup?

Rendi persistente /data e includi repository, oggetti LFS, allegati, configurazione e database nello stesso manifest di ripristino. Un restore pulito di Gitea è riuscito solo quando i repository superano fsck, gli oggetti LFS possono essere scaricati e issue, release e permessi degli utenti corrispondono allo stato precedente al backup.

Gitea richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Gitea e mantieni la porta 3000 sul percorso interno. Applica correttamente l'impostazione di Gitea: imposta ROOT_URL e SSH_DOMAIN sugli indirizzi da cui gli utenti eseguono effettivamente il clone. Per Gitea, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento dei client sensibile all'origine.

Come si deve testare un upgrade di Gitea?

Esegui il restore dello stato corrente di Gitea in un deploy isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché le migrazioni dello schema, gli hook dei repository, i package e i runner di terze parti richiedono un upgrade di Gitea graduale. Mantieni l'immagine precedente di Gitea finché non saranno chiari i confini della migrazione dei dati e del rollback.