How to Deploy Bitwarden on a VPS

copysudo ufw status verbose

copydig +short vault.example.com

#Get an installation ID and key

This is the step that surprises people, so it's worth its own heading: the official self-hosted server requires a free installation ID and installation key, which you request from bitwarden.com/host with an email address. They're free, they take a minute, and the installer will sit there and wait for them — so fetch them before you start rather than in the middle of a prompt.

They aren't a licence. They identify your instance to Bitwarden for things like push-notification relay and update checks. You'll also be asked to pick a region for that association. Keep both values somewhere safe; they end up in your configuration and you'll want them again if you ever rebuild the box from scratch.

#Install Bitwarden

Everything happens through a single script, run as your non-root user in a directory that will hold the whole deployment. Create it, then fetch the installer:

copymkdir ~/bitwarden && cd ~/bitwarden

copy# Official Bitwarden self-host installer
curl -Lso bitwarden.sh "https://func.bitwarden.com/api/dl/?app=self-host&platform=linux"
chmod +x bitwarden.sh
./bitwarden.sh install   # prompts for domain + install id/key

The install is interactive. It asks, in order, for:

• the domain name for your instance (vault.example.com — no scheme, no path)
• whether to use Let's Encrypt for SSL, and an email address if you say yes
• the database name to create
• your installation ID and installation key
• a region, and if you declined Let's Encrypt, which certificate route you want

When it finishes, you have a bwdata/ directory next to the script. Two files in there are the ones you'll actually touch:

• ./bwdata/config.yml — the deployment's structural configuration, including the ports and certificate paths its bundled nginx uses.
• ./bwdata/env/global.override.env — the runtime environment: SMTP settings, the admin portal allowlist, and the registration switch.

Start the stack:

copy./bitwarden.sh start

The first start pulls a set of images and initializes the database, so give it a few minutes before you judge it. Watch what comes up with docker ps — you should see the web vault, api, identity, admin, events, nginx, and mssql containers all in a running state. If one is restarting in a loop, jump to Troubleshooting.

#HTTPS + domain (mandatory)

The Bitwarden clients refuse to talk to a server that isn't served over HTTPS. That's a hard requirement in the official apps and extensions, not a warning you can click past. A self-hosted instance on plain http:// is, for practical purposes, an instance no real client will connect to. Bitwarden's own documentation is blunt about it: if you choose the no-certificate option, you must front the installation with a proxy that serves it over HTTPS.

You have two sane routes, and the right one depends on whether this box does anything else.

Route A — let the installer handle it (recommended for a dedicated box). Answer yes to the Let's Encrypt prompt during ./bitwarden.sh install. Bitwarden's bundled nginx obtains the certificate, serves 443, and renews on its own; there's a ./bitwarden.sh renewcert subcommand if you ever need to force it. Nothing else to configure, nothing else to run. If this VPS exists to host the vault and nothing else, take this route and skip to First-run setup.

Route B — put Caddy in front (use this if the box serves anything else). Because Bitwarden's own nginx wants 80 and 443, you cannot also run a reverse proxy on those ports without moving Bitwarden's out of the way first. To do that: answer no to the certificate prompt during install, then edit ./bwdata/config.yml and change the HTTP and HTTPS port entries to unused high ports (say 8081 and 8443). Apply the change with:

copy./bitwarden.sh rebuild
./bitwarden.sh restart

rebuild regenerates the deployment's generated config from config.yml; restart brings the containers back on the new ports. Then follow Automatic HTTPS with Caddy and give Caddy a single block:

vault.example.com {
    reverse_proxy 127.0.0.1:8081
}

Caddy terminates TLS on 443, fetches and renews the certificate itself, and forwards to Bitwarden's nginx on the loopback port. One wiring detail: if you run Caddy as a container rather than on the host, 127.0.0.1 inside that container is the container's own loopback, not the host's — give the Caddy service network_mode: host, or proxy to the host's LAN address instead.

