Vaultwarden Docker Compose con HTTPS: installarlo su Linux con Caddy

Questa guida serve a chi vuole tenere le password su un server proprio e usarle con le app di Bitwarden. Vaultwarden è un server scritto in Rust e compatibile con i client ufficiali di Bitwarden. Alla fine Vaultwarden gira in Docker Compose dietro Caddy, che ottiene da solo il certificato HTTPS. Sul server c’è un solo account registrato e le iscrizioni sono chiuse. La pagina /admin è protetta da un token in hash Argon2 e hai un metodo per fare il backup dei dati. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa serve

Vaultwarden è un progetto non ufficiale. Il README del repository lo dice: «not associated with Bitwarden, Inc.». Funziona con i client ufficiali di Bitwarden, ma i problemi del server vanno segnalati ai canali di Vaultwarden, non al supporto di Bitwarden. Le app sono spiegate nella nostra guida a Bitwarden.

L’HTTPS è obbligatorio. Il web vault usa le API WebCrypto, che i browser mettono a disposizione solo in un contesto sicuro. La pagina della wiki sull’HTTPS raccomanda di mettere un reverse proxy davanti a Vaultwarden. A chi non ha preferenze suggerisce Caddy, che ottiene da solo i certificati Let’s Encrypt. Questa guida usa solo Caddy.

Prima di cominciare controlla di avere:

• un server Linux con Debian o Ubuntu. La guida segue la documentazione di Docker per queste due distribuzioni e non tratta Windows o macOS come server;
• un nome di dominio che punti all’indirizzo IP del server, per esempio vaultwarden.example.com. Questa guida richiede un nome DNS per seguire l’esempio proposto. Let’s Encrypt offre anche certificati per indirizzi IP, con durata di circa sei giorni e una configurazione specifica non trattata qui;
• le porte 80 e 443 del server raggiungibili da Internet. Caddy usa la porta 80 per la sfida ACME HTTP-01, con cui ottiene il certificato. La 443 serve per l’HTTPS e, in UDP, per HTTP/3;
• un indirizzo email per la registrazione ACME.

Questo esempio non va bene se il server non deve essere raggiungibile da Internet. Per quel caso la wiki propone la sfida DNS, che questa guida non tratta.

Installare Docker e il plugin Docker Compose

La documentazione di Docker sul plugin Compose dà per scontato che Docker Engine e la CLI siano già installati. Se non li hai, installali e configura il repository di Docker seguendo le istruzioni per Debian o Ubuntu, collegate da quella stessa pagina.

Se un comando docker di questa guida ti risponde con un errore di permessi, ripetilo con sudo davanti.

Aggiorna l’indice dei pacchetti:

sudo apt-get update

Installa il plugin Compose:

sudo apt-get install docker-compose-plugin

Controlla l’installazione chiedendo la versione:

docker compose version

Se il terminale stampa un numero di versione, Compose è installato. Qui si scrive docker compose con lo spazio, perché è la forma del plugin e Docker consiglia di installarlo così. Con la vecchia installazione standalone il comando si scrive docker-compose, con il trattino.

Preparare compose.yaml e Caddyfile dall’esempio ufficiale

La pagina Using Docker Compose della wiki contiene l’esempio «Caddy with HTTP challenge», fatto di due file. Crea una cartella vuota sul server ed entra lì.

In quella cartella crea il file compose.yaml e copiaci l’esempio così com’è. Cambia solo due valori:

• DOMAIN: sostituisci "https://vaultwarden.example.com" con il tuo dominio preceduto da https://. Il valore compare due volte, nel servizio vaultwarden e nel servizio caddy, e deve essere identico in tutti e due;
• EMAIL: sostituisci "[email protected]" con l’indirizzo per la registrazione ACME.

Nella stessa cartella crea il file Caddyfile e copiaci l’esempio della wiki. Questo file non va modificato: prende dominio ed email dalle variabili definite nel Compose.

Vaultwarden salva i dati nella cartella ./vw-data, Caddy usa ./caddy-data e ./caddy-config. Il container vaultwarden non pubblica nessuna porta. Solo Caddy espone 80, 443 e 443/udp e passa il traffico a vaultwarden:80 sulla rete privata che Compose crea in automatico. Non aggiungere porte al servizio vaultwarden.

Avviare i servizi e leggere i log

Il comando crea i container, li avvia in background e mostra i log in diretta:

docker compose up -d && docker compose logs -f

Per uscire dai log premi Ctrl+C. I container continuano a girare.

Verificare il certificato HTTPS

