Configurare una pipeline CI/CD self-hosted non deve necessariamente passare per GitHub Actions o per un servizio cloud a pagamento.

Woodpecker CI è un motore di continuous integration open source, leggero e pensato per chi vuole mantenere il pieno controllo dei propri workflow di build e test direttamente sul proprio server, senza vincolarsi a un provider esterno.

In questa guida vedremo come installare e configurare Woodpecker CI da zero su una macchina con Ubuntu 26.04 LTS (“Resolute Raccoon”), usando Docker Compose per orchestrare server e agent.

Affiancheremo a Woodpecker un’istanza locale di Gitea, così da ottenere un ambiente di test completamente self-hosted, senza dover dipendere da GitHub o da altri forge esterni.

Passo dopo passo partiremo dall’installazione di Docker Engine, passeremo per la creazione dell’applicazione OAuth che permette a Woodpecker di autenticarsi su Gitea, fino ad arrivare alla prima pipeline di test eseguita con successo.

Lungo il percorso affronteremo anche alcuni degli inciampi più comuni in un setup di questo tipo permessi errati sui volumi Docker, file YAML danneggiati da un editor poco accorto, Client ID OAuth non corrispondenti perché conoscerli in anticipo fa risparmiare parecchio tempo di debug.

PREREQUISITI

• Serve un server (fisico, VPS o VM) con Ubuntu 26.04 LTS, accesso sudo.
• Un nome di dominio puntato al server è raccomandato per usare HTTPS, ma non obbligatorio per una prova locale.

AGGIORNAMENTO DEL SISTEMA E INSTALLAZIONE DI DOCKER

Il pacchetto docker-compose-plugin non si trova nei repository standard di Ubuntu insieme a docker.io: arriva solo dal repository ufficiale di Docker, che va aggiunto a parte. Installare quindi Docker Engine direttamente da lì (è anche il metodo raccomandato da Docker stesso, più aggiornato del docker.io di Ubuntu):

sudo apt update && sudo apt upgrade -y

# Prerequisiti

sudo apt install -y ca-certificates curl gnupg

# Chiave GPG del repository Docker

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Aggiungi il repository Docker (usa in automatico il codename della tua Ubuntu)

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

Verificare con i seguenti comandi:

docker --version
docker compose version

GENERAZIONE DEL SECRET CONDIVISO TRA SERVER E AGENT WOODPECKER

Eseguire il comando:

openssl rand -hex 32

Annotarsi il Secret:

607582cba2b3d4e2a89da7ad8b806e117f1a12fbe44f676ffe2c32372aed21c

Copiare il valore: lo utilizzeremo per WOODPECKER_AGENT_SECRET

CREAZIONE DELLA STRUTTURA DEL PROGETTO E IL FILE DOCKER COMPOSE

Creare la struttura del progetto e il file docker-compose con i comandi:

sudo mkdir -p /opt/woodpecker/gitea-data /opt/woodpecker/data
cd /opt/woodpecker

Creare il file docker-compose.yml con il comando:

sudo tee docker-compose.yml > /dev/null << 'EOF'
services:
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
- GITEA__server__ROOT_URL=http://SERVER_IP:3000/
- GITEA__server__HTTP_PORT=3000
- GITEA__webhook__ALLOWED_HOST_LIST=*
volumes:
- ./gitea-data:/data
ports:
- "3000:3000"
- "2222:22"

woodpecker-server:
image: woodpeckerci/woodpecker-server:v3
container_name: woodpecker-server
restart: unless-stopped
depends_on:
- gitea
ports:
- "8000:8000"
- "9000:9000"
volumes:
- ./data:/var/lib/woodpecker/
environment:
- WOODPECKER_HOST=http://SERVER_IP:8000
- WOODPECKER_AGENT_SECRET=IL_SECRET_GENERATO
- WOODPECKER_GITEA=true
- WOODPECKER_GITEA_URL=http://SERVER_IP:3000
- WOODPECKER_GITEA_CLIENT=DA_COMPILARE
- WOODPECKER_GITEA_SECRET=DA_COMPILARE
- WOODPECKER_ADMIN=DA_COMPILARE

woodpecker-agent:
image: woodpeckerci/woodpecker-agent:v3
container_name: woodpecker-agent
command: agent
restart: unless-stopped
depends_on:
- woodpecker-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_AGENT_SECRET=IL_SECRET_GENERATO
- WOODPECKER_MAX_WORKFLOWS=2
- WOODPECKER_BACKEND=docker
EOF

Salvare e chiudere il filem di configurazione

ATTENZIONE: sostituire SERVER_IP e IL_SECRET_GENERATO con i tuoi valori; i campi WOODPECKER_GITEA_CLIENT/SECRET e WOODPECKER_ADMIN li completeremo dopo aver creato l’app OAuth in Gitea

AVVIO DI GITEA E CREAZIONE DELL’UTENTE AMMINISTRATORE

Per ora avviare solo Gitea con il comando:

sudo docker compose up -d gitea

Dovremmo visualizzare un putput simile al seguente:

[+] up 9/9
 Image gitea/gitea:latest Pulled 4.5s
 Network woodpecker_default Created 0.0s
 Container gitea Started

Aprire il browser su http://SERVER_IP:3000 comparirà la procedura guidata di installazione.

Lasciare tutti i valori predefiniti (usare SQLite, va benissimo per un uso locale/di test)

Nella sezione Impostazioni account amministratore creare il tuo utente admin (username, email, password).

Quindi cliccare Installare Gitea

Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di Gitea

CREAZIONE DELL’APPLICAZIONE OAUTH IN GITEA PER WOODPECKER

Creare l’applicazione OAuth in Gitea per Woodpecker

Da amministratore andaree su http://SERVER_IP:3000/admin/settings/applications (oppure Impostazioni utente → Applicazioni se preferisci un’app a livello utente) e crea una nuova applicazione OAuth2:

Inserire le seguenti informazioni:

Nome applicazione: Woodpecker CI

Redirect URL: http://SERVER_IP:8000/authorize

Cliccare Crea Applicazione

Copiare le seguenti info:

Client ID: 3cf08282-49ff-46d4-9707-7bf6174ed82d

Client Secret: gto_66j26rf2li7vzqlkwdykedqpbt73ggnhpru4bz7rwjwebvisuyaa

Salva e copia il Client ID e il Client Secret mostrati (ATTENZIONE: il secret viene mostrato una sola volta).

Completa le tre variabili lasciate in sospeso nel file docker-compose.yml con sed:

cd /opt/woodpecker
sed -i 's/WOODPECKER_GITEA_CLIENT=DA_COMPILARE/WOODPECKER_GITEA_CLIENT=il-client-id-copiato/' docker-compose.yml
sed -i 's/WOODPECKER_GITEA_SECRET=DA_COMPILARE/WOODPECKER_GITEA_SECRET=il-client-secret-copiato/' docker-compose.yml
sed -i 's/WOODPECKER_ADMIN=DA_COMPILARE/WOODPECKER_ADMIN=il-tuo-username-gitea/' docker-compose.yml

Sostituire il-client-id-copiato, il-client-secret-copiato e il-tuo-username-gitea con i valori reali prima di eseguire i comandi.

AVVIO DI WOODPECKER (SERVER + AGENT)

Avviare Woodpecker con i seguenti comandi:

Posizionarsi nella cartella woodpcker con il comando:

cd /opt/woodpecker

Avviare Docker con il comando:

sudo docker compose up -d

Dovremmo visualizzare un output simile al seguente:

[+] up 13/14
 Image woodpeckerci/woodpecker-agent:v3 Pulled 3.6s
 Image woodpeckerci/woodpecker-server:v3 Pulled 4.0s
 Container gitea Started 1.0s
 Container woodpecker-server Started 0.4s
 Container woodpecker-agent Started

Fare la verifica con il comando:

sudo docker compose ps

