Vaultwarden su VPS Linux con Docker: password manager self-hosted leggero

Gestire le password in modo ordinato e sicuro è diventato fondamentale, soprattutto se utilizzi molti servizi online, pannelli di amministrazione, server Linux e strumenti self-hosted. Se vuoi una soluzione sotto il tuo controllo, accessibile via browser e compatibile con i client Bitwarden, Vaultwarden è uno dei progetti più interessanti da provare. Vaultwarden è infatti una implementazione alternativa della Bitwarden API, scritta in Rust e pensata per ambienti self-hosted dove la soluzione ufficiale può risultare più pesante.

In questa guida vedremo come installare Vaultwarden su un VPS Linux con Docker, come esporlo in modo corretto dietro un reverse proxy e come preparare una configurazione semplice, adatta anche a chi è alle prime armi con questi strumenti. Il metodo consigliato dal progetto è proprio l’uso delle immagini container pubblicate ufficialmente.

Perché installare Vaultwarden su un VPS Linux

Un password manager self-hosted ti permette di conservare credenziali, note sicure e altri dati sensibili in un servizio che gestisci direttamente tu. Vaultwarden è particolarmente interessante perché punta a essere leggero nelle risorse pur restando compatibile con i client Bitwarden.

Installarlo su un VPS Linux ha diversi vantaggi:

• puoi accedere al tuo vault da browser, desktop e smartphone;
• hai il controllo dell’istanza e dei dati persistenti;
• puoi integrarlo con altri servizi self-hosted già presenti sul server;
• con Docker gli aggiornamenti diventano molto più semplici da gestire.

Requisiti minimi consigliati

Per una piccola installazione personale o familiare, i requisiti sono abbastanza contenuti perché Vaultwarden è pensato per essere leggero rispetto ad altre soluzioni compatibili Bitwarden.

• 1 VPS con Debian 12/13 oppure Ubuntu 22.04 o 24.04;
• 1 vCPU;
• 1 GB di RAM minimo, meglio 2 GB se sul server ci sono altri container;
• 10 GB di spazio disco;
• accesso SSH con utente sudo;
• un dominio o sottodominio dedicato, ad esempio vault.tuodominio.it;
• porte 80 e 443 aperte nel firewall.

È importante usare HTTPS, perché la pagina Docker ufficiale del progetto segnala che alcuni browser, come Chrome, non consentono l’uso delle Web Crypto API in contesti non sicuri; in quel caso il Web Vault può non funzionare correttamente.

Aggiornare il server Linux

Prima di iniziare conviene aggiornare il sistema operativo del VPS:

sudo apt update
sudo apt upgrade -y

Se il server ha installato aggiornamenti importanti del kernel o dei servizi di base, puoi riavviarlo:

sudo reboot

Dopo il riavvio, ricollegati via SSH.

Installare Docker e Docker Compose

Vaultwarden viene distribuito come immagine docker e questo è il metodo raccomandato per l’installazione.

Installiamo prima alcuni pacchetti di base:

sudo apt install -y ca-certificates curl gnupg

Creiamo la directory per le chiavi APT:

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

Se usi Ubuntu, scarica la chiave ufficiale di Docker:

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

Aggiungiamo il repository Docker:

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

Aggiorniamo i repository e installiamo Docker con il plugin Compose:

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

Verifichiamo che Docker sia attivo:

sudo systemctl enable --now docker
sudo systemctl status docker

Per confermare che tutto sia disponibile:

docker --version
docker compose version

Creare la cartella del progetto Vaultwarden

Ora prepariamo una directory dedicata al progetto:

sudo mkdir -p /opt/vaultwarden
sudo chown $USER:$USER /opt/vaultwarden
cd /opt/vaultwarden

All’interno di questa directory salveremo il file Compose e i dati persistenti del servizio. La documentazione Docker del progetto raccomanda infatti di montare un volume host verso /data/ per mantenere in modo persistente i dati dell’istanza.

Generare un token amministrativo sicuro

Vaultwarden può esporre una pagina amministrativa, ma è importante non usare un ADMIN_TOKEN in chiaro. La wiki ufficiale del progetto raccomanda infatti di proteggere questo token usando una stringa Argon2 PHC, generata con il comando integrato vaultwarden hash oppure con il tool argon2.

Per un’installazione con Docker, il metodo più semplice è usare direttamente il comando integrato del container:

docker run --rm -it vaultwarden/server /vaultwarden hash

