Installare Vaultwarden con HTTPS e backup
Ospita Vaultwarden su Debian o Ubuntu con Docker e Caddy: HTTPS obbligatorio, registrazioni chiuse, token di amministrazione con hash, aggiornamenti, backup e prova di ripristino.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come ospitare Vaultwarden, un server leggero compatibile con le app Bitwarden, sul tuo server. Vaultwarden gira in Docker e resta accessibile solo in locale. Caddy lo pubblica in HTTPS.
Al termine della guida, la tua cassaforte risponde su https://vault.tuo-dominio.com, nessuno può registrarsi senza invito, il token di amministrazione è conservato sotto forma di hash ed esiste un backup giornaliero, di cui hai verificato il ripristino.
Ordina un Server
Questa guida si applica ai server che amministri tu stesso:
Prerequisiti
- Un server con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso SSH con un utente che dispone di
sudo - Docker Engine e Docker Compose, installati con la guida Installare Docker Engine e Docker Compose
- Caddy, installato con la guida Caddy come reverse proxy con HTTPS automatico
- Un nome di dominio di cui gestisci la zona DNS
- L'indirizzo IP pubblico del tuo computer, per limitare l'accesso alla pagina di amministrazione
Porte utilizzate
| Porta | Direzione | Ruolo | Da aprire |
|---|---|---|---|
| 80/tcp | In entrata | Validazione del certificato e reindirizzamento a HTTPS | Sì |
| 443/tcp | In entrata | Accesso HTTPS alla cassaforte | Sì |
| 443/udp | In entrata | HTTP/3 | Consigliato |
| 8222/tcp | Locale | Vaultwarden, solo su 127.0.0.1 |
No |
Passo 1: preparare il dominio e il firewall
Crea un record A per vault.tuo-dominio.com verso IP_DEL_TUO_SERVER. Se il tuo dominio è gestito presso HostMyServers, segui la guida Creare un record A.
Se usi UFW, autorizza le porte web:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw statusSe UFW non è ancora attivo, segui prima la guida Configurare il firewall UFW senza perdere l'accesso SSH.
Le porte pubblicate da Docker aggirano le regole di UFW. Per questo il file Compose del passo 3 pubblica Vaultwarden su 127.0.0.1: così non è raggiungibile da Internet, qualunque siano le tue regole.
Passo 2: creare il token di amministrazione con hash
La pagina /admin permette di gestire gli account dell'istanza. È protetta da un token, che conserverai solo sotto forma di impronta Argon2.
Crea la cartella dell'applicazione, poi genera una password di amministrazione lunga e casuale:
sudo mkdir -p /opt/vaultwarden
cd /opt/vaultwarden
openssl rand -base64 32Conserva questa password fuori dalla cassaforte, ad esempio in un altro gestore o su un supporto offline. Ti servirà per accedere a /admin, anche se la cassaforte non è disponibile.
Calcola poi la sua impronta. Il comando chiede la password due volte:
sudo docker run --rm -it vaultwarden/server:1.37.5 /vaultwarden hashMostra una riga di questo tipo:
ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'Crea il file .env:
sudo nano /opt/vaultwarden/.envIncollaci l'impronta, tra apici e senza raddoppiare i $:
VAULTWARDEN_ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'Proteggi il file:
sudo chmod 600 /opt/vaultwarden/.envPasso 3: scrivere il file Compose
sudo nano /opt/vaultwarden/compose.yamlservices:
vaultwarden:
image: vaultwarden/server:1.37.5
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: "https://vault.tuo-dominio.com"
SIGNUPS_ALLOWED: "false"
ADMIN_TOKEN: "${VAULTWARDEN_ADMIN_TOKEN}"
volumes:
- ./vw-data:/data
ports:
- "127.0.0.1:8222:80"| Parametro | Ruolo |
|---|---|
image |
Versione precisa, che cambi di tua volontà durante gli aggiornamenti |
DOMAIN |
Indirizzo pubblico esatto, con https:// |
SIGNUPS_ALLOWED |
false chiude le registrazioni libere fin dal primo avvio |
ADMIN_TOKEN |
Impronta letta da .env |
127.0.0.1:8222:80 |
Porta accessibile solo dal server |
Controlla il risultato, poi avvia il servizio:
cd /opt/vaultwarden
sudo docker compose config --quiet
sudo docker compose up -d
sudo docker compose ps
curl -fsS http://127.0.0.1:8222/aliveL'ultimo comando restituisce una data tra virgolette. Dopo circa un minuto, la colonna di stato di docker compose ps indica healthy.
Passo 4: pubblicare la cassaforte con Caddy
Aggiungi questo sito in /etc/caddy/Caddyfile, oppure in un file di /etc/caddy/sites/ se usi gli import:
vault.tuo-dominio.com {
encode zstd gzip
@admin_denied {
path /admin /admin/*
not client_ip TUO_IP
}
abort @admin_denied
reverse_proxy 127.0.0.1:8222 {
header_up X-Real-IP {remote_host}
}
}Solo TUO_IP può raggiungere /admin: le altre connessioni vengono interrotte senza risposta. Se accedi a Internet in IPv6, aggiungi anche il tuo indirizzo IPv6 dopo client_ip. L'header X-Real-IP permette a Vaultwarden di registrare nei log l'indirizzo reale dei visitatori.
Convalida e applica la configurazione:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyVerificare il risultato
curl -I http://vault.tuo-dominio.com
curl -fsS https://vault.tuo-dominio.com/alive
sudo ss -ltnp | grep 8222Il primo comando deve restituire un reindirizzamento 308 verso HTTPS e il secondo una data. Il terzo deve mostrare 127.0.0.1:8222 e nessun indirizzo pubblico.
Dal tuo computer, http://IP_DEL_TUO_SERVER:8222 non deve rispondere. Da una connessione che non usa TUO_IP, ad esempio uno smartphone con dati mobili, https://vault.tuo-dominio.com/admin deve fallire.
Passo 5: creare il tuo account su invito
Poiché le registrazioni sono chiuse, il primo account passa da un invito dell'amministratore.
- Apri
https://vault.tuo-dominio.com/admindaTUO_IP. - Inserisci la password generata al passo 2, e non la sua impronta.
- Nella scheda Users, usa il riquadro Invite User con il tuo indirizzo e-mail.
- Senza un server SMTP non viene inviato alcun messaggio. Apri direttamente
https://vault.tuo-dominio.com/#/signupe registrati con lo stesso indirizzo. - Scegli una password principale lunga e unica, poi accedi.
Attiva poi un metodo di accesso a due passaggi nelle impostazioni di sicurezza dell'account, e conserva il suo codice di recupero fuori dalla cassaforte.
Nelle app Bitwarden per computer, dispositivi mobili o browser, scegli un server self-hosted nella schermata di accesso, poi indica https://vault.tuo-dominio.com.
Passo 6: ridurre la superficie d'attacco
Dopo aver creato i tuoi account, aggiungi questa riga in environment perché i membri di un'organizzazione non possano più invitare nuovi utenti:
INVITATIONS_ALLOWED: "false"Se non usi più la pagina di amministrazione, disattivala rimuovendo la riga ADMIN_TOKEN da compose.yaml. Verifica anche che in vw-data/config.json non esista alcuna chiave admin_token, se il file è presente. Applica poi le modifiche:
cd /opt/vaultwarden
sudo docker compose up -dPer invitare una nuova persona in seguito, ripristina temporaneamente ADMIN_TOKEN, rimuovi INVITATIONS_ALLOWED, poi ricrea il container allo stesso modo.
Aggiornare Vaultwarden
Consulta le note di rilascio, esegui un backup con il servizio creato nella sezione successiva, poi sostituisci il numero di versione in compose.yaml:
cd /opt/vaultwarden
sudo systemctl start vaultwarden-backup.service
sudo nano compose.yaml
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs --tail=50 vaultwardenDalla versione 1.37.5, un valore di configurazione non valido impedisce l'avvio. Se il container si riavvia in continuazione, leggi i suoi log.
Eseguire il backup automaticamente
Lo script seguente crea una copia coerente del database con il comando integrato in Vaultwarden, poi archivia i file utili. La cache delle icone viene ignorata di proposito.
sudo nano /usr/local/sbin/vaultwarden-backup.sh#!/bin/sh
set -eu
umask 077
APP_DIR=/opt/vaultwarden
DEST=/var/backups/vaultwarden
STAMP=$(date +%F-%H%M)
WORK=$(mktemp -d)
trap 'rm -rf "$WORK"' EXIT
mkdir -p "$DEST" "$WORK/data"
cd "$APP_DIR"
docker compose exec -T vaultwarden /vaultwarden backup
DB=$(ls -1t vw-data/db_*.sqlite3 | head -n 1)
mv "$DB" "$WORK/data/db.sqlite3"
for item in vw-data/attachments vw-data/sends vw-data/config.json vw-data/rsa_key*; do
if [ -e "$item" ]; then
cp -a "$item" "$WORK/data/"
fi
done
cp -a compose.yaml .env "$WORK/"
tar -czf "$DEST/vaultwarden-$STAMP.tar.gz" -C "$WORK" .
find "$DEST" -name 'vaultwarden-*.tar.gz' -mtime +14 -deleteCrea il servizio /etc/systemd/system/vaultwarden-backup.service:
[Unit]
Description=Vaultwarden backup
Requires=docker.service
After=docker.service
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/vaultwarden-backup.shPoi il timer /etc/systemd/system/vaultwarden-backup.timer:
[Unit]
Description=Daily Vaultwarden backup
[Timer]
OnCalendar=*-*-* 03:15:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.targetAttiva tutto ed esegui un primo backup:
sudo chmod 700 /usr/local/sbin/vaultwarden-backup.sh
sudo systemctl daemon-reload
sudo systemctl enable --now vaultwarden-backup.timer
sudo systemctl start vaultwarden-backup.service
sudo ls -lh /var/backups/vaultwardenGli archivi restano 14 giorni sul server, il che non protegge dalla sua perdita. Copiali regolarmente altrove. Contengono tra l'altro .env e la chiave rsa_key.pem: cifrali se la destinazione non è sotto il tuo controllo, ad esempio con gpg --symmetric --cipher-algo AES256 archive.tar.gz.
| Elemento | Contenuto | Backup |
|---|---|---|
db.sqlite3 |
Account, casseforti cifrate, organizzazioni | Indispensabile |
attachments/ |
Allegati | Indispensabile |
rsa_key* |
Firma delle sessioni | Consigliato |
config.json |
Impostazioni salvate da /admin |
Consigliato |
sends/ |
File dei Send | Facoltativo |
icon_cache/ |
Icone dei siti | Inutile |
Testare il ripristino
Un backup ha valore solo se si riesce a ripristinarlo. Questo test avvia una copia isolata su un'altra porta, senza toccare l'istanza in servizio.
Estrai l'ultimo archivio e controlla il database:
sudo apt install -y sqlite3
sudo install -d -m 700 /root/vw-restore-test
sudo sh -c 'tar -xzf "$(ls -1t /var/backups/vaultwarden/*.tar.gz | head -n 1)" -C /root/vw-restore-test'
sudo sqlite3 /root/vw-restore-test/data/db.sqlite3 'PRAGMA integrity_check;'L'ultimo comando deve mostrare ok. Avvia poi la copia:
sudo docker run -d --rm --name vaultwarden-restore-test \
-e DOMAIN=http://localhost:8223 \
-e SIGNUPS_ALLOWED=false \
-v /root/vw-restore-test/data:/data \
-p 127.0.0.1:8223:80 \
vaultwarden/server:1.37.5
curl -fsS http://127.0.0.1:8223/aliveDal tuo computer, apri un tunnel SSH:
ssh -L 8223:127.0.0.1:8223 TUO_USER@IP_DEL_TUO_SERVERApri http://localhost:8223, accedi con il tuo account, poi verifica che una voce recente e un allegato si aprano correttamente. I browser considerano localhost un contesto sicuro, il che permette questo test senza certificato.
Chiudi il tunnel, poi elimina la copia:
sudo docker stop vaultwarden-restore-test
sudo rm -rf /root/vw-restore-testRipeti questo test dopo ogni modifica importante, e almeno una volta a trimestre.
Ripristinare in produzione
Sostituisci il nome dell'archivio con quello del backup scelto. Su un nuovo server, ripristina prima compose.yaml e .env in /opt/vaultwarden, dalla radice dell'archivio.
ARCHIVE=/var/backups/vaultwarden/vaultwarden-2026-11-18-0315.tar.gz
cd /opt/vaultwarden
sudo docker compose down
sudo mv vw-data "vw-data.old-$(date +%F)"
sudo install -d -m 700 /root/vw-restore
sudo tar -xzf "$ARCHIVE" -C /root/vw-restore
sudo cp -a /root/vw-restore/data /opt/vaultwarden/vw-data
sudo docker compose up -d
sudo rm -rf /root/vw-restoreAccedi e controlla i tuoi dati prima di eliminare la vecchia cartella vw-data.old-*.
In caso di problemi
The "argon2id" variable is not set
Docker Compose cerca di interpretare i $ dell'impronta. Deve trovarsi in .env, tra apici, e compose.yaml deve fare riferimento solo a ${VAULTWARDEN_ADMIN_TOKEN}. Verifica il risultato con sudo docker compose config: i $ vi compaiono raddoppiati, il che in quel punto è normale.
The configured Argon2 PHC in ADMIN_TOKEN is invalid
Il valore ricevuto da Vaultwarden non è corretto, spesso a causa di virgolette di troppo o di $ raddoppiati in .env. Controllalo:
sudo docker exec vaultwarden printenv ADMIN_TOKENL'output deve iniziare con $argon2id$, senza virgolette.
Invalid admin token, please try again.
Inserisci la password originale, non l'impronta. Se l'hai persa, generane una nuova ripartendo dal passo 2, poi ricrea il container con sudo docker compose up -d.
You are using a plain text ADMIN_TOKEN which is insecure
Vaultwarden legge ancora un token in chiaro. Il più delle volte, config.json ha la priorità su compose.yaml:
sudo grep admin_token /opt/vaultwarden/vw-data/config.jsonSostituisci allora il token dalla pagina /admin, nel campo Admin token/Argon2 PHC.
The admin panel is disabled
Nessun token è configurato. Controlla la riga ADMIN_TOKEN di compose.yaml e il contenuto di .env, poi ricrea il container.
/admin non risponde più
L'indirizzo IP del tuo computer è probabilmente cambiato. Correggi client_ip nel Caddyfile, poi convalida e ricarica Caddy.
Registration not allowed or user already exists
L'indirizzo inserito non corrisponde a un invito in sospeso, oppure l'account esiste già. Controlla l'indirizzo nella scheda Users di /admin. Se INVITATIONS_ALLOWED vale false, rimuovi questa riga per il tempo della registrazione.
Una variabile modificata non ha alcun effetto
Se vw-data/config.json esiste, sostituisce le variabili d'ambiente. Modifica l'impostazione da /admin, oppure rimuovi la chiave interessata dal file, con il container fermo.
La cassaforte non si apre o segnala che HTTPS è richiesto
Verifica di usare l'indirizzo in https:// e che DOMAIN contenga esattamente questo indirizzo. L'accesso tramite http://IP_DEL_TUO_SERVER non è supportato.
Errore 502 nel browser
Caddy non raggiunge il container:
cd /opt/vaultwarden
sudo docker compose ps
sudo docker compose logs --tail=50 vaultwarden
curl -fsS http://127.0.0.1:8222/alive