git — Michele Agostinelli Blog

Forgejo con Docker: Git self-hosted senza fronzoli

11 luglio 2025

Da tempo utilizzo Git per gestire i miei progetti personali, sia software che di configurazione. Per anni mi sono affidato al pc di qualcunaltro (es: Gitlab o GitHub), ma la dipendenza da un servizio centralizzato, per quanto comodo, inizia a starmi stretta. Così ho cercato una soluzione più allineata alla mia filosofia: Forgejo, un fork comunitario di Gitea, leggero e facilmente self-hostabile.

Perché Forgejo

Forgejo nasce da una comunità che punta alla trasparenza e all’autonomia, senza il rischio che un progetto venga assorbito o piegato a logiche commerciali. La compatibilità con Gitea è totale, e i requisiti minimi lo rendono perfetto per VPS o server casalinghi.

Veniamo subito al dunque e facciamolo partire, cosi potremo provarlo con mano!

Setup con Docker

Ci affidiamo a Docker Compose, cosi con un solo file di configurazione abbiamo tutto il necessario.

docker-compose.yaml

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:latest
    container_name: forgejo
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - ./robots.txt:/data/gitea/public/robots.txt:ro
    expose:
      - "3000"
    networks:
      - forgejo_net

networks:
  forgejo_net:
    driver: bridge

Reverse Proxy

E' possibile usare il web server che preferiamo, come ad esempio traefik, caddy, apache o nginx, in questo articolo vedremo un esempio con quest'ultimo.

Qui una configurazione base con https (via Let's Encrypt, gestito esternamente):

/etc/nginx/sites-available/forgejo.conf

server {
    listen 80;
    server_name git.miodominio.it;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name git.miodominio.it;

    ssl_certificate /etc/letsencrypt/live/git.miodominio.it/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.miodominio.it/privkey.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}

Dopo aver creato il file, attivare con:

ln -s /etc/nginx/sites-available/forgejo.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Backup automatico

Il backup rappresenta un step fondamentale del nostro setup, conviene implementarne subito uno all'avvio del servizio, cosi non ce ne dimenticvheremo e terremo i nostri dati al sicuro. Ricordiamoci che qui salveremo il risultato di diverse ore di programmazione, studio e prove!

I nostri dati si trovano nel volume data di cui sopra, quindi sarà sufficiente salvare il docker file e la directory data. Io consiglio di usare #borg ma potete usare il softwsre che preferite, trovo particolarmente utile aggiungere questa nuova directory alle procedure di salvataggio che sicuremante avrete già per tutto il resto. (se non le avete potete anche smettere di leggere questo blog, tornate quando ne avrete implementata una).

Configurazioni iniziali

A questo punto, dopo l'installazione, non ci resta che accedere via web al nostro software e fare le prime configurazioni. È possibile creare utenti, organizzazioni, concedere permessi e creare tutti i repository che si desiderano.

Ciascun progetto può essere impostato ad accesso privatp o pubblico.

In questo modo sarà semplicissimo collaborare in più persone allo stesso progetto, tenendo traccia delle varie modifiche.

Infine è anche possibile importare direttamente altri repository git.

Runner e Action

Forgejo, essendo un fork di Gitea, supporta un sistema di CI/CD integrato chiamato Actions, simile a GitHub Actions, e permette di eseguire job di build o deploy tramite runner personalizzati.

Io stesso ne faccio uso, è uno dei motivi per cui mi sto trovando benissimo con forgejo! Ho varie configurazione a seconda del progetto ospitato, ma essenzialmente queste si occupano di effettuare il “deploy” del codice, cioé copiano a destinazione (server di sviluppo o di produzione a seconda dei casi), il codice modificato, cosi che sia pronto all'uso. In questo modo, grazie alla history di git, sarà sempre possibile tornare indietro, nonché tenere traccia delle modifiche nel tempo.

Come funziona

Le Actions sono definite da file YAML nei repository (.forgejo/workflows/), e possono contenere job con step eseguiti su runner registrati.

I runner sono agent installati su macchine (stessa VPS o remote), che si collegano al server Forgejo e attendono job da eseguire.

Una volta definita la condizione scatenante (es: commit su ramo main, rilascio di una nuova versione, ecc) partirà il worksflow che abbiamo definito, con la possibilità di verificarne lo stato di esecuzione in tempo reale. Infine è anche possibile andare a vedere i log delle esecuzione precedenti.

All'interno di una action si possono usare #secret e #variabili, in modo da poter riusare il codice della action e allo stesso tempo mantenere al sicuro le credenziali.

Setup runner base

Vediamo come creare un nuovo runner, passo passo:

export RUNNER_VERSION=$(curl -X 'GET' https://data.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | jq .name -r | cut -c 2-)
wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64
chmod +x forgejo-runner
sudo mv forgejo-runner /usr/local/bin/forgejo-runner
sudo useradd -m -s /bin/bash forgejo-runner
sudo usermod -aG docker forgejo-runner

Rechiamoci sull'interfaccia web di Forgejo: Forgejo > Repository > Settings > Actions > Runners > “Generate new token”

sudo -i -u forgejo-runner
forgejo-runner register

Avvio automatico del runner

Io ho usato uno script systemd per l'avvio automatico, ve lo riporto di seguito

sudo echo "
[Unit]
Description=Forgejo Act Runner
After=network.target docker.service
Requires=docker.service

[Service]
User=forgejo-runner
Group=forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
WorkingDirectory=/home/forgejo-runner

[Install]
WantedBy=multi-user.target" > /etc/systemd/system/forgejo-runner.service

sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner
systemctl status forgejo-runner

Vantaggi in breve

Repository del proprio codice, diviso come si preferisce: singoli progetti, organizzazioni, ecc.
Possibilità di creare utenti per collaboratori/amici con controllo sugli accessi/permessi.
Automatizzo test, build, deploy senza dipendere da servizi esterni.
Nessuna dipendenza da fornitori terzi e nessun limite di spazio, esecuzioni, personalizzazioni.
Versionamento del codice, e nel caso di ci/cd garanzia di riproducibilità
Pocchissime risorse necessarie lato server
Vuoi mettere quanto è figo avere il proprio servizio di versionamento?

Uso quotidiano

Forgejo supporta #git via #ssh, Web UI e #webhooks. Ho configurato alcuni repository con CI locale usando le Actions e i runner integrati. L’interfaccia è leggera e pulita, senza funzionalità inutili.

Conclusioni

Forgejo è una soluzione Git solida, coerente con un approccio decentralizzato. Semplice da gestire, veloce da installare, e adatta anche per chi – come me – preferisce sapere dove stanno i propri dati. Per ora lo utilizzo solo per progetti personali, ma potrei iniziare a usarlo anche per collaborazioni future.

Non vi resta che provarlo, fatemi sapere le vostre impressioni con un commento nel #fediverso su questo articolo.

#git #forgejo #action #code #programmi #cicd #gitea #runner #selfhosting #selfhost #nocloud

Seguimi su mastodon: @magostinelli@mastodon.uno

Articolo pubblicato con licenza CC BY-NC-SA