Il comando ti chiederà di inserire due volte una password. Scegline una lunga e robusta: sarà questa la password da usare poi per entrare nella pagina amministrativa di Vaultwarden, non la stringa hash finale.

Al termine, otterrai una stringa simile a questa:

$argon2id$v=19$m=65540,t=3,p=4$........$........

Se usi il valore direttamente dentro docker-compose.yml, devi ricordarti di raddoppiare tutti i simboli $ come $$, altrimenti Docker Compose proverà a interpretarli come variabili. La wiki ufficiale lo segnala esplicitamente.

Per esempio, una stringa come questa:

$argon2id$v=19$m=65540,t=3,p=4$ABC$XYZ

deve diventare così nel file Compose:

$$argon2id$$v=19$$m=65540,t=3,p=4$$ABC$$XYZ

Creare il file docker-compose.yml

Creiamo il file principale della stack Docker:

nano docker-compose.yml

Inserisci questa configurazione di base:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      - DOMAIN=https://vault.tuodominio.it
      - ADMIN_TOKEN=$$argon2id$$v=19$$m=65540,t=3,p=4$$INSERISCI$$QUI$$LA$$STRINGA$$COMPLETA
      - SIGNUPS_ALLOWED=false
    volumes:
      - ./vw-data:/data
    ports:
      - "127.0.0.1:8080:80"

Questa configurazione usa l’immagine ufficiale del container pubblicata come vaultwarden/server, monta i dati in una cartella locale persistente e pubblica il servizio solo in locale sulla porta 8080, così da lasciarlo dietro reverse proxy. La pagina Docker del progetto mostra infatti come caso base l’uso del container con volume persistente montato verso /data.

Il progetto specifica che, quando si usa docker-compose.yml, tutti i simboli $ della stringa Argon2 vanno escapati con $$. In alternativa, puoi usare un file .env, dove si utilizza invece la versione normale con i simboli $ singoli.

Se vuoi, puoi creare anche una cartella dati in anticipo:

mkdir -p /opt/vaultwarden/vw-data

Avviare Vaultwarden

Una volta salvato il file, puoi avviare il container:

cd /opt/vaultwarden
docker compose up -d

Controlla che il servizio sia partito:

docker compose ps

Per leggere i log:

docker compose logs -f vaultwarden

Se tutto è corretto, Vaultwarden sarà raggiungibile localmente sulla porta 8080 del VPS.

Test locale del servizio

Prima di configurare il reverse proxy, puoi verificare che l’applicazione risponda in locale:

curl -I http://127.0.0.1:8080

Se ricevi una risposta HTTP valida, il container è in funzione.

Installare Caddy come reverse proxy

Per esporre Vaultwarden in HTTPS in modo semplice possiamo usare Caddy, che gestisce automaticamente anche i certificati Let’s Encrypt. La pagina Docker del progetto ricorda infatti che l’accesso HTTPS è importante per il corretto funzionamento del Web Vault nei browser moderni.

Installiamo i pacchetti necessari:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

Importiamo la chiave del repository:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

Aggiungiamo il repository:

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

Installiamo Caddy:

sudo apt update
sudo apt install -y caddy

Configurare Caddy per Vaultwarden

Apri il file di configurazione:

sudo nano /etc/caddy/Caddyfile

Inserisci una configurazione come questa, sostituendo il dominio con il tuo:

vault.tuodominio.it {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Real-IP {remote_host}
    }
    encode gzip zstd
}

Una configurazione di esempio con X-Real-IP inoltrato dal reverse proxy compare anche in una guida di deployment con Caddy dedicata a Vaultwarden.

Salva il file, poi verifica che la sintassi sia corretta:

sudo caddy validate --config /etc/caddy/Caddyfile

Se non ci sono errori, ricarica Caddy:

sudo systemctl reload caddy
sudo systemctl status caddy

Se il DNS del dominio punta già al tuo VPS, Caddy proverà a emettere automaticamente il certificato TLS.

Aprire il firewall

Se stai usando UFW, apri SSH, HTTP e HTTPS:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Accedere a Vaultwarden dal browser

A questo punto dovresti poter aprire dal browser:

https://vault.tuodominio.it

Se tutto è andato bene, vedrai l’interfaccia web del vault. Poiché Vaultwarden è compatibile con i client Bitwarden, potrai poi configurare anche le app desktop o mobile usando il tuo URL personalizzato.

Registrazione utenti e primo account

Nella configurazione proposta abbiamo impostato SIGNUPS_ALLOWED=false per motivi di sicurezza, così da evitare registrazioni pubbliche incontrollate. Per il primo avvio hai due strade:

