Forgejo Docker Compose: come installarlo su un server di casa

di Matteo Rinaldi redattore IA 16 ottobre 2026, 12:35

Illustrazione 3D di persone attorno a un home server contenente container trasparenti e laptop su una scrivania. — Immagine generata con IA

Questa guida è per chi ha un server di casa o un computer Linux sempre acceso con Docker e vuole tenere i propri repository Git su Forgejo. Alla fine avrete un’istanza avviata con Docker Compose. Si raggiunge dal browser sulla porta 3000 e via SSH sulla porta 222, usa SQLite o PostgreSQL come database, ha un account amministratore e non accetta registrazioni libere. Secondo la guida all’aggiornamento di Forgejo, Forgejo è un hard fork di Gitea. La migrazione da Gitea qui non è trattata. I comandi sono quelli della documentazione ufficiale di Forgejo e di Docker, elencata in fondo.

Cosa serve

Una macchina con Docker Engine e la Docker CLI già installati. La pagina di Docker sul plugin Compose dà per scontato che ci siano.
Il plugin Docker Compose. Il prossimo passaggio spiega come controllare se c’è.
Docker in versione 20.10.6 o successiva. La guida all’aggiornamento avverte che con versioni più vecchie le installazioni Docker di Forgejo hanno problemi difficili da capire.
Le porte 3000 (interfaccia web) e 222 (SSH) della macchina, che il file compose dell’esempio ufficiale collega al container.
Un browser, sul server stesso o su un altro computer che lo raggiunge con il suo indirizzo IP locale.

Le pagine di Docker usate qui spiegano l’installazione di Compose solo su Linux: questa guida non copre altri sistemi.

Controllare che Docker Compose sia installato

Tutta la guida usa il comando docker compose, quindi prima di cominciare conviene controllare che il plugin risponda. È lo stesso controllo che Docker indica a fine installazione.

docker compose version

Se il terminale mostra un numero di versione, il plugin c’è. Se il comando non viene riconosciuto, seguite la guida di Docker: su Ubuntu e Debian si installa il pacchetto docker-compose-plugin dal repository di Docker, sulle distribuzioni basate su RPM si usa yum. Dopo l’installazione ripetete il controllo.

Creare la cartella dei dati di Forgejo

Scegliete una cartella per il progetto: lì metterete il file docker-compose.yml. Dentro serve una sottocartella forgejo, il volume del container per configurazione, repository e database SQLite. Lanciate il comando dalla cartella del progetto:

mkdir -p ./forgejo

Nella cartella del progetto c’è ora la sottocartella forgejo, vuota.

Scrivere il docker-compose.yml

Nella cartella del progetto create un file di testo chiamato docker-compose.yml. Copiatelo dall’esempio della pagina Installation with Docker, da tenere aperta perché le voci vanno riportate esatte. Le sottosezioni qui sotto spiegano cosa contiene.

Immagine e tag

Il servizio si chiama server e usa l’immagine pubblicata su Codeberg. Al 16 ottobre 2026 la versione stabile più recente è Forgejo 17.0, supportata fino al 28 gennaio 2027, secondo la pagina dei rilasci. La pagina della documentazione v17.0 riporta però ancora nell’esempio il tag codeberg.org/forgejo/forgejo:16, la serie il cui supporto termina il 29 ottobre 2026: per una nuova installazione usate il tag 17 al suo posto (17-rootless nella variante rootless). Il tag con il solo numero principale, per esempio 16, punta sempre all’ultima versione minore di quella serie. Il tag 16.0 punta invece all’ultima patch. Il passaggio da una versione principale alla successiva richiede un intervento manuale e una verifica. Prima di scrivere il file, controllate il tag sulla pagina.

Porte, volumi e utente

Il servizio server nell’esempio ufficiale ha queste voci:

container_name: forgejo e restart: always;
le variabili USER_UID=1000 e USER_GID=1000 in environment;
i volumi ./forgejo:/data (i dati) e /etc/localtime:/etc/localtime:ro (l’ora del sistema, in sola lettura);
le porte '3000:3000' per l’interfaccia web e '222:22': la porta 222 della macchina porta alla 22 del container, cioè all’SSH di Forgejo;
una rete forgejo con external: false, dichiarata in cima al file e assegnata al servizio.

La cartella del volume deve appartenere all’utente e al gruppo con l’UID e il GID scritti nel file, qui 1000 e 1000. Con permessi sbagliati il container potrebbe non partire. Controllate il proprietario della cartella forgejo appena creata: se non è l’utente 1000 con il gruppo 1000, per esempio perché il vostro utente ha un altro UID, assegnatela con lo stesso comando che la documentazione usa per l’immagine rootless.

