Ospitare Vaultwarden su un VPS gestito: le vostre password sul vostro server

Che cosa fa Vaultwarden

Vaultwarden è un server di gestione delle password scritto in Rust, pensato per il self-hosting. Il suo wiki lo destina a privati, famiglie e organizzazioni di dimensioni contenute. La cassaforte web è inclusa nelle sue immagini Docker.

Implementa un'API compatibile con i client ufficiali Bitwarden, sul browser, sul computer e sul telefono. Il README precisa che il progetto non è associato a Bitwarden né a Bitwarden, Inc., e chiede di segnalargli direttamente qualsiasi problema, qualunque sia il client usato, anziché ai canali di assistenza ufficiali.

• La cassaforte: cassaforte personale, allegati, icone dei siti, chiave API personale e Send per trasmettere un testo o un file.
• Le organizzazioni: raccolte, condivisione delle password, ruoli, gruppi, registri degli eventi e criteri.
• L'autenticazione a due fattori: app di autenticazione, e-mail, FIDO2 WebAuthn, YubiKey e Duo.
• I rimedi: accesso di emergenza e recupero dell'account, quest'ultimo con l'e-mail configurata.
• L'amministrazione: una pagina /admin per le impostazioni, gli account e la diagnostica.

Il wiki elenca anche ciò che manca rispetto al server ufficiale, come l'accesso con passkey, i ruoli personalizzati e alcuni criteri aziendali. Precisa che le funzioni utili soprattutto alle grandi organizzazioni non sono una priorità del progetto: leggete quell'elenco se ne avete bisogno.

Che cosa consente la licenza AGPL-3.0

Vaultwarden è pubblicato con la GNU Affero General Public License, versione 3. Il testo afferma un'autorizzazione illimitata a eseguire il programma non modificato. Potete quindi usare l'immagine pubblicata dal progetto per la vostra azienda e il vostro team, senza alcuna licenza da acquistare.

L'articolo 13 aggiunge una condizione propria dell'AGPL: se modificate il programma, la vostra versione deve offrire a tutti coloro che la usano a distanza, tramite la rete, il modo di ottenerne gratuitamente il codice sorgente.

L'installazione con Docker Compose

Il README raccomanda le immagini dei container. Su un server in cui Docker è installato, create una cartella e collocatevi questo compose.yaml, tratto dal README e dal wiki:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

docker compose up -d

• Una porta pubblicata su 127.0.0.1: come nel README, Vaultwarden si raggiunge solo tramite il reverse proxy, installato sullo stesso server.
• DOMAIN: l'indirizzo di base della vostra istanza, in https. Il wiki avverte che senza di esso alcune funzioni non vanno, tra cui gli allegati e i link di invito.
• Una cartella vw-data su un disco locale: contiene tutti i dati. Il wiki segnala i problemi di SQLite su un volume CIFS o Samba, che non gestisce il blocco dei file.
• Il tag latest segue l'ultima versione pubblicata, e il wiki lo raccomanda per la maggior parte degli usi. Un tag come 1.37.5 fissa una versione, e latest-alpine dà lo stesso risultato su una base Alpine.

Il vostro nome di dominio punta al server con record A e AAAA, e i visitatori arrivano sulle porte 80 e 443. Finché il reverse proxy non è al suo posto, la cassaforte web resta inutilizzabile: passate direttamente alla sezione successiva.

Il progetto non indica né la memoria né il processore necessari; si presenta soltanto come una soluzione per i casi in cui il servizio ufficiale, esigente in termini di risorse, non è adatto. La taglia dipende dal numero di account e dal volume degli allegati. Su un VPS gestito, descrivetici il vostro uso e vi raccomandiamo la taglia adatta.

HTTPS e WebSocket: il reverse proxy

La cassaforte web si appoggia all'API Web Crypto, che i browser riservano ai contesti sicuri: il README indica che funziona solo con HTTPS attivo, e il wiki giudica HTTPS «pretty much required», cioè quasi obbligatorio. Il progetto raccomanda un reverse proxy davanti a Vaultwarden e sconsiglia il TLS integrato nel suo framework Rocket.