Whichever route you take, the domain you configured must match how clients reach you, https:// and all. A mismatch between the installed domain and the URL people type produces login failures that look like server errors.

#Configure email (SMTP)

Treat this as required, not optional. On a self-hosted instance, email carries: user invitations, email-address verification, new-device login alerts, and — the one that catches everybody — the login link for the System Administrator Portal at /admin, which authenticates by emailing a passwordless link. No working SMTP means no admin portal.

Open ./bwdata/env/global.override.env and fill in the mail block plus the admin allowlist:

Open the override file in your editor:

nano ~/bitwarden/bwdata/env/global.override.env

globalSettings__mail__smtp__host=smtp.example.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
globalSettings__mail__smtp__username=apikey-or-user
globalSettings__mail__smtp__password=your-smtp-password
globalSettings__mail__replyToEmail=vault@example.com
adminSettings__admins=you@example.com

Two details worth knowing. globalSettings__mail__smtp__ssl is a boolean where true means implicit SSL and false means STARTTLS — for the common port 587 submission setup, false is what you want. And dollar signs are not supported in the SMTP password value, so if your provider handed you a password containing one, regenerate it rather than fighting the escaping.

adminSettings__admins is a comma-separated list of the email addresses allowed into the admin portal. Keep it to real administrators; anyone on that list can manage users and licensing for the whole instance.

Apply the changes:

copy./bitwarden.sh restart

Any SMTP relay works — a transactional email provider is the least painful option, since a VPS sending mail directly will mostly land in spam folders.

#First-run setup

Open https://vault.example.com in a browser. You should get the Bitwarden web vault with a valid certificate.

Create your own account now. Register through the normal sign-up flow, verify the email (this is your first real test that SMTP works), and log in. Then create an organization if more than one person will use this instance — on the official server, sharing, groups, and collections all hang off an organization rather than off individual accounts, which is a meaningful difference from Vaultwarden's model.

Then close public registration. An internet-facing vault where anyone who finds the URL can create an account is the classic serious mistake. Once your own account exists, add the switch to global.override.env:

globalSettings__disableUserRegistration=true

and restart:

copy./bitwarden.sh restart

Existing users are unaffected and you can still bring people in by inviting them into your organization — which is the better flow anyway, since it puts them under your policies from the start. Verify by loading the site in a private window: the registration page should refuse to create an account.

Finally, connect a real client. In the browser extension, desktop, or mobile app, open the settings on the login screen (usually a gear icon) and set the self-hosted server URL to https://vault.example.com before logging in. From then on that client syncs through your server.

#Hardening

The two big ones are already done — HTTPS in front, registration closed. A few more habits make this genuinely solid:

• Keep the admin allowlist tight. adminSettings__admins is the portal's entire access control, and the portal can manage every user on the instance. One or two addresses, both of which you control.

• Turn on two-step login for every account, starting with yours. The self-hosted server supports authenticator apps out of the box; the organization policy that requires two-step login for members is worth enabling as soon as you have more than one user.

• Don't skip host hardening. SSH keys only, no password authentication, ufw limited to 22/80/443, unattended security updates on. The application is only as safe as the box under it, and this box holds every password your team has.

• Keep it patched. Bitwarden ships releases regularly, security fixes included. The update path is one command (below) — the failure mode is letting it drift for a year, then discovering the jump is bigger than you wanted on the day you needed it to be small.

#Backups

Bitwarden's documentation names four paths inside bwdata as the ones a backup must capture:

• ./bwdata/env — environment variables, including the database and certificate passwords
• ./bwdata/core/attachments — vault item attachments
• ./bwdata/mssql/data — the database itself
• ./bwdata/core/aspnet-dataprotection — framework-level data protection keys, covering authentication tokens and some database columns

That last one is the one people miss. Restore the database without aspnet-dataprotection and you get a server that starts fine and then can't decrypt parts of its own data — the worst kind of broken, because it looks like it worked. For a disaster-recovery plan you actually trust, back up the entire bwdata directory; it's the vendor's own advice and it removes the guesswork.