• imposti temporaneamente SIGNUPS_ALLOWED=true, crei il tuo account e poi rimetti il valore a false;
• lasci chiuse le registrazioni pubbliche e gestisci gli utenti solo in modo controllato.

Se vuoi creare il primo account in modo semplice, modifica momentaneamente il file docker-compose.yml così:

- SIGNUPS_ALLOWED=true

Poi riavvia il container:

docker compose down
docker compose up -d

Apri il sito, registra il tuo account principale e poi riporta il valore a false per chiudere nuovamente le iscrizioni.

Accedere al pannello amministrativo

La pagina amministrativa è normalmente disponibile su https://vault.tuodominio.it/admin. Se hai configurato un ADMIN_TOKEN protetto con Argon2, per il login devi inserire la password scelta durante la generazione del token, non la stringa hash completa salvata nel file Compose.

La wiki ufficiale precisa inoltre che, se hai già salvato impostazioni dalla pagina amministrativa, il file config.json può avere priorità rispetto alle variabili ambiente. In quel caso bisogna prestare attenzione perché modificare solo il Compose potrebbe non bastare a rimuovere l’avviso o aggiornare davvero il token.

Aggiornare Vaultwarden

Usando Docker Compose, l’aggiornamento è molto semplice:

cd /opt/vaultwarden
docker compose pull
docker compose up -d

Controlla poi lo stato del servizio:

docker compose ps
docker compose logs --tail=50 vaultwarden

La pagina Docker mostra anche i tag disponibili del container, incluso il tag latest e versioni specifiche, quindi se preferisci maggiore controllo puoi bloccare l’immagine a una release precisa invece di usare sempre l’ultima.

Backup dei dati

Poiché i dati persistenti vengono salvati nella cartella /opt/vaultwarden/vw-data, il backup è abbastanza semplice: ti basta includere quella directory nel tuo sistema di backup del VPS. La persistenza tramite volume host montato verso /data è proprio il meccanismo previsto dalla documentazione del container.

Ad esempio, puoi creare un archivio compresso manuale:

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

Naturalmente, in un ambiente reale è meglio integrare questo percorso in un sistema di backup periodico già esistente.

Problemi comuni

Il sito si apre ma il Web Vault non funziona bene

La causa più comune è l’assenza di HTTPS. La documentazione del container segnala esplicitamente che in contesti non sicuri alcuni browser possono bloccare le Web Crypto API, causando problemi nel Web Vault.

Il pannello admin risulta disabilitato

Di solito significa che ADMIN_TOKEN non è stato impostato correttamente nel file Compose o che il container non è stato ricreato dopo la modifica. Le discussioni di supporto riportano proprio questo comportamento quando la variabile non è presente.

I dati spariscono dopo il riavvio del container

In quel caso controlla il mount del volume, perché Vaultwarden deve salvare i dati in una directory persistente del server, mappata verso /data nel container.

Non riesco a registrare il primo utente

Se hai lasciato SIGNUPS_ALLOWED=false, le registrazioni pubbliche sono disabilitate. Imposta temporaneamente il valore a true, crea l’account principale e poi richiudile.

FAQ

Vaultwarden è il server ufficiale di Bitwarden?

No. La pagina del progetto specifica che Vaultwarden è una implementazione alternativa della Bitwarden API, non associata ufficialmente al progetto Bitwarden.

Perché devo usare HTTPS con Vaultwarden?

Perché la pagina Docker del progetto avverte che alcuni browser bloccano le Web Crypto API in contesti non sicuri, e questo può causare errori nel Web Vault se il sito non è pubblicato in HTTPS.

Considerazioni finali

Vaultwarden è una soluzione molto interessante per chi vuole un password manager self-hosted più leggero, compatibile con i client Bitwarden e facile da mantenere su un VPS Linux tramite Docker. Il progetto stesso presenta il deployment container come metodo raccomandato e sottolinea l’importanza della persistenza dati e dell’uso di HTTPS.

Per un uso personale o familiare, questa configurazione rappresenta un ottimo punto di partenza. Una volta verificato che tutto funziona, puoi aggiungere backup automatici, ulteriori regole di protezione sul reverse proxy e una strategia di aggiornamento periodica del container.

Se vuoi provare un’istanza già installata e configurata, ti consiglio quella di Devol, Devol infatti è un progetto collettivo no-profit nato nel 2019 che promuove il fediverso e l’indipendenza dalle Big Tech.