Attenzione: questo comando usa i privilegi di amministratore per cambiare il proprietario della cartella ./forgejo e di tutto quello che contiene. Il percorso è relativo, quindi lanciatelo solo dalla cartella del progetto, quella con la sottocartella forgejo. Non cancella nulla, ma dalla cartella sbagliata cambiano proprietario i file di altri utenti o programmi, che potrebbero smettere di funzionare. I due numeri di 1000:1000 devono coincidere con USER_UID e USER_GID: se nel file avete messo altri valori, scrivete quelli.

sudo chown -R 1000:1000 ./forgejo

SQLite o PostgreSQL

Se nel file non configurate un database, Forgejo usa SQLite e non serve un secondo servizio. Secondo la pagina sull’installazione da binario, SQLite basta almeno per una decina di utenti, forse anche per qualcuno in più.

Per PostgreSQL la documentazione ha il blocco «PostgreSQL database». Vanno aggiunte due cose:

Nel servizio server: le variabili FORGEJO__database__DB_TYPE=postgres, FORGEJO__database__HOST=db:5432, FORGEJO__database__NAME=forgejo, FORGEJO__database__USER=forgejo e FORGEJO__database__PASSWD=forgejo, più depends_on con la voce db.
Un secondo servizio db con immagine postgres:14, restart: always, le variabili POSTGRES_USER=forgejo, POSTGRES_PASSWORD=forgejo e POSTGRES_DB=forgejo, la rete forgejo e il volume ./postgres:/var/lib/postgresql/data.

I valori forgejo dell’esempio ufficiale sono segnaposto: sostituiteli con valori vostri, soprattutto la password. Nome del database, utente e password devono essere identici in due posti, cioè nelle variabili FORGEJO__database__ del servizio server e nelle variabili POSTGRES_ del servizio db. La pagina ha anche un esempio con MySQL (mysql:8), costruito allo stesso modo.

Facoltativo: usare l’immagine rootless

L’immagine rootless usa un altro percorso per i dati e ha un server SSH integrato su una porta diversa. L’esempio ufficiale parte dal file con PostgreSQL e cambia queste voci:

Voce	Immagine standard	Immagine rootless
`image`	`codeberg.org/forgejo/forgejo:16`	`codeberg.org/forgejo/forgejo:16-rootless`
`user`	non presente	`1000:1000`
Volume dei dati	`./forgejo:/data`	`./forgejo:/var/lib/gitea`
Porta SSH	`222:22`	`222:2222`

Con l’immagine rootless la documentazione chiede di impostare sempre i permessi della cartella collegata, con proprietario utente e gruppo 1000 come nella voce user.

Attenzione: il comando cambia con i privilegi di amministratore il proprietario della cartella ./forgejo e di tutto il suo contenuto. Lanciatelo solo dalla cartella del progetto, quella con docker-compose.yml e la sottocartella forgejo. Non cancella nulla, ma con un percorso sbagliato i file di altri utenti o programmi cambierebbero proprietario e potrebbero smettere di funzionare. Il valore 1000:1000 deve essere uguale a quello della voce user: se ne avete messo un altro, scrivete quello.

sudo chown -R 1000:1000 ./forgejo

Variante per Raspberry Pi

Sui Raspberry Pi Docker a volte ha problemi a rimappare i permessi delle cartelle montate, anche se la rimappatura non è attiva: con la configurazione rootless qui sopra Forgejo non riesce a creare file in ./forgejo. La pagina Docker di Forgejo propone di passare a volumi con nome che restano collegati alle stesse cartelle. Servono tre modifiche:

In cima al file, accanto a networks, dichiarate una sezione volumes con due voci, forgejo-data e postgres-data, ciascuna con driver: local e, sotto driver_opts, le opzioni type: none, o: bind e device.
Nel servizio server sostituite il montaggio ./forgejo:/var/lib/gitea con forgejo-data:/var/lib/gitea; nel servizio db sostituite ./postgres:/var/lib/postgresql/data con postgres-data:/var/lib/postgresql/data. Dichiarare i volumi senza cambiare questi montaggi non basta: i servizi continuerebbero a usare le cartelle come prima.
In device non usate i percorsi relativi ./forgejo e ./postgres dell’esempio di Forgejo. La documentazione dei volumi di Docker Compose chiede il percorso assoluto di una cartella che esiste già. Dalla cartella del progetto il comando pwd stampa il suo percorso: aggiungete /forgejo per il volume forgejo-data e /postgres per postgres-data. Prima del primo avvio la cartella postgres deve esistere accanto a forgejo: createla allo stesso modo.

Avviare Forgejo con Docker Compose

Con il file pronto, i servizi si avviano in modalità detached: i container girano in background e il terminale resta libero. Al primo avvio Docker scarica le immagini, poi crea e lancia i servizi. Date il comando dalla cartella del progetto:

docker compose up -d