Prima di creare l’account controlla che il certificato sia installato con la catena completa. Senza la catena i dispositivi Android non riescono a collegarsi. Il comando della wiki è questo:

openssl s_client -showcerts -connect vault.domain.com:443 -servername vault.domain.com

vault.domain.com è un segnaposto: sostituiscilo con il tuo dominio in tutti e due i punti. È il dominio che hai scritto in DOMAIN, senza https://. Con un certificato Let’s Encrypt la wiki riporta questo inizio di output:

CONNECTED(00000003)
depth=2 O = Digital Signature Trust Co., CN = DST Root CA X3
verify return:1
depth=1 C = US, O = Let's Encrypt, CN = R3
verify return:1
depth=0 CN = vault.domain.com
verify return:1

L’esempio qui sopra è storico: nomi dei certificati e numero di livelli possono cambiare. Controlla che OpenSSL non segnali errori di verifica e riporti «Verify return code: 0 (ok)»; non richiedere esattamente tre valori di depth. Più avanti nell’output devono comparire i certificati di Let’s Encrypt codificati in base64. Poi apri nel browser l’indirizzo https:// del tuo dominio: deve comparire il web vault.

Creare il primo account e chiudere le registrazioni

Nel web vault scegli «Create account» e registra il tuo account con una master password robusta. Finché le registrazioni sono aperte, chiunque raggiunga il server può registrarsi. Chiudile subito dopo aver creato l’account.

Apri compose.yaml. Nel servizio vaultwarden cambia SIGNUPS_ALLOWED da "true" a "false", come indica il commento nell’esempio minimo della wiki. Poi ricrea il container perché legga la nuova impostazione:

docker compose up -d

Con le registrazioni chiuse restano possibili gli inviti nelle organizzazioni e quelli dalla pagina /admin. Per bloccare anche questi, vedi la pagina «Disable invitations» della wiki.

Attivare la pagina /admin con un token Argon2

Dalla pagina /admin si configura il server e si gestiscono utenti e organizzazioni, fino a disattivarli o cancellarli. La pagina della wiki sull’admin raccomanda di attivarla solo quando l’HTTPS funziona già, e a questo punto è così. Il token fa da password per l’area di amministrazione. Di solito la configurazione è salvata in chiaro, per questo la wiki consiglia di salvare il token come hash Argon2id in formato PHC.

Per generarlo, lancia il comando incluso in Vaultwarden in un container temporaneo:

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

Il comando chiede la password due volte. Se le due coincidono, stampa una stringa che inizia con $argon2id$. Per impostazione predefinita usa i parametri di Bitwarden: 64 MiB di memoria, 3 iterazioni e 4 thread. Conserva la password che hai digitato: per entrare in /admin userai quella, non la stringa.

In compose.yaml, sotto environment del servizio vaultwarden, aggiungi la chiave ADMIN_TOKEN con la stringa PHC come valore. La stringa contiene cinque simboli $. Raddoppiali tutti in $$, altrimenti Compose li interpreta come variabili: $argon2id$v=19$… diventa $$argon2id$$v=19$$…. Non pubblicare la tua stringa e non usare quelle di esempio della wiki.

Controlla la configurazione risultante:

docker compose config

Nella wiki questo comando compare nell’esempio con il file .env. Qui ti serve soprattutto per far emergere gli avvisi di variabile non impostata, come The argon2id variable is not set. Se compaiono, almeno un $ non è stato raddoppiato. Se non ci sono avvisi, ricrea il container:

docker compose up -d

Apri /admin sul tuo dominio ed entra con la password usata per generare l’hash. Per impostazione predefinita la sessione dura 20 minuti. Al primo salvataggio dalla pagina admin, Vaultwarden crea il file config.json nella cartella dati. Da quel momento i valori del file prevalgono sulle variabili d’ambiente e le impostazioni si cambiano dalla pagina admin.

Collegare app ed estensioni Bitwarden al server

Le app per Windows, macOS, Linux, Android e iOS e le estensioni del browser si collegano tutte allo stesso modo. Nella schermata di accesso scegli il server self-hosted al posto di quello di Bitwarden. Inserisci l’indirizzo HTTPS del tuo dominio, lo stesso di DOMAIN, ed entra con l’account appena creato.

Email in uscita (SMTP), autenticazione a due fattori lato server e organizzazioni restano fuori da questa guida. Le pagine dedicate sono nell’indice della wiki.

Fare il backup della cartella dati

Il README avverte che il progetto non risponde di eventuali perdite di dati e raccomanda backup regolari. La pagina della wiki sul backup consiglia un processo automatico e almeno una copia su un’altra macchina o su un cloud. Sconsiglia di affidarsi agli snapshot del filesystem o della macchina virtuale.

