Install Vaultwarden with HTTPS and Backups
Host Vaultwarden on Debian or Ubuntu with Docker and Caddy: mandatory HTTPS, closed registrations, hashed admin token, updates, backups and a restore test.
On this page
Your values
Enter them once and the commands in this guide update.
This guide explains how to host Vaultwarden, a lightweight server compatible with the Bitwarden apps, on your own server. Vaultwarden runs in Docker and stays reachable only locally. Caddy publishes it over HTTPS.
By the end of the guide, your vault answers on https://vault.your-domain.com, nobody can sign up without an invitation, the admin token is stored in hashed form, and a daily backup exists whose restoration you have verified.
Order a Server
This guide applies to servers that you administer yourself:
Prerequisites
- A server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
- SSH access with a user that has
sudo - Docker Engine and Docker Compose, installed with the guide Install Docker Engine and Docker Compose
- Caddy, installed with the guide Caddy as a Reverse Proxy with Automatic HTTPS
- A domain name whose DNS zone you manage
- The public IP address of your computer, to restrict the admin page
Ports Used
| Port | Direction | Purpose | To open |
|---|---|---|---|
| 80/tcp | Inbound | Certificate validation and redirect to HTTPS | Yes |
| 443/tcp | Inbound | HTTPS access to the vault | Yes |
| 443/udp | Inbound | HTTP/3 | Recommended |
| 8222/tcp | Local | Vaultwarden, on 127.0.0.1 only |
No |
Step 1: Prepare the Domain and the Firewall
Create an A record for vault.your-domain.com pointing to YOUR_SERVER_IP. If your domain is managed at HostMyServers, follow the guide Create an A record.
If you use UFW, allow the web ports:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw statusIf UFW is not active yet, first follow the guide Configure the UFW firewall without losing SSH access.
Ports published by Docker bypass UFW rules. This is why the Compose file in step 3 publishes Vaultwarden on 127.0.0.1: it is then not reachable from the Internet, whatever your rules are.
Step 2: Create the Hashed Admin Token
The /admin page lets you manage the accounts of the instance. It is protected by a token, which you will keep only as an Argon2 hash.
Create the application folder, then generate a long, random admin password:
sudo mkdir -p /opt/vaultwarden
cd /opt/vaultwarden
openssl rand -base64 32Keep this password outside the vault, for example in another manager or on offline media. You will need it to sign in to /admin, including when the vault is unavailable.
Then compute its hash. The command asks for the password twice:
sudo docker run --rm -it vaultwarden/server:1.37.5 /vaultwarden hashIt prints a line of this form:
ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'Create the .env file:
sudo nano /opt/vaultwarden/.envPaste the hash into it, between single quotes and without doubling the $:
VAULTWARDEN_ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'Protect the file:
sudo chmod 600 /opt/vaultwarden/.envStep 3: Write the Compose File
sudo nano /opt/vaultwarden/compose.yamlservices:
vaultwarden:
image: vaultwarden/server:1.37.5
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: "https://vault.your-domain.com"
SIGNUPS_ALLOWED: "false"
ADMIN_TOKEN: "${VAULTWARDEN_ADMIN_TOKEN}"
volumes:
- ./vw-data:/data
ports:
- "127.0.0.1:8222:80"| Setting | Purpose |
|---|---|
image |
Exact version, which you change deliberately during updates |
DOMAIN |
Exact public address, with https:// |
SIGNUPS_ALLOWED |
false closes open registrations from the first start |
ADMIN_TOKEN |
Hash read from .env |
127.0.0.1:8222:80 |
Port reachable only from the server |
Check the result, then start the service:
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/aliveThe last command returns a quoted date. After about a minute, the status column of docker compose ps shows healthy.
Step 4: Publish the Vault with Caddy
Add this site to /etc/caddy/Caddyfile, or to a file in /etc/caddy/sites/ if you use imports:
vault.your-domain.com {
encode zstd gzip
@admin_denied {
path /admin /admin/*
not client_ip YOUR_IP
}
abort @admin_denied
reverse_proxy 127.0.0.1:8222 {
header_up X-Real-IP {remote_host}
}
}Only YOUR_IP can reach /admin: other connections are dropped without a response. If you access the Internet over IPv6, also add your IPv6 address after client_ip. The X-Real-IP header lets Vaultwarden log the real address of visitors.
Validate and apply the configuration:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyCheck the Result
curl -I http://vault.your-domain.com
curl -fsS https://vault.your-domain.com/alive
sudo ss -ltnp | grep 8222The first command must return a 308 redirect to HTTPS and the second a date. The third must show 127.0.0.1:8222 and no public address.
From your computer, http://YOUR_SERVER_IP:8222 must not respond. From a connection that does not use YOUR_IP, for example a phone on mobile data, https://vault.your-domain.com/admin must fail.
Step 5: Create Your Account by Invitation
Since registrations are closed, the first account goes through an invitation from the administrator.
- Open
https://vault.your-domain.com/adminfromYOUR_IP. - Enter the password generated in step 2, not its hash.
- In the Users tab, use the Invite User block with your email address.
- Without an SMTP server, no message is sent. Directly open
https://vault.your-domain.com/#/signupand sign up with the same address. - Choose a long, unique master password, then sign in.
Then enable a two-step login method in the account's security settings, and keep its recovery code outside the vault.
In the Bitwarden desktop, mobile or browser apps, choose a self-hosted server on the login screen, then enter https://vault.your-domain.com.
Step 6: Reduce the Attack Surface
Once your accounts are created, add this line to environment so that members of an organization can no longer invite new users:
INVITATIONS_ALLOWED: "false"If you no longer use the admin page, disable it by removing the ADMIN_TOKEN line from compose.yaml. Also check that no admin_token key exists in vw-data/config.json, if that file is present. Then apply the changes:
cd /opt/vaultwarden
sudo docker compose up -dTo invite someone later, temporarily restore ADMIN_TOKEN, remove INVITATIONS_ALLOWED, then recreate the container the same way.
Update Vaultwarden
Read the release notes, run a backup with the service created in the next section, then replace the version number 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 vaultwardenSince version 1.37.5, an invalid configuration value prevents startup. If the container restarts in a loop, read its logs.
Back Up Automatically
The following script creates a consistent copy of the database with the command built into Vaultwarden, then archives the useful files. The icon cache is deliberately ignored.
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 -deleteCreate the service /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.shThen the timer /etc/systemd/system/vaultwarden-backup.timer:
[Unit]
Description=Daily Vaultwarden backup
[Timer]
OnCalendar=*-*-* 03:15:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.targetEnable everything and run a first 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/vaultwardenArchives stay on the server for 14 days, which does not protect against losing it. Copy them elsewhere regularly. They contain, among other things, .env and the rsa_key.pem key: encrypt them if the destination is not under your control, for example with gpg --symmetric --cipher-algo AES256 archive.tar.gz.
| Item | Contents | Backup |
|---|---|---|
db.sqlite3 |
Accounts, encrypted vaults, organizations | Essential |
attachments/ |
Attachments | Essential |
rsa_key* |
Session signing | Recommended |
config.json |
Settings saved from /admin |
Recommended |
sends/ |
Sends files | Optional |
icon_cache/ |
Site icons | Not needed |
Test the Restoration
A backup is only worth something if it can be restored. This test starts an isolated copy on another port, without touching the running instance.
Extract the latest archive and check the 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;'The last command must print ok. Then start the copy:
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/aliveFrom your computer, open an SSH tunnel:
ssh -L 8223:127.0.0.1:8223 YOUR_USER@YOUR_SERVER_IPOpen http://localhost:8223, sign in with your account, then check that a recent entry and an attachment open correctly. Browsers treat localhost as a secure context, which allows this test without a certificate.
Close the tunnel, then delete the copy:
sudo docker stop vaultwarden-restore-test
sudo rm -rf /root/vw-restore-testRepeat this test after every significant change, and at least once a quarter.
Restore in Production
Replace the archive name with that of the backup you chose. On a new server, first restore compose.yaml and .env into /opt/vaultwarden, from the root of the archive.
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-restoreSign in and check your data before deleting the old vw-data.old-* folder.
Troubleshooting
The "argon2id" variable is not set
Docker Compose is trying to interpret the $ characters in the hash. It must be in .env, between single quotes, and compose.yaml must only reference ${VAULTWARDEN_ADMIN_TOKEN}. Check the result with sudo docker compose config: the $ characters appear doubled there, which is normal at that point.
The configured Argon2 PHC in ADMIN_TOKEN is invalid
The value received by Vaultwarden is incorrect, often because of extra quotes or doubled $ characters in .env. Check it:
sudo docker exec vaultwarden printenv ADMIN_TOKENThe output must start with $argon2id$, without quotes.
Invalid admin token, please try again.
Enter the original password, not the hash. If you lost it, generate a new one by repeating step 2, then recreate the container with sudo docker compose up -d.
You are using a plain text ADMIN_TOKEN which is insecure
Vaultwarden is still reading a plain-text token. Most often, config.json takes priority over compose.yaml:
sudo grep admin_token /opt/vaultwarden/vw-data/config.jsonThen replace the token from the /admin page, in the Admin token/Argon2 PHC field.
The admin panel is disabled
No token is configured. Check the ADMIN_TOKEN line in compose.yaml and the contents of .env, then recreate the container.
/admin No Longer Responds
Your computer's IP address has probably changed. Fix client_ip in the Caddyfile, then validate and reload Caddy.
Registration not allowed or user already exists
The address you entered does not match a pending invitation, or the account already exists. Check the address in the Users tab of /admin. If INVITATIONS_ALLOWED is false, remove that line for the duration of the registration.
A Changed Variable Has No Effect
If vw-data/config.json exists, it overrides the environment variables. Change the setting from /admin, or remove the relevant key from the file with the container stopped.
The Vault Does Not Open or Reports That HTTPS Is Required
Check that you are using the https:// address and that DOMAIN contains exactly that address. Access through http://YOUR_SERVER_IP is not supported.
502 Error in the Browser
Caddy cannot reach the container:
cd /opt/vaultwarden
sudo docker compose ps
sudo docker compose logs --tail=50 vaultwarden
curl -fsS http://127.0.0.1:8222/alive