Scegliete un certificato riconosciuto, come quelli di Let's Encrypt, che il wiki raccomanda: con un certificato autofirmato, alcune piattaforme rifiutano la connessione. Il certificato deve includere la catena completa, altrimenti i dispositivi Android non si connettono.

Le notifiche WebSocket, attive per impostazione predefinita, avvisano il browser, l'applicazione desktop e l'estensione che una voce è cambiata. Passano dalla porta HTTP principale, e il proxy deve inoltrare le intestazioni Upgrade e Connection. Le app mobili usano le notifiche native del loro sistema, che si configurano a parte.

Con Caddy

Il wiki consiglia di guardare Caddy per primo se non avete preferenze: attiva HTTPS da solo, ottiene il certificato Let's Encrypt e supporta WebSocket. L'impostazione del wiki trasmette inoltre a Vaultwarden l'indirizzo reale del visitatore, per i suoi log:

vault.example.com {
  reverse_proxy 127.0.0.1:8000 {
    header_up X-Real-IP {remote_host}
  }
}

Con Nginx e Certbot

Questo blocco riprende l'esempio Nginx del wiki, ridotto alla porta 80 per lasciare a Certbot l'attivazione di HTTPS:

upstream vaultwarden-default {
  zone vaultwarden-default 64k;
  server 127.0.0.1:8000;
  keepalive 2;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      "";
}

server {
    listen 80;
    listen [::]:80;
    server_name vault.example.com;

    client_max_body_size 525M;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    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;

    location / {
      proxy_pass http://vaultwarden-default;
    }
}

Certbot installa poi il certificato e si occupa di rinnovarlo:

sudo certbot --nginx

Verificare WebSocket

Aprite gli strumenti per sviluppatori del browser, scheda rete, filtro WS, poi riconnettetevi alla cassaforte: una risposta 101 su /notifications/hub conferma la connessione. Altra prova del wiki: aprite la cassaforte in due browser, rinominate una voce in uno dei due e la modifica compare subito nell'altro.

Chiudere le registrazioni

Per impostazione predefinita, chiunque raggiunga la vostra istanza può crearvi un account. È utile per il vostro primo account, e il wiki raccomanda di chiudere subito dopo, per impedire a un malintenzionato di crearne uno.

1. Aprite il vostro indirizzo HTTPS e create il vostro account, poi collegate le vostre app a quell'indirizzo.
2. Portate SIGNUPS_ALLOWED a "false" in compose.yaml.
3. Rilanciate con docker compose up -d: una variabile d'ambiente è legata al container, che va ricreato perché venga presa in considerazione.

SIGNUPS_ALLOWED: "false"

• Gli inviti restano aperti dopo la chiusura: i proprietari e gli amministratori di un'organizzazione possono invitare nuove persone. INVITATIONS_ALLOWED impostato su "false" toglie questa possibilità, e il wiki lascia la scelta in base alla fiducia che accordate ai vostri utenti.
• Un elenco di domini: SIGNUPS_DOMAINS_WHITELIST limita la registrazione ad alcuni domini e-mail, e SIGNUPS_VERIFY impostato su true impone allora di verificare l'indirizzo. Quando questo elenco è definito, SIGNUPS_ALLOWED viene ignorata.
• La pagina di amministrazione permette di invitare chiunque, a prescindere da queste restrizioni.

Non appena salvate la configurazione dalla pagina di amministrazione, nella cartella dei dati nasce un file config.json che prevale sulle variabili d'ambiente. Le impostazioni interessate si cambiano allora da quella pagina: modificare compose.yaml non basta più.

La pagina di amministrazione e il suo token

La pagina /admin serve a configurare Vaultwarden, a vedere ed eliminare gli account e le organizzazioni, a togliere l'autenticazione a due fattori a un utente, a invitare e a leggere la diagnostica. Senza ADMIN_TOKEN, resta disattivata: se non vi serve, lasciatela così.

Il wiki raccomanda vivamente di attivare HTTPS prima di usare questa pagina. Il token fa da password, e può essere conservato in forma hashata, con argon2id, anziché in chiaro nella configurazione. Vaultwarden fornisce il comando: chiede la password due volte, poi restituisce una stringa PHC.

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

