Ogni tanto capita di guardare la propria organizzazione su GitHub e chiedersi quanto di quel codice sia davvero nostro. Non in senso legale ma in senso operativo: dove vive, chi ne detiene le chiavi, cosa succede il giorno in cui cambiano i termini di servizio o il piano gratuito diventa meno gratuito.
Per un homelab è una curiosità. Per chi gestisce script, playbook e configurazioni di infrastrutture altrui, è una domanda che prima o poi presenta il conto.
Forgejo è la risposta più elegante che ho trovato a questa domanda.
È un forge Git self-hosted: repository, pull request, issue, wiki, registry pacchetti e una CI compatibile con la sintassi di GitHub Actions, il tutto in un singolo binario scritto in Go che gira sereno in mezzo giga di RAM.
Non è un GitLab in miniatura, ed è esattamente questo il punto: fa quello che serve davvero, senza portarsi dietro Redis, Sidekiq, Gitaly e otto giga di requisiti minimi.
Nasce nel 2022 come fork di Gitea, quando marchio e domini di quest’ultimo sono passati a una società for-profit. Oggi vive sotto Codeberg e.V., un’associazione non-profit tedesca, con licenza GPL e una governance pubblica.
È la stessa piattaforma che regge Codeberg.org con oltre centomila utenti e non è esattamente un progetto sperimentale.
In questa guida lo installiamo su Ubuntu Server 26.04 LTS partendo da zero: database PostgreSQL, utente di servizio dedicato, deploy da binario con verifica GPG, unit systemd irrobustita, reverse proxy Nginx con certificato Let’s Encrypt e configurazione iniziale.
Alla fine avrai un’istanza raggiungibile in HTTPS, pronta per accogliere il primo git push.
Mettiamoci al lavoro.
PREREQUISITI
- Ubuntu 26.04 LTS (server), accesso sudo
- 2 vCPU / 2 GB RAM / 20 GB disco come minimo ragionevole (Forgejo da solo gira anche con meno, ma le Actions e i repo crescono)
- Un record DNS
A/AAAAche punta al server, ad esempiogit.miodominio.tld - Porte 80 e 443 raggiungibili (o solo interne, se pubblichi tramite un altro proxy)
AGGIORNAMENTO DEL SISTEMA
Aggiornare il sistema e installare le dipendenze con i comandi:
|
0
1
|
sudo apt update && sudo apt upgrade -y
sudo apt install -y git git-lfs curl xz-utils gnupg ca-certificates
|
Verificare la versione di Git (Forgejo 16 richiede Git ≥ 2.34) con il comando:
|
0 |
git --version
|
Dovremmo visualizzare un output simile al seguente:
|
0 |
git version 2.53.0
|
INSTALLAZIONE DATABASE POSTGRESQL
SQLite funziona ed è comodo per test, ma per un’istanza destinata a durare consiglio PostgreSQL.
|
0
1
|
sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
|
Creare utente e database con i comandi:
|
0 |
sudo -u postgres psql
|
Quindi eseguire i comandi SQL:
|
0
1
2
|
CREATE ROLE forgejo WITH LOGIN PASSWORD 'PASSWORD_MOLTO_ROBUSTA';
CREATE DATABASE forgejo WITH OWNER forgejo TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'C.UTF-8' LC_CTYPE 'C.UTF-8';
\q
|
NOTA BENE: TEMPLATE template0 con collation C.UTF-8 evita problemi di ordinamento e di ricostruzione indici dopo un upgrade di PostgreSQL. Annota la password: ti servirà nel wizard.
Eseguire un Test di connessione con il comando:
|
0 |
psql -h 127.0.0.1 -U forgejo -d forgejo -c '\conninfo'
|
Quindi inserire la password dell’utente creato poco fa
Se è tutto OK dovremmo visualizzare un output simile al seguente:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
Connection Information
Parameter | Value
----------------------+------------------------
Database | forgejo
Client User | forgejo
Host | 127.0.0.1
Server Port | 5432
Options |
Protocol Version | 3.0
Password Used | true
GSSAPI Authenticated | false
Backend PID | 34026
SSL Connection | true
SSL Library | OpenSSL
SSL Protocol | TLSv1.3
SSL Key Bits | 256
SSL Cipher | TLS_AES_256_GCM_SHA384
SSL Compression | false
ALPN | postgresql
Superuser | off
Hot Standby | off
(18 rows)
|
CREAZIONE UTENTE DU SISTEMA E STRUTTURA DELLE DIRECTORY
Forgejo non va mai eseguito come root. Creare un utente di servizio git con il comando:
|
0
1
|
sudo adduser --system --shell /bin/bash --gecos 'Forgejo Git Service' \
--group --disabled-password --home /home/git git
|
Configurare le directory di dati con i seguenti comandi:
|
0
1
2
3
4
|
sudo mkdir -p /var/lib/forgejo /etc/forgejo
sudo chown -R git:git /var/lib/forgejo
sudo chmod 750 /var/lib/forgejo
sudo chown root:git /etc/forgejo
sudo chmod 770 /etc/forgejo
|
NOTA BENE: /etc/forgejo resta scrivibile finché il wizard web non ha generato app.ini
DOWNLOAD E VERIFICA DEL FILE BINARIO
Impostare le variabili (adatta versione e architettura linux-amd64 o linux-arm64):
|
0
1
2
|
FORGEJO_VERSION=16.0.1
FORGEJO_ARCH=linux-amd64
BASE="https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}"
|
Scaricare il binario quindi firma e checksum:
|
0
1
2
3
|
cd /tmp
curl -fLO "${BASE}/forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}"
curl -fLO "${BASE}/forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}.asc"
curl -fLO "${BASE}/forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}.sha256"
|
Verificare lo SHA256 con il comando:
|
0 |
sha256sum -c "forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}.sha256"
|
Dovremmo visualizzare un output simile al seguente:
|
0 |
forgejo-16.0.1-linux-amd64: OK
|
Verificare la firma GPG (chiave di release Forgejo) con il comando:
|
0
1
2
|
gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify "forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}.asc" \
"forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}"
|
Dovremmo visualizzare un output simile al seguente:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
|
gpg: directory '/root/.gnupg' created
gpg: keybox '/root/.gnupg/pubring.kbx' created
gpg: /root/.gnupg/trustdb.gpg: trustdb created
gpg: Total number processed: 1
gpg: imported: 1
gpg: Signature made Tue 21 Jul 2026 08:34:47 AM UTC
gpg: using EDDSA key 3BF4E813F84812411DA01E5BC4186DF66F4B6750
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: EB11 4F5E 6C0D C2BC DD18 3550 A4B6 1A2D C592 3710
Subkey fingerprint: 3BF4 E813 F848 1241 1DA0 1E5B C418 6DF6 6F4B 6750
|
NOTA BENE: L’avviso sulla chiave “not certified with a trusted signature” è normale: significa solo che non hai firmato tu quella chiave.
Procedere con l’installazione con il comando:
|
0 |
sudo install -m 755 "forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}" /usr/local/bin/forgejo
|
fare il check con il comando:
|
0 |
forgejo --version
|
Dovremmo visualizzare un output simile al seguente:
|
0 |
forgejo version 16.0.1+gitea-1.22.0 (release name 16.0.1) built with GNU Make 4.4.1, go1.26.5 : bindata, timetzdata, sqlite, sqlite_unlock_notify
|
CONFIGURAZIONE DEL SYSTEMD
Eseguire il comando:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
sudo tee /etc/systemd/system/forgejo.service > /dev/null <<'EOF'
[Unit]
Description=Forgejo (Beyond coding. We forge.)
After=network-online.target
Wants=network-online.target
After=postgresql.service
Requires=postgresql.service
[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/forgejo/
RuntimeDirectory=forgejo
RuntimeDirectoryMode=0750
ExecStart=/usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/forgejo
# Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=false
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
LockPersonality=true
[Install]
WantedBy=multi-user.target
EOF
|
Quindi fare un reload e abilitare Forgejo con i comandi:
|
0
1
2
|
sudo systemctl daemon-reload
sudo systemctl enable --now forgejo
sudo systemctl status forgejo --no-pager
|
Se è tutto OK dovremmo visualizzare il seguente output:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
● forgejo.service - Forgejo (Beyond coding. We forge.)
Loaded: loaded (/etc/systemd/system/forgejo.service; enabled; preset: enabled)
Active: active (running) since Sat 2026-07-25 13:44:14 UTC; 4s ago
Invocation: 7ce8cc3c82a94da388640ce1a5d8bcd2
Main PID: 34277 (forgejo)
Tasks: 8 (limit: 6210)
Memory: 92.3M (peak: 92.4M)
CPU: 450ms
CGroup: /system.slice/forgejo.service
└─34277 /usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:114:showWebStartupMessage() [I] Forgejo version: 16.0.1+gitea-1.22.0 built with G…nlock_notify
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:115:showWebStartupMessage() [I] * RunMode: prod
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:116:showWebStartupMessage() [I] * AppPath: /usr/local/bin/forgejo
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:117:showWebStartupMessage() [I] * WorkPath: /var/lib/forgejo
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:118:showWebStartupMessage() [I] * CustomPath: /var/lib/forgejo/custom
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:119:showWebStartupMessage() [I] * ConfigFile: /etc/forgejo/app.ini
Jul 25 13:44:14 vm-srv-test forgejo[34277]: 2026/07/25 13:44:14 cmd/web.go:120:showWebStartupMessage() [I] Prepare to run install page
Jul 25 13:44:15 vm-srv-test forgejo[34277]: Listen: http://0.0.0.0:3000
Jul 25 13:44:15 vm-srv-test forgejo[34277]: AppURL(ROOT_URL): http://localhost:3000/
Jul 25 13:44:15 vm-srv-test forgejo[34277]: Starting new Web server: tcp:0.0.0.0:3000 on PID: 34277
Hint: Some lines were ellipsized, use -l to show in full.
|
Controllare i log in caso di problemi con il comando:
|
0 |
sudo journalctl -u forgejo -f
|
A questo punto Forgejo è in ascolto su http://127.0.0.1:3000 (di default sull’interfaccia 0.0.0.0, che restringeremo dopo il wizard).
INSTALLAZIONE E CONFIGURAZIONE DEL REVERSE PROXY
Installare Nginx con il comando:
|
0 |
sudo apt install -y nginx
|
Configurazione del vhost:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
sudo tee /etc/nginx/sites-available/forgejo.conf > /dev/null <<'EOF'
server {
listen 80;
listen [::]:80;
server_name git.miodominio.tld;
# Necessario per push/pull di repository di grandi dimensioni
client_max_body_size 512M;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Evita timeout su operazioni Git lunghe
proxy_read_timeout 300s;
proxy_send_timeout 300s;
proxy_request_buffering off;
}
}
EOF
|
Quindi eseguire i comandi:
|
0
1
2
|
sudo ln -s /etc/nginx/sites-available/forgejo.conf /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
|
CONFIGURAZIONE DEL CERTIFICATO LET’S ENCRYPT
Eseguire i comandi:
|
0
1
|
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d git.miodominio.tld
|
Certbot aggiunge il blocco listen 443 ssl, il redirect da HTTP e imposta il rinnovo automatico via systemd timer.
Configurare il firewall con i comandi:
|
0
1
2
|
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
|
ATTENZIONE: In homelab: se usi una CA interna (es. Windows CA con certificato wildcard) o un proxy centralizzato come Nginx Proxy Manager / Caddy, salta Certbot e limita l’esposizione della 3000 alla sola rete di gestione.
CONFIGURAZIONE INIZIALE VIA WEB
Aprire da un qualsiasi https://git.miodominio.tld/. Comparirà il wizard di installazione.
Di seguito tutti i valori da inserire:
Database
- Tipo: PostgreSQL
- Host: 127.0.0.1:5432
- Utente: forgejo
- Password: quella impostata in precedenza
- Nome database: forgejo
- SSL: Disable (connessione locale)
Impostazioni generali
- Site Title: il nome della tua istanza
- Repository Root Path:
/var/lib/forgejo/data/forgejo-repositories - LFS Root Path:
/var/lib/forgejo/data/lfs - Run As Username:
git - SSH Server Domain:
git.miodominio.tld - SSH Port:
22 - Forgejo HTTP Listen Port:
3000 - Forgejo Base URL:
https://git.miodominio.tld/ - Log Path:
/var/lib/forgejo/log
Impostazioni opzionali
- Email Settings: server SMTP, se vuoi notifiche e reset password funzionanti
- Server and Third-Party Service Settings: spunta **Disable Self-Registration** e **Require Sign-In to View Pages** se l’istanza è privata
- Administrator Account Settings: **crea qui l’account amministratore**. Se non lo fai, il primo utente registrato diventa admin — non è quello che vuoi su un’istanza esposta.
Al termine cliccare Installare Forgejo
A questo punto Il file /etc/forgejo/app.ini viene generato e il servizio si riavvia.
Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di ForgeJo
HARDENING POST INSTALLAZIONE
Rendere la configurazione in sola lettura per il servizio con i comandi:
|
0
1
|
sudo chmod 750 /etc/forgejo
sudo chmod 640 /etc/forgejo/app.ini
|
Far ascoltare Forgejo solo su localhost, dato che davanti c’è Nginx. Modificare il file di configurazione /etc/forgejo/app.ini:
|
0
1
2
3
4
|
[server]
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000
ROOT_URL = https://git.miodominio.tld/
DOMAIN = git.miodominio.tld
|
Di seguito alcune direttive utili da aggiungere o verificare:
|
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true
ENABLE_NOTIFY_MAIL = true
[security]
INSTALL_LOCK = true
PASSWORD_COMPLEXITY = lower,upper,digit,spec
MIN_PASSWORD_LENGTH = 12
[session]
COOKIE_SECURE = true
[log]
LEVEL = Info
|
Riavviare Forgejo con il comando:
|
0 |
sudo systemctl restart forgejo
|
VERIFICA FUNZIONALE
Creare un repository di test dalla UI, poi da una macchina client:
|
0
1
2
3
4
|
# HTTPS
git clone https://git.miodominio.tld/tuo-utente/test.git
# SSH (dopo aver caricato la tua chiave pubblica nel profilo)
git clone git@git.miodominio.tld:tuo-utente/test.git
|
Se l’SSH non funziona controllare che la chiave sia stata scritta in /home/git/.ssh/authorized_keys e che i permessi siano 700 sulla directory e 600 sul file.
BACKUP DI FORGEJO
Forgejo include un comando di dump che raccoglie database, repository, allegati e configurazione:
|
0
1
2
|
sudo -u git bash -c 'cd /var/lib/forgejo && \
/usr/local/bin/forgejo dump --config /etc/forgejo/app.ini \
--file /var/lib/forgejo/backup/forgejo-dump-$(date +%F).zip'
|
Creare prima la directory (sudo -u git mkdir -p /var/lib/forgejo/backup) e schedulare il comando con un timer systemd o un cron, poi replicare l’archivio fuori dall’host.
AGGIORNAMENTO DI FORGEJO
L’upgrade consiste nel sostituire il binario:
|
0 |
sudo systemctl stop forgejo
|
Scaricare e verificare la nuova versione quindi:
|
0 |
sudo install -m 755 forgejo-NUOVA_VERSIONE-linux-amd64 /usr/local/bin/forgejo
|
Avviare Fogejo:
|
0
1
|
sudo systemctl start forgejo
sudo journalctl -u forgejo -f
|
Prima di ogni upgrade di major version: eseguire il dump e leggi la sezione breaking changes delle release notes. Le migrazioni del database vengono applicate automaticamente al primo avvio e non sono reversibili.
PROBLEMI FREQUENTI
502 Bad Gateway: servizio non attivo o HTTP_ADDR errato systemctl status forgejo – Verificare che la porta 3000 sia in ascolto con ss -ltnp
Push oltre pochi MB rifiutato: limite di Nginx – Aumentare client_max_body_size
Clone SSH chiede la password: chiave non registrata o permessi errati su /home/git/.ssh – Correggere i permessi e controllare authorized_keys
Link generati in http://localhost:3000: ROOT_URL non corretto – Correggere [server] ROOT_URL e riavviare
Errori di collation dopo upgrade PostgreSQL: database creato senza template0 – REINDEX DATABASE forgejo;
Actions non partono: nessun Runner registrato – installare Forgejo Runner e registralo dalla UI (dalla 15.0 la registrazione è guidata via web)
PRO E CONTRO
Di seguito i PRO:
Governance e licenza. È il differenziale vero. Forgejo nasce nell’ottobre 2022 quando domini e marchio Gitea passarono a una società for-profit senza il consenso della community; il progetto vive oggi sotto l’ombrello di Codeberg e.V., un’associazione non-profit tedesca.
Dalla versione 9 è rilasciato sotto licenza copyleft GPL, quindi nessun rischio di edizioni “enterprise” chiuse o di funzionalità tenute dietro un paywall.
Leggerezza. Binario statico singolo in Go, gira tranquillamente in ~512 MB di RAM — abissale la differenza con GitLab CE, che vuole 4 GB minimi (8 per stare comodi) più Postgres, Redis, Gitaly e i worker Sidekiq.
Su un LXC o una VM piccola del tuo homelab è un altro pianeta.
Feature set completo per il 90% dei casi. Repo, pull request, issue, wiki, LFS, registry pacchetti (Docker, npm, PyPI, Cargo, Debian, Go) e CI compatibile con la sintassi GitHub Actions, tutto incluso.
Autoconsistenza del progetto. Forgejo è sviluppato usando Forgejo stesso, testato e rilasciato con Forgejo Actions; Gitea è sviluppato su GitHub e rilasciato con GitHub Actions.
Codeberg fa da banco di prova su scala reale per ogni release prima che arrivi agli altri self-hoster.
Migrazione facile in entrata. L’importer da GitHub/GitLab funziona bene e copre issue, PR, label e milestone, non solo il codice.
Di seguito i CONTRO:
Ecosistema di terze parti più povero. Un decennio di tutorial, provider Terraform, script di backup e guide di integrazione parla di Gitea: quando cerchi soluzioni finisci spesso su documentazione Gitea da adattare. In genere funziona, ma è attrito.
Nessun vendor a cui rivolgersi. Non esiste un contratto di supporto commerciale. Per un’azienda che vuole un’alternativa leggera a GitHub con un fornitore da chiamare, Gitea è la risposta più difendibile in sede di procurement e nel tuo contesto MSP questo pesa soprattutto verso clienti che chiedono un SLA sul software.
CI meno matura di GitLab. Forgejo Actions copre bene i casi standard, ma non ha l’equivalente di pipeline multi-stage complesse, DAG, environment con approvazioni, security scanning integrato o container registry con policy di retention avanzate.
Federazione ancora acerba. ActivityPub/ForgeFed è la bandiera del progetto ma va trattato come un opt-in sperimentale: non contarci per casi d’uso produttivi.
Porta a senso unico verso Gitea. Dopo l’hard fork del 2024 non sono più intercambiabili come drop-in; passare dall’uno all’altro oggi è un progetto di migrazione, non un cambio di configurazione. La direzione Forgejo → Gitea in particolare è chiusa.
Manutenzione a tuo carico. Upgrade, backup, TLS, monitoraggio: tutto tuo. È il prezzo del self-hosting rispetto a GitHub/GitLab.com, e va messo a budget in ore, non solo in euro di VPS.
0 commenti