Con PostgreSQL partono due servizi, server e db; con SQLite solo server.

Controllare i log dell’avvio

Per vedere se Forgejo è partito senza errori, seguite in tempo reale i log di tutti i servizi. Ogni riga ha davanti il nome del servizio.

docker compose logs -f

Per smettere di seguire i log premete Ctrl+C: i container restano accesi. Se il container forgejo si ferma o riparte di continuo, guardate la sezione sui problemi più sotto.

Completare la configurazione iniziale dal browser

Aprite il browser su http://localhost:3000. Se il browser è su un’altra macchina, mettete l’indirizzo IP locale del server al posto di localhost. Compare la schermata «Initial Configuration», per cui la documentazione dà qualche indicazione:

scegliete il database: SQLite3 se non ne avete configurato un altro, altrimenti PostgreSQL, con gli stessi valori del file compose;
in Server Domain scrivete il nome con cui raggiungete il server (l’esempio della documentazione è git.example.com);
in Forgejo Base URL scrivete l’indirizzo completo con la porta, per esempio http://git.example.com:3000;
date un’occhiata alle sezioni Server and Third-Party Service Settings;
create subito l’amministratore in Administrator Account Settings, a maggior ragione se poi chiuderete le registrazioni.

Prima di premere Install Forgejo, controllate la porta SSH mostrata negli URL di clonazione: l’impostazione SSH_PORT vale 22 per impostazione predefinita, mentre la mappatura del file compose espone la porta 222. Potete impostarla a 222 aggiungendo FORGEJO__server__SSH_PORT=222 al blocco environment del servizio server prima del primo avvio. Se avete già avviato il container, eseguite nuovamente docker compose up -d dalla cartella del progetto, quindi ricaricate la schermata iniziale e controllate la porta SSH. Poi premete Install Forgejo. Dopo qualche secondo compare la dashboard, se avete creato l’amministratore, oppure la schermata di accesso e registrazione. Quasi tutte queste impostazioni si possono cambiare in seguito nel file app.ini, che l’immagine di Forgejo crea da sola se non esiste.

Chiudere le registrazioni libere

Su un server personale conviene che i nuovi account li crei solo l’amministratore. Per farlo c’è l’opzione DISABLE_REGISTRATION nella sezione [service] di app.ini. Il Configuration Cheat Sheet spiega che, se impostata a true, solo l’amministratore può creare gli account.

Con l’immagine standard app.ini si trova nei dati di Forgejo, quindi nella cartella ./forgejo collegata a /data. La pagina Docker però non dice in quale sottocartella sia il file. Usate quindi una variabile d’ambiente nel formato FORGEJO__[SECTION]__[KEY], che equivale a scrivere il valore in app.ini. Nel blocco environment del servizio server aggiungete la riga FORGEJO__service__DISABLE_REGISTRATION=true.

Con una variabile d’ambiente non si può cancellare un valore già presente: per toglierlo bisogna modificare app.ini. Le modifiche alla configurazione hanno effetto solo dopo un riavvio completo di Forgejo, per esempio con docker compose down seguito da docker compose up -d.

Fermare e rimuovere i container

Per spegnere Forgejo, per esempio prima di cambiare il file compose, si fermano e si rimuovono i container. La guida rapida di Docker Compose spiega che così si perde tutto quello che stava solo nel livello scrivibile del container. In questa configurazione i dati sono in cartelle collegate, ./forgejo e, con PostgreSQL, ./postgres, quindi restano sul disco.

docker compose down

Non aggiungete l’opzione -v per abitudine: la stessa guida avverte che rimuove anche i volumi con nome e cancella per sempre i dati salvati lì. Il rischio riguarda i normali volumi gestiti da Docker. I volumi della variante per Raspberry Pi sono invece bind mount con nome: rimuoverli non cancella il contenuto delle cartelle forgejo e postgres sul disco.

Se qualcosa va storto

Il container non parte. Controllate che la cartella del volume appartenga all’UID e al GID del file compose. Se non è così, usate il comando chown della sezione «Porte, volumi e utente».
codeberg.org non risponde. In tutto il file potete mettere data.forgejo.org al posto di codeberg.org: è il mirror ufficiale.
Raspberry Pi con immagine rootless. Se Forgejo non riesce a creare file in ./forgejo, applicate la «Variante per Raspberry Pi» descritta sopra, con i montaggi dei servizi sostituiti e i percorsi assoluti in device.
Sistemi con SELinux. Se i container danno problemi, guardate nei log di audit.
L’interfaccia non si apre. Se il browser non è sul server, usate l’indirizzo IP locale del server al posto di localhost.

Documentazione di riferimento

Pagine consultate il 16 ottobre 2026. Le pagine di Forgejo sono della documentazione v17.0. Le pagine di Docker sull’installazione di Compose riguardano Linux.