Inserite questa stringa in un file .env, accanto a compose.yaml, tra apici, poi richiamatela dal servizio:

VAULTWARDEN_ADMIN_TOKEN='$argon2id$...'

ADMIN_TOKEN: ${VAULTWARDEN_ADMIN_TOKEN}

Verificate il risultato, rilanciate, poi accedete a /admin con la vostra password, e non con la stringa PHC:

docker compose config
docker compose up -d

• La sessione dura 20 minuti per impostazione predefinita, regolabili con ADMIN_SESSION_LIFETIME. Una sessione aperta resta valida dopo un cambio di token. Per chiuderle tutte, eliminate rsa_key.pem dalla cartella dei dati e riavviate, il che disconnette anche gli utenti e annulla gli inviti in corso.
• Un accesso ridotto: gli esempi di proxy del wiki mostrano come aprire /admin solo ad alcuni indirizzi, o aggiungervi un'autenticazione HTTP.
• DISABLE_ADMIN_TOKEN toglie ogni controllo: è previsto per uno strato di autenticazione separato posto davanti, e il wiki lo riserva a chi sa quello che fa.

Ciò che protegge la cassaforte

La prima protezione è la password principale. I dati della cassaforte sono cifrati con chiavi personali o d'organizzazione: chi ottiene una copia del database o forza una sessione deve ancora violare questa password per leggerli. La sua solidità conta quindi più di ogni altra cosa. Una sessione di amministrazione, da sola, permette di eliminare un account o di togliere un'autenticazione a due fattori, senza dare accesso ai dati della cassaforte.

Prevedete lo smarrimento della password principale prima che accada: attivate l'accesso di emergenza del vostro account e, in un'organizzazione, il recupero dell'account, che richiede l'e-mail configurata.

Altre tre impostazioni, tratte dalla guida al rafforzamento

• Un account non root: l'immagine gira come root per impostazione predefinita, e il wiki ritiene preferibile darle il minimo dei diritti. Aggiungete user: 1000:1000 al servizio, con una cartella vw-data che appartenga a quell'utente.
• I log del proxy: la connessione WebSocket passa un token nell'indirizzo, in access_token. Se il vostro proxy conserva i log o li invia a un servizio esterno, il wiki raccomanda di mascherarvi questo valore.
• Il minimo di montaggi: montate la cartella dei dati e nient'altro, né la vostra cartella personale né /var/run/docker.sock.

SQLite, MariaDB o PostgreSQL

La stessa immagine supporta i tre database. Il wiki descrive SQLite come il più usato e il più testato, e lo raccomanda per la maggior parte degli usi, salvo una precisa necessità di un altro.

DATABASE_URL: "postgresql://user_name:user_password@db_host:5432/vaultwarden"

Create un database vuoto e il suo utente: all'avvio, Vaultwarden vi installa da solo il proprio schema. Una password che contiene caratteri speciali si scrive con la codifica percentuale in questo indirizzo.

Fate questa scelta prima di riempire la cassaforte. Il wiki descrive un passaggio da SQLite a PostgreSQL con pgloader, precisando che questa strada non è supportata dal progetto, che si percorre a vostro rischio e che inizia con un backup.

Le e-mail: la configurazione SMTP

Vaultwarden parte senza e-mail, ma diverse funzioni ne dipendono: gli inviti, la verifica degli indirizzi, l'invio dei suggerimenti della password, l'autenticazione a due fattori via e-mail e il recupero dell'account.

Su un VPS Simafri, l'invio passa da un relay SMTP autenticato, sulla porta 587: l'indirizzo di un account di posta che avete già, oppure Simafri Suite. La password si colloca nel file .env, come il token di amministrazione:

SMTP_HOST: "smtp.example.com"
SMTP_FROM: "vault@example.com"
SMTP_PORT: "587"
SMTP_SECURITY: "starttls"
SMTP_USERNAME: "vault@example.com"
SMTP_PASSWORD: ${VAULTWARDEN_SMTP_PASSWORD}