Verificare i Log con il comando:

sudo docker compose logs -f woodpecker-server

ATTENZIONE: premere Ctrl+C per uscire dai log senza fermare i container.

PRIMO ACCESSO A WOODPECKER

Aprire da un qualsiasi browser il link http://SERVER_IP:8000

Cliccare Login e autorizzare l’accesso tramite il tuo account Gitea. Essendo l’utente indicato in WOODPECKER_ADMIN, sarai automaticamente amministratore di Woodpecker.

Se non dovesse mostrare la pagina di Login eseguire i comandi elencati di seguito:

cd /opt/woodpecker
sudo docker compose down

# assegna la cartella dati all'utente 1000 usato dal processo woodpecker-server nel container
sudo chown -R 1000:1000 /opt/woodpecker/data

sudo docker compose up -d

sudo docker compose logs -f woodpecker-server

Cliccare su Accedi a Woodpecker

Cliccare Autorizza Applicazione

Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di Woodpecker come mostrato nell’ìimmagine sovrastante

CREAZIONE DI UN REPOSITORY DI TEST E COLLEGAMENTO ALLA PIPELINE

In Gitea (http://SERVER_IP:3000) creare un nuovo repository (es. test-ci) quindi clonarlo e aggiungere un file .woodpecker.yml.

Da browser: andare su http://192.168.80.34:3000 quindi fare login come admin cliccare sul + in alto a destra → Nuovo repository.

Nome: test-ci.

Spuntare Inizializza repository (così non è vuoto) e cliccare Crea Repository

Se è tutto OK dovremmo vedere una schermata come quella sovrastante

A questo punto da terminale eseguire i comandi elencati di seguito:

git clone http://192.168.80.34:3000/admin/test-ci.git

Dovremmo visualizzare il seguente output:

Cloning into 'test-ci'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (3/3), done.

Quindi eseguire il comando:

cd test-ci

Creare il file YML con il comando:

cat > .woodpecker.yml << 'EOF'
steps:
- name: hello
image: alpine
commands:
- echo "Ciao da Woodpecker!"
EOF

Quindi eseguire i comandi:

git add .woodpecker.yml

git commit -m "Aggiunge pipeline di test"

git push

Collegarsi alla Dashboard di Woodpecker (http://SERVER_IP:8000)

Dalla dashboard di Woodpecker attivare il repository dalla lista cliccando su Aggiungi Repository

Cliccare Abilita

Cliccare Esegui Pipeline

COMANDI UTILI PER LA MANUTENZIONE

Di seguito una lista dei comandi utili per la manutenzione di Woodpecker

cd /opt/woodpecker

# Aggiornare tutte le immagini

sudo docker compose pull
sudo docker compose up -d

# Log dei singoli servizi

sudo docker compose logs -f gitea
sudo docker compose logs -f woodpecker-agent

# Fermare tutto

sudo docker compose down

PRO E CONTRO DI WOODPECKER CI

Prima di lanciarsi nell’installazione vale la pena capire dove Woodpecker CI si posiziona rispetto alle alternative più note come Jenkins, GitHub Actions o GitLab CI.

PRO

• Completamente self-hosted e open source (licenza AGPL v3): tutti i dati e le pipeline restano sulla propria infrastruttura, senza vendor lock-in e senza costi per utente o per minuto di build.
• Architettura leggera e container-first: ogni step è semplicemente “un’immagine Docker + un comando”, il che lo rende facile da capire, da eseguire anche su hardware modesto e da far girare in container/Kubernetes con buon isolamento.
• Supporto nativo a più forge: Gitea, Forgejo, GitHub, GitLab e Bitbucket, con integrazione OAuth2 e registrazione automatica dei webhook (come visto nella nostra configurazione con Gitea).
• Funzionalità pratiche integrate: pipeline multiple nella cartella .woodpecker/, cron job nativi senza bisogno di trigger esterni, supporto ad architetture ARM.
• Sviluppo attivo: nato come fork di Drone dopo il passaggio di quest’ultimo a una licenza BSL, riceve release e correzioni più frequenti rispetto al progetto originale.
• Sintassi delle pipeline quasi identica a Drone, il che rende la migrazione da Drone particolarmente semplice.

CONTRO

• Ecosistema di plugin più piccolo rispetto a GitHub Actions o GitLab CI: non esiste un marketplace ricco di integrazioni pronte all’uso, quindi spesso serve costruirsi il proprio step Docker.
• Nessuna offerta gestita (SaaS): a differenza di GitHub Actions o GitLab CI, non c’è un servizio cloud “pronto all’uso” — tutta la gestione operativa (aggiornamenti, backup, sicurezza) resta a carico di chi lo installa, come stiamo facendo in questa guida.
• Supporto solo community-driven: nessuna azienda dietro con SLA garantiti, a differenza per esempio di Drone (partnership con Harness). Documentazione e canali di supporto (Matrix, GitHub Issues) sono più piccoli rispetto a quelli di progetti più maturi.
• Gestione dei secret piuttosto basilare: manca il rotation automatico o l’integrazione nativa con strumenti come HashiCorp Vault, e i controlli di accesso sono granulari solo a livello di repository.
• Progetto relativamente giovane: essendo un fork di Drone, ha una storia più breve e una community più piccola rispetto a Jenkins o alle piattaforme CI dei grandi provider.

Per un uso personale, un piccolo team o un homelab proprio il caso della nostra installazione locale con Gitea questi limiti pesano poco a fronte dei vantaggi in termini di semplicità, controllo e costi.

Diventano invece un fattore da valutare con più attenzione in contesti enterprise con requisiti stringenti di compliance, supporto SLA o gestione avanzata dei segreti.

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/AAAA che punta al server, ad esempio git.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:

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:

git --version

Dovremmo visualizzare un output simile al seguente:

git version 2.53.0

INSTALLAZIONE DATABASE POSTGRESQL

SQLite funziona ed è comodo per test, ma per un’istanza destinata a durare consiglio PostgreSQL.

sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql

Creare utente e database con i comandi:

sudo -u postgres psql

Quindi eseguire i comandi SQL:

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:

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:

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 DI SISTEMA E STRUTTURA DELLE DIRECTORY

Forgejo non va mai eseguito come root. Creare un utente di servizio git con il comando:

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:

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):

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:

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:

sha256sum -c "forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}.sha256"

Dovremmo visualizzare un output simile al seguente:

forgejo-16.0.1-linux-amd64: OK

Verificare la firma GPG (chiave di release Forgejo) con il comando:

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:

gpg: directory '/root/.gnupg' created
gpg: keybox '/root/.gnupg/pubring.kbx' created
gpg: /root/.gnupg/trustdb.gpg: trustdb created
gpg: key A4B61A2DC5923710: public key "Forgejo <contact@forgejo.org>" imported
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: Good signature from "Forgejo <contact@forgejo.org>" [unknown]
gpg: aka "Forgejo Releases <release@forgejo.org>" [unknown]
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:

sudo install -m 755 "forgejo-${FORGEJO_VERSION}-${FORGEJO_ARCH}" /usr/local/bin/forgejo

fare il check con il comando:

forgejo --version

Dovremmo visualizzare un output simile al seguente:

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:

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:

sudo systemctl daemon-reload
sudo systemctl enable --now forgejo
sudo systemctl status forgejo --no-pager

Se è tutto OK dovremmo visualizzare il seguente output:

● 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:

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:

sudo apt install -y nginx

Configurazione del vhost:

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:

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:

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:

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:

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:

[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:

[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:

sudo systemctl restart forgejo

VERIFICA FUNZIONALE

Creare un repository di test dalla UI, poi da una macchina client:

# 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:

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:

sudo systemctl stop forgejo

Scaricare e verificare la nuova versione quindi:

sudo install -m 755 forgejo-NUOVA_VERSIONE-linux-amd64 /usr/local/bin/forgejo

Avviare Fogejo:

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.

Nel panorama degli strumenti di monitoraggio self-hosted Gatus si sta ritagliando uno spazio sempre più importante grazie alla sua filosofia semplice ma efficace: un dashboard di health check “developer-oriented”, pensato per chi vuole sapere in tempo reale se i propri servizi siti web, API, database, dispositivi di rete sono realmente raggiungibili e funzionanti, senza dover configurare uno stack di monitoring complesso.

A differenza di soluzioni basate puramente su metriche di traffico, Gatus esegue controlli attivi e programmati verso gli endpoint configurati, permettendo di intercettare un’interruzione di servizio anche quando nessun utente sta effettivamente generando richieste in quel momento.

Il tutto restituito attraverso una status page pulita, leggera e completamente personalizzabile via file YAML.

In questa guida vedremo passo passo come installare Gatus su Ubuntu Server 26.04, utilizzando Docker Compose come metodo di deployment: partiremo dall’installazione di Docker Engine da zero, per poi arrivare a una configurazione base funzionante, con endpoint di esempio, storage persistente su SQLite e alcune indicazioni per l’esposizione sicura tramite reverse proxy.

Un punto di partenza solido per chi vuole integrare un sistema di status monitoring leggero nel proprio homelab o nella propria infrastruttura di produzione.

PREREQUISITI

• Un server Ubuntu 26.04 con accesso sudo
• Docker Engine (versione 19.03 o superiore, API 1.40+) e il plugin Docker Compose
• Un container già in esecuzione, giusto per avere qualche log da guardare

AGGIORNAMENTO DEL SISTEMA

Aggiornare il sistema con i seguenti comandi:

sudo apt update && sudo apt upgrade -y

sudo apt install -y ca-certificates curl gnupg

INSTALLAZIONE DI DOCKER ENGINE + DOCKER COMPOSE PLUGIN

Creare la directory per le chiavi GPG con il comando:

sudo install -m 0755 -d /etc/apt/keyrings

Aggiungere la chiave GPG ufficiale di Docker con i comandi:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

Aggiungere il repository Docker con il comando:

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Aggiornare e installare Docker + Compose plugin con i comandi:

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

NOTA BENE: Ubuntu 26.04 è recentissima se il repository Docker non ha ancora una entry specifica per il suo codename, il comando sopra userà comunque il nome codename rilevato da os-release. Se apt update desse errore per il repo, verifica su https://download.docker.com/linux/ubuntu/dists/ quale codename è disponibile e sostituiscilo manualmente.

VERIFICARE L’INSTALLAZIONE DI DOCKER

Verificare l’installazione di Docker con i seguenti comandi:

sudo docker --version

sudo docker compose version

sudo systemctl status docker

Dovremmo visualizzare il seguente output:

● docker.service - Docker Application Container Engine
Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
Active: active (running) since Sun 2026-07-12 19:56:12 UTC; 1min 18s ago
Invocation: cc37e30724f641f694ef48dfdbb5fec7
TriggeredBy: ● docker.socket
Docs: https://docs.docker.com
Main PID: 30242 (dockerd)
Tasks: 10
Memory: 27.8M (peak: 28.1M)
CPU: 316ms
CGroup: /system.slice/docker.service
└─30242 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.022827820Z" level=info msg="Restoring containers: start."
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.051534074Z" level=info msg="Deleting nftables IPv4 rules" error="running nft: /dev/stdin:1:17-30: >
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.058935552Z" level=info msg="Deleting nftables IPv6 rules" error="running nft: /dev/stdin:1:18-31: >
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.275806869Z" level=info msg="Loading containers: done."
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.283474191Z" level=info msg="Docker daemon" commit=8ec5ab3 containerd-snapshotter=true storage-driv>
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.283562293Z" level=info msg="Initializing buildkit"
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.384444825Z" level=info msg="Completed buildkit initialization"
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.390776109Z" level=info msg="Daemon has completed initialization"
Jul 12 19:56:12 vm-srv-test dockerd[30242]: time="2026-07-12T19:56:12.390817886Z" level=info msg="API listen on /run/docker.sock"
Jul 12 19:56:12 vm-srv-test systemd[1]: Started docker.service - Docker Application Container Engine.

UTILIZZO DI DOCKER SENZA SUDO (OPZIONALE MA CONSIGLIATO)

Per utilizzare Docker senza sudo eseguire i comandi di seguito:

sudo usermod -aG docker $USER

newgrp docker

Poi verificare con il seguente comando:

docker run hello-world

CREAZIONE DELLA STRUTTURA DI CARTELLE PER GATUS

Creare la struttura delle cartelle per Gatus con i seguenti comandi:

mkdir -p ~/gatus/config ~/gatus/data

cd ~/gatus

CREAZIONE DEL FILE DOCKER-COMPOSE.YML

Creare il file docker-compose.yml con il comando:

sudo nano docker-compose.yml

Quindi incollare all’interno il seguente output:

services:
gatus:
image: ghcr.io/twin/gatus:stable
container_name: gatus
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./config/config.yaml:/config/config.yaml:ro
- ./data:/data
environment:
- GATUS_CONFIG_PATH=/config/config.yaml

Salvare e chiudere il file di configurazione.

CREAZIONE DEL FILE DI CONFIGURAZIONE CONFIG/CONFIG.YAML

Creare il file di configurazione config/config.yaml con il comando:

sudo nano config/config.yaml

Quindi incollare all’interno il seguente output:

storage:
type: sqlite
path: /data/data.db

web:
port: 8080

endpoints:
- name: Google
url: "https://google.com"
interval: 60s
conditions:
- "[STATUS] == 200"
- "[RESPONSE_TIME] < 1000"

- name: Sito di esempio
url: "https://tuo-dominio-esempio.it"
interval: 60s
conditions:
- "[STATUS] == 200"

Salvare e chiudere il file di configurazione.

Sostituire gli endpoint con i servizi reali da monitorare (siti, API, ESXi, vCenter, Portainer, ecc.).

AVVIO DEL CONTAINER

Avviare il Docker con il comando:

docker compose up -d

Dovremmo visualizzare il seguente output:

[+] up 7/7
 Image ghcr.io/twin/gatus:stable Pulled 4.1s
 Network gatus_default Created 0.0s
 Container gatus Started

Verificare i log con il comando:

docker compose logs -f gatus

Dovremmo visualizzare il seguente output:

gatus | 2026/07/12 20:03:50 [main.configureLogging] Log Level is set to INFO
gatus | 2026/07/12 20:03:50 [config.LoadConfiguration] Reading configuration from configFile=/config/config.yaml
gatus | 2026/07/12 20:03:50 [config.ValidateAlertingConfig] Alerting is not configured
gatus | 2026/07/12 20:03:50 [config.ValidateEndpointsConfig] Validated 2 endpoints
gatus | 2026/07/12 20:03:50 [config.ValidateEndpointsConfig] Validated 0 external endpoints
gatus | 2026/07/12 20:03:50 [config.ValidateSuitesConfig] No suites configured
gatus | 2026/07/12 20:03:50 [main.initializeStorage] Total endpoint keys to preserve: 2
gatus | 2026/07/12 20:03:50 [controller.Handle] Listening on 0.0.0.0:8080
gatus |
gatus | ┌───────────────────────────────────────────────────┐
gatus | │ Fiber v2.52.13 │
gatus | │ http://[::]:8080 │
gatus | │ │
gatus | │ Handlers ............ 41 Processes ........... 1 │
gatus | │ Prefork ....... Disabled PID ................. 1 │
gatus | └───────────────────────────────────────────────────┘
gatus |
gatus | 2026/07/12 20:03:51 [watchdog.executeEndpoint] Monitored group=; endpoint=Google; key=_google; success=true; errors=0; duration=194ms
gatus | 2026/07/12 20:03:51 [api.ErrorHandler] Cannot GET /api/events/stream
gatus | 2026/07/12 20:03:52 [watchdog.executeEndpoint] Monitored group=; endpoint=Sito di esempio; key=_sito-di-esempio; success=true; errors=0; duration=1.07s

ACCESSO ALLA DASHBOARD DI GATUS

Per accedere alla Dashboard di Gatus da un qualsiasi browser richiamare il link:

http://<IP-del-server>:8080

Dovremmo visualizzare la Dashboard di Gatus con i due Host monitorati

ABILITARE L’AUTENTICAZIONE BASE (OPZIONALE)

Per abilitare l’autenticazione su Gatus eseguire il comando:

sudo apt install -y apache2-utils
htpasswd -bnBC 10 '' TuaPasswordSicura | tr -d ':\n' | base64

Nel file config.yaml aggiungere le seguenti righe:

security:
basic:
username: admin
password-bcrypt-base64: "INCOLLA_QUI_L'HASH"

Salvare e chiudere il file di configurazione

Riavviare Docker con il comando:

docker compose up -d

Fare un refresh della pagina web e se è tutto corretto dovrebbe chiedere la credenziali di accesso.

ABILITARE L’ALERT VIA EMAIL (OPZIONALE)

Per abilitare gli alert via mail inserire all’interno del file config.yaml le seguenti righe:

alerting:
email:
from: "gatus@mypsx.net"
to: "tuamail@example.com"
smtp:
host: smtp.example.com
port: 587
username: user
password: pass

Salvare e chiudere il file di configurazione.

MANUTENZIONE

Per aggiornare Gatus alla nuova versione eseguire i comandi:

cd ~/gatus

docker compose pull

docker compose up -d

Per controllare la dimensione del database SQLite eseguire il comando:

du -sh ~/gatus/data/

FUNZIONALITA’ DI GATUS CON PRO E CONTRO

Ecco l’elenco completo delle funzionalità di Gatus, con pro e contro per ciascuna area.

Tipi di health check

Funzionalità: monitoraggio via HTTP, TCP, ICMP (ping), DNS, STARTTLS/TLS, e persino query GraphQL Gatus è una dashboard di health monitoring orientata agli sviluppatori che permette di monitorare i servizi tramite query HTTP, ICMP, TCP e DNS. TwiN

Pro: copre praticamente ogni tipo di servizio (web app, database, DNS interni, certificati, dispositivi di rete raggiungibili solo via ping).

Pro: supporta anche richieste GraphQL con verifica del body, utile per API moderne.

Contro: nessun check “agent-based” (a differenza di Zabbix/Prometheus node_exporter) non misura CPU/RAM/disco dell’host, solo raggiungibilità/risposta del servizio.

Condizioni di valutazione (conditions)

Funzionalità: condizioni flessibili su status code, tempo di risposta, contenuto del body (JSON path), scadenza certificati, IP Gatus valuta il risultato delle query usando una lista di condizioni su valori come il codice di stato, il tempo di risposta, la scadenza del certificato e il body. TwiN

Pro: molto più granulare di un semplice “è su/giù” puoi verificare che l’API risponda con dati corretti, non solo con HTTP 200.

Pro: utilizzabile anche come test di accettazione automatizzati (UAT), non solo monitoring.

Contro: la sintassi delle condizioni (JSON path custom, placeholder [STATUS], [BODY], ecc.) richiede una curva di apprendimento iniziale, specialmente per condizioni complesse su body annidati.

Contro: l’operatore pat() (pattern matching) è molto più oneroso computazionalmente di un confronto diretto, quindi va usato con parsimonia.

Alerting multi-canale

Funzionalità: integrazioni native con Slack, Discord, Teams, PagerDuty, Twilio, Telegram, Email, Mattermost, Google Chat, Opsgenie, Gotify, ntfy, HomeAssistant, GitHub, GitLab, iLert e provider custom via webhook.

Pro: copertura estremamente ampia “out of the box”, incluse integrazioni home-lab friendly come ntfy e HomeAssistant.

Pro: soglie configurabili per failure/success (es. avvisa solo dopo 3 fallimenti consecutivi, chiudi l’alert dopo 2 successi).

Pro: provider custom per casi non coperti (es. rollback automatici, webhook interni).

Contro: ogni provider ha una sintassi di configurazione leggermente diversa nello YAML, quindi bisogna consultare la doc per ciascuno.

Contro: non tutti i provider gestiscono l’auto-risoluzione (send-on-resolved) allo stesso modo  per alcuni (es. PagerDuty, iLert) è fortemente raccomandato abilitarla per evitare incident “fantasma” aperti.

Storage dei dati storici

Funzionalità: storage in memoria, SQLite (default consigliato) o PostgreSQL Gatus supporta anche uno storage PostgreSQL configurabile tramite stringa di connessione. Libre Self-hosted

Pro: SQLite è zero-config e perfetto per homelab/singola istanza.

Pro: PostgreSQL disponibile per scenari multi-istanza o retention più lunga.

Contro: lo storage in memoria (default se non configurato) perde tutto lo storico ad ogni riavvio del container.

Contro: nessun supporto nativo per storage a lungo termine tipo time-series DB (InfluxDB/Prometheus) se ti servono dashboard analitiche avanzate, va integrato esternamente.

Dashboard e status page

Funzionalità: dashboard web con dark mode, badge di stato (anche integrabili in README GitHub), raggruppamento endpoint per categoria.

Pro: interfaccia pulita, leggera, pensata per essere pubblica (status page stile StatusPage.io).

Pro: badge integrabili ovunque (utile per un post sul blog o repo Gitea).

Contro: la personalizzazione grafica è limitata rispetto a soluzioni più “enterprise” (Uptime Kuma ha temi più ricchi, Kener è pensato apposta per status page brandizzate).

Sicurezza e accesso

Funzionalità: autenticazione basic (bcrypt), OIDC (in alpha).

Pro: protezione semplice via basic auth per dashboard esposte pubblicamente.

Contro: OIDC è ancora in stato alpha — non affidarti ad esso per ambienti di produzione critici, specialmente se hai già SSO aziendale da integrare stabilmente.

Contro: nessun sistema di ruoli/permessi granulare (RBAC) è tutto o niente sull’accesso alla dashboard.

Metriche e osservabilità

Funzionalità: endpoint /metrics in formato Prometheus.

Pro: si integra facilmente col tuo stack Grafana/Prometheus esistente.

Pro: basso consumo di risorse, tipico delle applicazioni Go il consumo di risorse richiesto è trascurabile, come tipico delle applicazioni Go.

Deployment e automazione

Funzionalità: Docker, Helm Chart per Kubernetes, Terraform provider, auto-discovery Kubernetes (alpha), istanze remote (sperimentale).

Pro: ottimo fit sia per homelab Docker/Portainer sia per cluster K8s più strutturati.

Pro: configurazione dichiarativa in YAML → si presta benissimo a GitOps (perfetto per il tuo workflow con Gitea).

Contro: auto-discovery K8s e istanze remote sono ancora sperimentali/alpha non stabili al 100% per produzione.

Filosofia generale: monitoraggio “esterno” vs metriche interne

Funzionalità: check attivi e sintetici, non dipendenti dal traffico reale a differenza delle metriche che dipendono dal traffico esistente, Gatus ti avvisa anche se nessun cliente sta attivamente chiamando l’endpoint in quel momento. Openaitx

Pro: rileva problemi anche prima che gli utenti reali li notino (es. load balancer giù senza traffico).

Contro: essendo check sintetici a intervalli, non sostituisce un vero APM (Application Performance Monitoring) per diagnosticare cause profonde di degradazione è complementare, non alternativo, a strumenti come Prometheus/Grafana per metriche interne.

Dozzle è un log viewer per container Docker leggero e in tempo reale pensato per essere l’alternativa pratica al classico docker logs -f lanciato a mano su ogni container.

È stateless (non salva nulla su disco), pesa pochi MB e si installa con un solo comando Docker.

Nelle versioni più recenti supporta anche query SQL sui log tramite DuckDB in-browser monitoraggio multi-host con agent dedicati e notifiche verso Slack, Discord, ntfy o webhook generici.

In questa guida vedremo come installarlo su Ubuntu 26.04 con configurazione tramite Docker Compose, persistenza dei dati, autenticazione e pubblicazione dietro reverse proxy con certificato TLS.

PREREQUISITI

• Un server Ubuntu 26.04 con accesso sudo
• Docker Engine (versione 19.03 o superiore, API 1.40+) e il plugin Docker Compose
• Un container già in esecuzione, giusto per avere qualche log da guardare

INSTALLAZIONE DI DOCKER

Se Docker non è ancora installato eseguire i comandi:

sudo apt update

sudo apt install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

sudo usermod -aG docker $USER

Dopo l’ultimo comando, esci e rientra nella sessione SSH (o esegui newgrp docker) per usare Docker senza sudo.

CREAZIONE DELLA DIRECTORY DELLO STACK

Come per gli altri servizi self-hosted conviene tenere ogni stack in una cartella dedicata sotto /opt:

sudo mkdir -p /opt/stacks/dozzle

cd /opt/stacks/dozzle

CREAZIONE DEL DOCKER-COMPOSE.YML

Creare il file docker-compose.yml con il comando:

sudo nano docker-compose.yml

Contenuto minimo, con persistenza del volume /data (necessaria per non perdere le impostazioni di notifica tra un riavvio e l’altro del container):

services:
dozzle:
image: amir20/dozzle:latest
container_name: dozzle
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- dozzle_data:/data
ports:
- "8080:8080"
environment:
- DOZZLE_HOSTNAME=dozzle-srv01
# - DOZZLE_ENABLE_ACTIONS=true # abilita start/stop/restart dei container dalla UI
# - DOZZLE_ENABLE_SHELL=true # abilita l'accesso alla shell dei container dalla UI
# - DOZZLE_AUTH_PROVIDER=simple # abilita l'autenticazione (vedi Passo 5)

volumes:
dozzle_data:

NOTA BENE: il flag :ro sul mount del socket Docker perchè Dozzle ha bisogno solo di leggere lo stato dei container e i log, quindi montarlo in sola lettura è una buona pratica anche se, va detto, l’accesso al socket Docker resta comunque equivalente a un accesso root sull’host.

AVVIO DEL CONTAINER

Avviare il Container con il comando:

docker compose up -d

Dovremmo visualizzare un output simile al seguente:

[+] up 9/9
 Image amir20/dozzle:latest Pulled 3.1s
 Network dozzle_default Created 0.0s
 Volume dozzle_dozzle_data Created 0.0s
 Container dozzle Started

Fare un check con il comando:

docker ps | grep dozzle

Dovremmo visualizzare un output simile al seguente:

d7c03c6a3fb8 amir20/dozzle:latest "/dozzle" 33 seconds ago Up 31 seconds 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp dozzle

Verificare che sia raggiungibile il link con il comando:

curl -I http://localhost:8080

ACCESSO A DOZZLE DA WEBGUI

Se tutto è a posto da un qualsiasi browser richiamare il link http://IP-DEL-SERVER:8080

Se è tutto OK dovremmo visualizzare la dashboard con l’elenco dei container in esecuzione sull’host.

CONFIGURAZIONE DEL FIREWALL

Se si vuole esporre la porta solo sulla rete interna limitare la regola alla subnet invece di aprirla su 0.0.0.0 con il comando:

sudo ufw allow from 192.168.0.0/16 to any port 8080 proto tcp

Se invece si pubblica Dozzle dietro reverse proxy la porta 8080 non deve essere esposta pubblicamente: basta che sia raggiungibile dal proxy.

ABILITARE L’AUTENTICAZIONE SU DOOZLE

Di default Dozzle è senza autenticazione quindi chiunque raggiunge la porta vede i log di tutti i container.

Per qualsiasi esposizione oltre al semplice localhost va abilitata l’autenticazione con il comando:

docker run -it --rm -v dozzle_data:/data amir20/dozzle generate admin \
--password "PASSWORD_SICURA" \
--email admin@lab.prv \
--name "Admin"

Poi nel docker-compose.yml scommentare la seguente riga:

yaml environment:
- DOZZLE_AUTH_PROVIDER=simple

Quindi riavviare lo stack con il comando:

docker compose up -d

Da questo momento l’accesso alla UI richiederà la login.

MONITORAGGIO MULTI-HOST (OPZIONALE)

Se si hanno più host Docker da monitorare da un’unica dashboard Dozzle supporta un’architettura ad agent: su ogni host remoto lanci un agent leggero, e li colleghi tutti al Dozzle principale.

Su ogni host remoto eseguire i comandi:

docker run -d \
--name dozzle-agent \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-p 7007:7007 \
amir20/dozzle:latest agent

Sul Dozzle principale aggiungere nel docker-compose.yml le seguenti righe:

environment:
- DOZZLE_REMOTE_AGENT=IP_HOST_REMOTO:7007

L’agent comunica via gRPC sulla porta 7007: verificare che sia raggiungibile prima di dare per scontato che non funzioni.

FUNZIONALITA’ DI DOOZER

Ecco un quadro completo delle funzionalità di Dozzle, con pro e contro di ciascuna:

Monitoraggio log in tempo reale

Streaming live dei log di tutti i container Docker, senza bisogno di aprire terminali multipli con docker logs -f.

Pro: zero configurazione, log visibili immediatamente all’avvio

Contro: nessuna persistenza se un container va giù, vedi solo quello che rimane nel buffer del log driver Docker (limitato da max-size in daemon.json)

Ricerca e filtri sui log

Supporta ricerca regex, fuzzy search e (nelle versioni recenti) query SQL complete tramite DuckDB, eseguite via WebAssembly direttamente nel browser.

Pro: ricerca potente senza bisogno di un backend esterno o database

Contro: la ricerca SQL funziona solo sui log attualmente in buffer/visibili, non su uno storico persistente non è un sostituto di Loki o ELK per ricerche su settimane di log

Statistiche container (CPU, memoria, rete)

Grafici con storico “rolling” delle risorse per ogni container, aggiornati in tempo reale.

Pro: utile per un colpo d’occhio rapido senza aprire docker stats o Portainer

Contro: storico limitato alla sessione, non pensato per capacity planning a lungo termine

Multi-container / split view

Visualizzazione affiancata dei log di più container contemporaneamente.

Pro: comodo per debug su stack con più servizi correlati (es. app + db + reverse proxy)

Contro: con molti container aperti insieme l’interfaccia diventa affollata

Azioni sui container (start/stop/restart, shell)

Da abilitare esplicitamente con DOZZLE_ENABLE_ACTIONS e DOZZLE_ENABLE_SHELL.

Pro: gestione rapida senza uscire dal browser

Contro: disattivate di default per motivi di sicurezza — abilitarle su un’istanza esposta pubblicamente amplia parecchio la superficie di rischio, dato che chi ha accesso può eseguire comandi nei container

Notifiche/alert su pattern di log

Match su espressioni configurabili con notifica verso Slack, Discord, ntfy o webhook generico.

Pro: permette un minimo di alerting reattivo senza integrare uno stack di observability completo

Contro: nessuna gestione di stato/silenziamento evoluta come in un vero sistema di alerting (Alertmanager, ecc.)

Multi-host e Swarm/Kubernetes

Architettura ad agent per collegare più host Docker o cluster Swarm da un’unica dashboard; supporto anche per Kubernetes (DOZZLE_MODE=k8s, con RBAC per accesso ai log dei pod).

Pro: scala bene per contesti MSP con più host da monitorare centralmente

Contro: richiede di esporre/raggiungere la porta 7007 (gRPC) dell’agent su ogni host remoto, quindi va pianificato bene su reti segmentate o dietro VPN/tunnel

Autenticazione

Provider “simple” con utenti generati via CLI, oppure integrazione con reverse proxy di autenticazione tipo Authelia.

Pro: copre il caso base senza bisogno di terze parti

Contro: disattivata di default è facile dimenticarsene e lasciare un’istanza aperta su una rete condivisa; nessun supporto nativo a RBAC granulare (es. utenti che vedono solo certi container)

Impronta e leggerezza

Immagine da 7-10 MB, footprint minimo di CPU/RAM, nessun database.

Pro: ideale per homelab o affiancato ad app leggere senza overhead percepibile

Contro: proprio perché stateless, non fa retention: non è adatto a compliance/audit log a lungo termine

Accesso al socket Docker

Richiede il mount di /var/run/docker.sock (idealmente in sola lettura, :ro).

Pro: nessuna configurazione aggiuntiva per “vedere” tutti i container

Contro: l’accesso al socket Docker è di fatto equivalente a un accesso root sull’host è il principale motivo per cui va protetto dietro autenticazione/reverse proxy e mai esposto direttamente su internet

Analytics anonime

Raccoglie dati anonimi di utilizzo (Google Analytics) per orientare lo sviluppo, disattivabile col flag –no-analytics.

Pro: aiuta il progetto (open source, non finanziato) a capire dove investire

Contro: va disattivato esplicitamente se in ambienti con policy privacy stringenti (es. NIS2, clienti regolamentati)

In sintesi Dozzle è ottimo come vista live leggera e immediata, ma non sostituisce una piattaforma di log management vera e propria quando servono retention, ricerca storica, alerting strutturato o controlli di accesso granulari lì restano scelte più adatte Loki+Grafana, ELK o soluzioni a pagamento tipo Dash0.

Chi gestisce progetti in team o anche solo la propria lista di attività personali prima o poi si scontra con lo stesso dilemma: affidarsi a un servizio cloud di terze parti, con tutti i limiti in termini di privacy e controllo dei dati che questo comporta, oppure cercare un’alternativa self-hosted altrettanto semplice da usare.

Planka risponde proprio a questa esigenza: una board Kanban open source, leggera e reattiva, che riprende l’esperienza di Trello ma gira interamente sul proprio server.

In questa guida vedremo come installare e configurare Planka su Ubuntu Server 26.04 utilizzando Docker Compose, l’approccio più pulito e manutenibile per chi, come nel mio caso, gestisce già altri servizi containerizzati in homelab.

Partiremo dall’installazione di Docker, passeremo per la configurazione del container PostgreSQL necessario come backend, fino ad arrivare alla creazione dell’utente amministratore e a qualche accorgimento pratico per evitare i problemi più comuni che si possono incontrare al primo avvio, come la classica race condition tra database e applicazione.

Alla fine della guida avrete un’istanza di Planka funzionante e pronta per organizzare i vostri progetti, con le basi solide per aggiungere in un secondo momento un reverse proxy con HTTPS e altre personalizzazioni.

PREREQUISITI

• Ubuntu 26.04 con accesso sudo
• Almeno 1 GB di RAM libera
• Docker ed il plugin Compose

INSTALLAZIONE DI DOCKER

Installare Docker con i seguenti comandi:

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

sudo usermod -aG docker $USER

newgrp docker

sudo apt install docker-compose-plugin -y

Quindi verificare Docker con il comando:

docker --version

Dovremmo visualizzare un output simile al seguente:

Docker version 29.6.1, build 8900f1d

Verificare Docker Compose con il comando:

docker compose version

Dovremmo visualizzare un output simile al seguente:

Docker Compose version v5.3.1

CREAZIONE DELLE STRUTTURA DI PROGETTO

Creare la struttura di cartella con i seguenti comandi:

sudo mkdir -p /opt/planka

cd /opt/planka

CONFIGURAZIONE DEL DOCKER-COMPOSE.YML

Usare l’immagine ufficiale ghcr.io/plankanban/planka con PostgreSQL come backend.

Creare il file docker-compose.yml con il comando:

sudo nano docker-compose.yml

Quindi copiare all’interno il seguente output:

services:
planka:
image: ghcr.io/plankanban/planka:latest
container_name: planka
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
ports:
- "3000:1337"
environment:
- BASE_URL=http://TUO_IP_O_DOMINIO:3000
- DATABASE_URL=postgres://planka:CAMBIA_QUESTA_PASSWORD@postgres:5432/planka
- SECRET_KEY=CAMBIA_CON_STRINGA_CASUALE_LUNGA
- TRUST_PROXY=false
volumes:
- ./data/user-avatars:/app/public/user-avatars
- ./data/project-background-images:/app/public/project-background-images
- ./data/attachments:/app/private/attachments

postgres:
image: postgres:16-alpine
container_name: planka-db
restart: unless-stopped
environment:
- POSTGRES_USER=planka
- POSTGRES_PASSWORD=CAMBIA_QUESTA_PASSWORD
- POSTGRES_DB=planka
volumes:
- ./db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
interval: 5s
timeout: 5s
retries: 5

Salvare il file e generare una SECRET_KEY sicura con il comando:

openssl rand -hex 64

Copiare il risultato dentro il file al posto di CAMBIA_CON_STRINGA_CASUALE_LUNGA e impostare una password robusta uguale in entrambi i punti CAMBIA_QUESTA_PASSWORD.

AVVIARE IL CONTAINER

Avviare il container con i seguenti comandi:

cd /opt/planka

docker compose up -d

Dovremmo visualizzare un output simile al seguente:

[+] up 31/31
 Image postgres:16-alpine Pulled 8.9s
 Image ghcr.io/plankanban/planka:latest Pulled 10.5s
 Network planka_default Created 0.0s
 Container planka-db Started 4.7s
 Container planka Started

Verificare i log con il comando:

docker compose logs -f planka

Attendere che i log mostrino che il server è pronto, poi Ctrl+C per uscire dai log (i container restano attivi).

CREAZIONE DELL’UTENTE AMMINISTRATORE

Dalla versione 1.13 in poi Planka non crea più un admin di default automaticamente. Va creato a mano con il seguente comando:

docker compose run --rm planka npm run db:create-admin-user

Ti verranno chiesti email, password, nome e username.

In alternativa, puoi impostare le variabili DEFAULT_ADMIN_EMAIL, DEFAULT_ADMIN_PASSWORD, DEFAULT_ADMIN_USERNAME e DEFAULT_ADMIN_NAME nel compose e fare un restart in modo che l’utente viene creato al primo avvio.

ACCESSO TRAMITE WEBGUI

Da un quslaisi browser aprire il link http://TUO_IP:3000 (o l’IP del server) ed effettuare il login con le credenziali admin appena create.

Inserire le credenziali create in precedenza quindi cliccare su Accedi

Accettare l’EULA e cliccare Continua

Dovremmo accedere alla Home di Planka

Da questa schermata è possibile iniziare a creare Progetti

BACKUP DI PLANKA

Planka fornisce script dedicati per backup/restore quando si usa docker-compose utile per uno script cron periodico che salvi sia il volume db_data sia le cartelle data/.

TROUBLESHOOTING RAPIDO

Check di Errori di avvio con il seguente comando:

docker compose logs planka | grep -i error

Check Problemi di autenticazione DB con il comando:

docker compose logs postgres

Per un Riavvio pulito utilizzare i comandi:

docker compose down

docker compose up -d

FUNZIONALITA’ PRINCIPALI

Gestione progetti e board

• Board in stile Kanban con liste e card trascinabili (drag-and-drop)
• Card con checklist, sotto-attività, etichette colorate, scadenze
• Allegati file sulle card
• Aggiornamenti in tempo reale via WebSocket (se più persone lavorano insieme, vedono i cambiamenti istantaneamente)

Collaborazione

• Gestione utenti e membri per progetto/board
• Assegnazione di card a membri specifici
• Commenti sulle card
• Import da Trello (utile se stai migrando)

Amministrazione

• Autenticazione OIDC (OpenID Connect) — comodo se vuoi integrarlo con un provider SSO che magari già usi in ambito M365/Azure AD
• Personalizzazione dei termini di utilizzo per utenti finali
• API disponibili (con client Python non ufficiale, plankapy)
• Supporto Swagger/Postman per chi vuole integrarlo via API

Deployment

• Docker/Docker Compose (il metodo che abbiamo appena configurato)
• Installazione manuale su Debian/Ubuntu
• Helm chart per chi gira su Kubernetes — potenzialmente interessante visto il tuo K3S

PRO E CONTRO DI PLANKA

Pro

• Leggero e veloce: footprint di risorse minimo, gira bene anche su una VM homelab modesta
• Interfaccia pulita: nessun sovraccarico di funzionalità inutili, esperienza molto simile a Trello
• Open source e self-hosted: controllo completo dei dati, nessuna dipendenza da servizi cloud terzi
• Real-time collaboration affidabile: funziona bene senza configurazioni complesse
• Community attiva: sviluppo continuo, immagini Docker aggiornate regolarmente

Contro

• Funzionalità limitate rispetto a strumenti più completi: non ha Gantt chart, timeline, dashboard di reportistica avanzata, automazioni (tipo Trello Butler o Jira workflows)
• Nessuna gestione avanzata di permessi/ruoli granulari: i controlli di accesso sono piuttosto semplici rispetto a strumenti enterprise
• Nessuna app mobile nativa: è web-based, va bene ma manca l’esperienza mobile dedicata
• Gestione admin utente cambiata di recente: dalla versione 1.13 non c’è più creazione automatica dell’admin, richiede uno step manuale in più (come abbiamo visto)
• Meno adatto a project management “pesante”: se hai bisogno di dipendenze tra task, milestone, roadmap, conviene guardare altrove (es. Taiga, che hai citato come alternativa nella guida che abbiamo trovato)
• Notifiche limitate: manca un sistema di notifiche via email/Slack robusto out-of-the-box

IN SINTESI

Planka è la scelta giusta se cerchi un Trello self-hosted semplice ed essenziale per organizzare task di un piccolo team o per uso personale esattamente il tipo di tool che si inserisce bene nel tuo stack homelab accanto a Portainer, Gitea, ecc.

Se invece hai bisogno di project management più strutturato con reportistica, automazioni o gestione risorse, è meglio orientarsi su alternative più feature-rich come Taiga o OpenProject.

Negli ultimi anni la gestione delle password è diventata un tema centrale per chiunque si occupi di sicurezza informatica, sia in ambito personale che professionale.

Tra i tanti password manager disponibili, Bitwarden si è affermato come una delle soluzioni open source più apprezzate, grazie alla sua compatibilità multipiattaforma e alle funzionalità avanzate di condivisione e organizzazione dei dati.

Per chi, come me, preferisce mantenere il pieno controllo dei propri dati attraverso soluzioni self-hosted, Vaultwarden rappresenta l’alternativa ideale: si tratta di un’implementazione non ufficiale del server Bitwarden, scritta in Rust, estremamente leggera e perfettamente compatibile con tutti i client ufficiali (estensioni browser, app mobile, desktop).

Questo la rende una scelta particolarmente indicata per ambienti homelab, dove risorse hardware contenute e semplicità di gestione sono priorità assolute.

In questa guida vedremo passo per passo come installare e configurare Vaultwarden su Ubuntu Server 26.04, utilizzando Docker e Docker Compose per un deployment pulito e facilmente riproducibile.

Affronteremo l’installazione del container, la configurazione delle variabili d’ambiente essenziali, l’impostazione di un reverse proxy per l’accesso sicuro via HTTPS, e la gestione dei certificati in un contesto di laboratorio locale. Al termine della guida avrete un’istanza di Vaultwarden pienamente funzionante, pronta per essere utilizzata come gestore password centralizzato per la vostra infrastruttura.

AGGIORNAMENTO DEL SISTEMA E PREREQUISITI

Eseguire i comandi:

sudo apt update && sudo apt upgrade -y

sudo apt install -y ca-certificates curl

INSTALLAZIONE DI DOCKER

Ubuntu 26.04 supporta nativamente il repository ufficiale Docker. Docker CE 29.4.0 supporta Ubuntu 26.04 nativamente dal giorno del rilascio, senza bisogno di workaround o pinning a codename precedenti.

Installare la chiave GPG ufficiale Docker con i comandi:

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc

Confiugurare il repository (formato DEB822) con i comandi:

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Quindi eseguire i comandi:

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

NOTA BENE: se ricevi un 404 sull’apt update (repository Docker non ancora popolato per resolute), puoi sostituire temporaneamente il codename con noble (Ubuntu 24.04), dato che i pacchetti sono compatibili a livello binario. In tal caso modifica il file docker.sources cambiando Suites: resolute in Suites: noble. Margrop Blog

Verificare l’installazione con i seguenti comandi:

sudo systemctl enable --now docker

sudo docker run --rm hello-world

Aggiungere il tuo utente al gruppo docker se vuoi eseguire comandi senza sudo con il comando:

sudo usermod -aG docker $USER

newgrp docker

STRUTTURA DIRECTORY PER VAULTWARDEN

Creare le cartelle con il comando:

sudo mkdir -p /opt/vaultwarden/data

cd /opt/vaultwarden

CREAZIONE DEL FILE DOCKER-COMPOSE

Creare il file docker-compose.yml con il comando:

sudo nano /opt/vaultwarden/docker-compose.yml

Quindi incollare il seguente contenuto:

services:
vaultwarden:
image: vaultwarden/server:latest
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: "https://vault.tuodominio.it"
SIGNUPS_ALLOWED: "false" # metti a true solo per il primo utente, poi disattiva
WEBSOCKET_ENABLED: "true"
ADMIN_TOKEN: "GENERA_UN_TOKEN_FORTE_QUI"
LOG_FILE: "/data/vaultwarden.log"
TZ: "Europe/Rome"
volumes:
- /opt/vaultwarden/data:/data
ports:
- "192.168.80.34:8080:80" # bind solo su localhost, esposto poi via NPM

Salvare e chiudere il file di configurazione

Generare un ADMIN_TOKEN sicuro (per accedere al pannello admin di Vaultwarden) con il comando:

openssl rand -base64 48

Incollare il risultato al posto di GENERA_UN_TOKEN_FORTE_QUI.

AVVIO DEL CONTAINER

Eseguire i comandi di seguito per avviare il container:

cd /opt/vaultwarden

sudo docker compose up -d

Verificare il container con il comando:

sudo docker compose logs -f

Se è tutto OK dovremmo visualizzare il seguente output:

vaultwarden | /--------------------------------------------------------------------\
vaultwarden | | Starting Vaultwarden |
vaultwarden | | Version 1.36.0 |
vaultwarden | |--------------------------------------------------------------------|
vaultwarden | | This is an *unofficial* Bitwarden implementation, DO NOT use the |
vaultwarden | | official channels to report bugs/features, regardless of client. |
vaultwarden | | Send usage/configuration questions or feature requests to: |
vaultwarden | | https://github.com/dani-garcia/vaultwarden/discussions or |
vaultwarden | | https://vaultwarden.discourse.group/ |
vaultwarden | | Report suspected bugs/issues in the software itself at: |
vaultwarden | | https://github.com/dani-garcia/vaultwarden/issues/new |
vaultwarden | \--------------------------------------------------------------------/
vaultwarden |
vaultwarden | [NOTICE] You are using a plain text `ADMIN_TOKEN` which is insecure.
vaultwarden | Please generate a secure Argon2 PHC string by using `vaultwarden hash` or `argon2`.
vaultwarden | See: https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page#secure-the-admin_token
vaultwarden |
vaultwarden | [2026-07-12 00:02:59.873][vaultwarden::auth][INFO] Private key 'data/rsa_key.pem' created correctly
vaultwarden | [2026-07-12 00:02:59.975][start][INFO] Rocket has launched from http://0.0.0.0:80

CONFIGURAZIONE REVERSE PROXY (NGINX PROXY MANAGER)

In questo tutorial utlizzerò come Reverse Proxy NPM

Creare un nuovo Proxy Host con queste info:

Domain: vault.lab.prv
Scheme: http
Forward Hostname/IP: IP del server dove gira Vaultwarden
Forward Port: 8080
Abilitare Websockets Support (fondamentale per la sync in tempo reale)
Tab SSL: richiedi certificato Let’s Encrypt, forza HTTPS.

ATTENZIONE: Vaultwarden richiede HTTPS per funzionare correttamente con le app client (browser extension, mobile), quindi il certificato non è opzionale.

PRIMO ACCESSO TRAMITE WEB GUI E CREAZIONE UTENTE

Aprire un qualsiasi browser e richiamare https://vault.lab.prv

Cliccare su Crea Account

Inserire l’indirizzo email e il nome quindi cliccare Continua

Inserire la Password quindi cliccare Create Account

Installare l’estensione o cliccare Più tardi per installarla in seguito

Cliccare Vai a Bitwarden WEB

Se è andato tutto a buon fine dovremmo visualizzare la Dashboard di Vaultwarden come mostrato nell’immagine sovrastante

Dopo aver creato l’utente admin disattivare la possibilità di registrare utenti modificando all’interno del file docker-compose.yml il seguente valore:

SIGNUPS_ALLOWED: "false"

Salvare e chiudere il file YAML

Quindi eseguire il comando:

sudo docker compose up -d

ACCESSO AL PANNELLO DI AMMINISTRAZIONE

Raggiungibile su https://vault.lab.prv/admin richiede il token generato in precedenza.

Inserire il Token quindi cliccare Enter

Se è tutto OK dovremmo accedere all’interfaccia Admin di Vaultwarden

Dal tab Users è possibile aggiungere gli utenti

Dal Tab Diagnostic è possibile vedere tutte le informazioni relative al server Vault

BACKUP

Il volume /opt/vaultwarden/data contiene tutto (database SQLite, attachments, config).

Backup consigliato con il comando:

sudo tar czf vaultwarden-backup-$(date +%F).tar.gz /opt/vaultwarden/data

Puoi integrarlo facilmente nel tuo stack Veeam/backup esistentem o schedularlo con un cron job verso il NAS.

AGGIORNAMENTI DI VAULTWARDEN

Per eseguire gli aggiornamenti di VaultWarden eseguire i comandi:

cd /opt/vaultwarden

sudo docker compose pull

sudo docker compose up -d

FUNZIONALITA’ PRINCIPALI

Gestione password e vault

• Password, note sicure, identità, carte di credito
• Cartelle e organizzazione vault
• Generatore di password/passphrase integrato
• Ricerca full-text nel vault
• Allegati ai singoli item (es. PDF, chiavi SSH)

Sincronizzazione multi-dispositivo

• Estensioni browser (Chrome, Firefox, Edge, Safari, Brave)
• App mobile (iOS/Android)
• App desktop (Windows/Mac/Linux)
• CLI ufficiale Bitwarden
• Sync in tempo reale via WebSocket (quello che abbiamo abilitato con WEBSOCKET_ENABLED)

Organizzazioni e condivisione (gratis su Vaultwarden, a pagamento su Bitwarden ufficiale)

• Creazione organizzazioni multiple
• Condivisione password tra utenti/gruppi
• Collections con permessi granulari
• Questo è uno dei motivi principali per cui la gente sceglie Vaultwarden: su Bitwarden cloud le organizzazioni richiedono piano a pagamento, qui sono gratuite

Autenticazione a due fattori (2FA)

• TOTP (Google Authenticator, Authy, ecc.)
• WebAuthn/FIDO2 (chiavi hardware tipo YubiKey)
• Duo (con configurazione aggiuntiva)
• Email 2FA
• Yubikey OTP

Bitwarden Send

• Condivisione sicura e temporanea di testo/file con link, scadenza automatica, password opzionale

Pannello admin (/admin)

• Gestione utenti (creazione, disabilitazione, eliminazione)
• Statistiche generali istanza
• Configurazione SMTP per invii email (inviti, reset password)
• Diagnostica (test connessione, versione, ecc.)
• Backup/export diagnostica

Import/Export

• Import da centinaia di altri password manager (LastPass, 1Password, KeePass, Chrome, ecc.)
• Export in formati cifrati o JSON/CSV

Emergency Access

• Designazione di un contatto di emergenza che può richiedere accesso al vault dopo un periodo di attesa configurabile

PRO E CONTRO

PRO

• Leggerissimo: Un singolo binario Rust, consumo RAM/CPU minimo — perfetto per homelab, gira bene anche su Raspberry Pi
• Compatibilità client al 100%: Usa le stesse app/estensioni ufficiali Bitwarden, nessuna app custom da installareù
• Funzionalità premium gratis: Organizzazioni, 2FA avanzato, Send: tutto ciò che su Bitwarden cloud richiede abbonamento qui è gratuito
• Self-hosted: controllo totale datiNessun dato transita su server terzi, importante per compliance/privacy
• Community attiva: Sviluppo costante, rilasci frequenti, ben documentato
• Facile da backuppare: Tutto in un volume/cartella (SQLite di default), backup semplice da integrare in Veeam o script cron
• Basso attack surface: Codice compatto rispetto al server ufficiale Bitwarden (che è containerizzato in decine di microservizi via bitwarden/self-host)

CONTRO

• Non ufficiale/non supportato da Bitwarden Inc.: Se qualcosa si rompe, supporto solo community (GitHub issues, Discord), nessun SLA
• Rischio di rottura compatibilità: Bitwarden Inc. può cambiare API client senza preavviso; Vaultwarden deve rincorrere gli aggiornamenti a volte con ritardo di giorni/settimane
• SQLite come DB di default: Va benissimo per uso personale/piccolo team, ma non scala bene per centinaia di utenti simultanei (puoi comunque passare a MySQL/PostgreSQL se serve)
• Nessuna interfaccia “enterprise”: Manca SSO/SAML nativo enterprise-grade (esiste supporto limitato, non paragonabile a Bitwarden Enterprise)
• Responsabilità di gestione tutta tua: Backup, certificati, aggiornamenti, sicurezza del server: nessuno lo fa per te (a differenza di Bitwarden cloud)
• Alcune funzionalità arrivano in ritardo: Feature nuove lato client Bitwarden a volte non sono supportate lato server finché la community non le implementa
• Termini di servizio “grigi”: Bitwarden Inc. non garantisce che i client ufficiali continueranno a funzionare con implementazioni terze in futuro (per ora nessun blocco, ma è un rischio teorico da tenere presente)
• Single point of failure: Se il tuo server va giù, perdi accesso al vault (mitigabile con backup + export periodici offline)

CONSIDERAZIONI FINALI

• Per uso personale/homelab: scelta quasi obbligata, SQLite basta e avanza
• Se in futuro pensi di offrirlo a clienti come servizio gestito: valuta il passaggio a PostgreSQL come backend (più robusto per multi-tenant) e assicurati SLA chiari con i clienti sul fatto che non è supporto ufficiale Bitwarden
• Backup: essendo SQLite, è un singolo file perfetto per backup incrementali veloci, ma verifica sempre la consistenza (evita backup “a caldo” senza dump, meglio uno stop breve o sqlite3 .backup)