The stack also writes automatic nightly database backups into ./bwdata/mssql/backups and keeps them for a month. Those are useful for point-in-time recovery on the same box, and useless if the box is gone — they're a convenience, not a backup strategy.

The safe way to take a copy is with the stack stopped, so the database files are consistent:

copycd ~/bitwarden
./bitwarden.sh stop
sudo tar czf - bwdata \
  | gpg --symmetric --cipher-algo AES256 \
      -o "bitwarden-$(date +%F).tar.gz.gpg"
./bitwarden.sh start

Encrypt it, always — this archive is your vault, so a backup that leaks is as bad as a database that leaks. Then copy the .gpg file off the server: object storage, another machine, anywhere that survives this VPS dying. A backup that only lives on the same box dies with the box.

Automate it on a schedule, and — the part everyone skips — test a restore at least once. Stand up a throwaway server, drop the restored bwdata in place, run ./bitwarden.sh start, and confirm you can log in. If the brief stop-and-start window is a problem for you, snapshot the whole VPS volume on your provider's schedule as well; on a vault this is belt and braces, not paranoia.

#Upgrades

Upgrading is two commands, in this order, because the script updates itself first:

copycd ~/bitwarden
./bitwarden.sh updateself
./bitwarden.sh update

updateself fetches a newer bitwarden.sh; update pulls the new images, applies any database migrations, and recreates the containers against your unchanged data. There's also ./bitwarden.sh updatedb if you ever need to run migrations alone, and ./bitwarden.sh rebuild to regenerate the deployment config after editing config.yml.

Run a backup first, every time. Then read the release notes before a big jump — the stack is stable, but it's a real database migration, and a snapshot you can roll back to costs you nothing on the days it turns out you didn't need it.

#Troubleshooting

The client says "Cannot reach server" or refuses the URL. Almost always HTTPS. Load https://vault.example.com in a browser and confirm the certificate is valid — the apps reject self-signed and expired certificates even where a browser lets you click through. Then check that DNS resolves to this box (dig +short vault.example.com), that 80 and 443 are open in ufw and in any cloud firewall your provider puts in front of it, and that the server URL in the client matches the domain you gave the installer exactly.

Containers keep restarting, or the stack never becomes healthy. Check memory first: free -m. SQL Server is the usual culprit on an undersized box, and its logs will say so — docker logs bitwarden-mssql (the container names are prefixed bitwarden-). If memory is fine, docker ps -a will show which service is cycling, and its log is the next place to look.

The admin portal at /admin won't let me in. It authenticates by emailing a login link, so this is nearly always SMTP. Confirm your address is in adminSettings__admins, confirm the mail block in global.override.env is correct, and remember that a $ in the SMTP password is not supported. Restart after any edit — the file is only read at startup.

Invitations and verification emails never arrive. Same root cause. Check the api container's logs for send failures, verify the credentials against your provider, and check whether your provider requires the replyToEmail address to be a verified sender.

The certificate didn't renew. If Bitwarden's bundled nginx is managing it, ./bitwarden.sh renewcert forces the attempt and prints the reason if it fails — usually port 80 being blocked or the A record having moved. If Caddy is in front, renewal is Caddy's job; check its logs instead.

#Verification + next steps

You're done when you can: load https://vault.example.com with a valid certificate, create and verify an account (proving SMTP works), log in from a real Bitwarden client pointed at your server URL, confirm public registration is closed in a private window, reach the admin portal via an emailed link, and produce an encrypted, off-box backup of bwdata that you have restored at least once.

After that it's routine: updateself and update on a schedule you choose, backups flowing off the box, and a supported password manager running on infrastructure that answers to you. The thing underneath it that matters most is a host with dependable uptime and real volume snapshots — this is your credentials. A Hetzner instance in the 4 GB tier is the value pick; DigitalOcean is the easy button if you want snapshots and monitoring in the same dashboard; Kamatera is the one to reach for when you want to size CPU and RAM independently. See Best VPS for self-hosting for the ranked picks.