• I link di invito si costruiscono a partire da DOMAIN, e restano validi 5 giorni.
• Microsoft: il wiki indica che Hotmail, Outlook e Office 365 richiedono ormai OAuth2, che Vaultwarden non supporta ancora. L'errore da riconoscere è No compatible authentication mechanism was found.
• Gmail: prevedete una password per le app, secondo il wiki.
• La prova: la pagina di amministrazione invia un'e-mail di prova. Se vi cambiate un'impostazione SMTP, salvate prima, perché la prova usa le impostazioni salvate, e questo salvataggio crea config.json.

Se non parte nulla, il wiki propone di provare la connessione al relay dal server. Il comando restituisce 0 quando il relay risponde:

timeout 5 bash -c 'cat < /dev/null > /dev/tcp/smtp.example.com/587'; echo $?

I backup

Il README ricorda che il progetto non può essere ritenuto responsabile di una perdita di dati e raccomanda vivamente backup regolari. Il wiki li consiglia automatici, con almeno una copia altrove. Ecco che cosa contiene la cartella dei dati con SQLite:

Il database, a servizio attivo

Dalla versione 1.32.1, Vaultwarden sa salvare da solo il proprio database SQLite, senza fermare il servizio:

docker exec -it vaultwarden /vaultwarden backup

Il comando scrive un file db_AAAAMMGG_HHMMSS.sqlite3 accanto al database, in vw-data. L'immagine non contiene né sqlite3 né cron: il wiki consiglia di pianificare l'attività sul server, almeno una volta al giorno. Togliete allora -it, perché un'attività pianificata non ha un terminale, e fate pulizia tra questi file, che si accumulano.

L'intera cartella, a servizio fermo

Quando il database non è in uso, basta una semplice copia di tutti i suoi file. È il metodo a servizio fermo che il wiki dà come esempio per Docker, e porta con sé anche gli allegati:

docker compose down
tar -czf vaultwarden-$(date +%F).tar.gz vw-data
docker compose up -d

Il wiki ritiene utile uno strato di cifratura, soprattutto quando il backup contiene il token di amministrazione e le credenziali SMTP, e cita rclone, restic e rustic per inviare le copie lontano. Con MariaDB o PostgreSQL, aggiungete un'esportazione del database alla cartella vw-data.

Il wiki chiede di non affidarsi ai soli snapshot del disco, più delicati da ripristinare. Conservate quindi queste copie proprie dell'applicazione: collocate sul disco del server, rientrano anche nei suoi backup notturni.

Ripristinare

1. Fermate Vaultwarden.
2. Sostituite ogni file o cartella di vw-data con la sua versione salvata.
3. Se il database proviene da /vaultwarden backup, chiamatelo db.sqlite3 ed eliminate prima qualsiasi file db.sqlite3-wal esistente: un journal che non corrisponde può corrompere il database. Se proviene da una copia diretta, ripristinate insieme db.sqlite3 e il suo db.sqlite3-wal.
4. Rilanciate, poi verificate di riuscire ad aprire la cassaforte.

Il wiki consiglia di ripetere questo esercizio di tanto in tanto, conservando una copia dei dati in uso: è così che verificate che un backup funzioni.

Gli aggiornamenti

Il wiki fornisce due comandi, dalla cartella del compose.yaml. La cartella dei dati resta al suo posto:

docker compose pull
docker compose up -d

Questi aggiornamenti contano più che altrove. Le app mobili e le estensioni del browser si aggiornano da sole, e il wiki avverte che uno scarto di versione con il server può provocare guasti improvvisi. La cassaforte web, inclusa nell'immagine, resta sempre allineata al proprio server.

Il progetto non ha un calendario delle versioni: seguite le sue note di rilascio e lanciate un backup subito prima di ogni aggiornamento. Alcune contengono correzioni di sicurezza, come la 1.37.5 del 1° novembre 2026, le cui note raccomandano di aggiornare al più presto. Le stesse note avvertono inoltre che, dalla 1.37.5, un valore di configurazione non valido impedisce l'avvio di Vaultwarden: rileggete il vostro file di ambiente prima di aggiornare. La pagina di diagnostica di /admin indica se esiste una versione più recente.

Chi fa che cosa su un VPS gestito

Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Vaultwarden resta il vostro software, con le sue impostazioni e i suoi dati.

Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.