Dalla versione 1.32.1 Vaultwarden include un comando di backup. Nell’esempio con Caddy il container si chiama vaultwarden, quindi il comando funziona senza modifiche:

docker exec -it vaultwarden /vaultwarden backup

Per eseguirlo da cron sul server, preferibilmente almeno una volta al giorno, elimina le opzioni interattive: docker exec vaultwarden /vaultwarden backup. Il comando salva solo il database SQLite. Gli altri file di vw-data vanno copiati a parte:

• attachments: backup obbligatorio, perché contiene gli allegati;
• config.json e i file rsa_key*: backup consigliato. Contengono dati sensibili, come il token admin e la chiave che firma le sessioni, quindi cifra le copie;
• sends e icon_cache: backup facoltativo.

Per copiare a mano l’intera cartella in modo coerente, ferma prima i servizi. docker compose down rimuove i container di Vaultwarden e Caddy, ma non tocca le cartelle vw-data, caddy-data e caddy-config. Finché i servizi sono fermi il server non risponde. Lancia il comando dalla cartella che contiene compose.yaml:

docker compose down

Copia la cartella vw-data nella destinazione del backup, poi riavvia i servizi:

docker compose up -d

Per ripristinare, tieni Vaultwarden fermo e sostituisci file e cartelle di vw-data con quelli del backup. Se ripristini un backup del database fatto con .backup o VACUUM INTO, cancella prima il file db.sqlite3-wal esistente: un WAL che non corrisponde può corrompere il database. Anche /vaultwarden backup usa VACUUM INTO e salva un file db_AAAAMMGG_HHMMSS.sqlite3 nella cartella del database, quindi qui in vw-data. Per ripristinarlo, ferma Vaultwarden, elimina l’eventuale db.sqlite3-wal esistente e copia il backup scelto come vw-data/db.sqlite3, sostituendo il database precedente. Se invece hai copiato a freddo db.sqlite3 insieme al suo db.sqlite3-wal, ripristina i due file in coppia. Prova un ripristino a intervalli regolari e tieni da parte una copia dei dati originali.

Aggiornare, fermare o disinstallare

Per aggiornare, scarica le immagini nuove, ricrea i container e controlla i log:

docker compose pull && docker compose up -d && docker compose logs -f

Esci dai log con Ctrl+C. Per fermare tutto usa il comando qui sotto: rimuove i container e lascia intatte le cartelle con i dati e i certificati.

docker compose down

Per disinstallare del tutto, dopo il down cancella a mano le cartelle vw-data, caddy-data e caddy-config. Fallo solo dopo un backup verificato. Se cancelli vw-data perdi per sempre il database con le password di tutti gli utenti e gli allegati.

Se qualcosa va storto

• Avvisi «The argon2id variable is not set» o simili: nella stringa PHC dentro compose.yaml almeno un $ non è stato raddoppiato.
• «You are using a plain text ADMIN_TOKEN which is insecure.»: le cause possibili sono due. Hai già salvato la configurazione dalla pagina admin e config.json prevale sulle variabili d’ambiente, oppure il formato è sbagliato. Controlla che la stringa non abbia virgolette in più attorno.
• La pagina admin accetta come password l’intera stringa $argon2id$…: la versione di Vaultwarden è vecchia e non supporta Argon2id. Aggiorna Vaultwarden.
• L’app mobile mostra «Chain validation failed»: controlla la validità del certificato e la completezza della catena presentata dal server con openssl. Con i certificati attuali di Let’s Encrypt l’assenza di OCSP stapling è normale e non dimostra un guasto.
• Gli allegati non si scaricano in Firefox: secondo il commento nel Caddyfile, la riga encode zstd gzip può dare problemi con alcuni browser. Il commento suggerisce di provare a disattivarla.

Documentazione di riferimento

Pagine consultate il 17 ottobre 2026:

• Repository ufficiale di Vaultwarden, README
• Wiki di Vaultwarden
• Wiki di Vaultwarden, Using Docker Compose
• Wiki di Vaultwarden, Enabling HTTPS
• Wiki di Vaultwarden, Enabling admin page
• Wiki di Vaultwarden, Backing up your vault
• Documentazione di Docker, Install the Docker Compose plugin (Linux): i comandi usati valgono per Debian e Ubuntu.

Leggi anche

• Bitwarden: come creare l’account e proteggerlo con la verifica in due passaggi
• Installare Docker su Ubuntu con il plugin Compose, passo passo
• Forgejo Docker Compose: come installarlo su un server di casa