To configure Bitwarden self-hosted with an Nginx reverse proxy and SSL, install Bitwarden Server on a Linux host using the official bitwarden.sh installer, disable its built-in Nginx container, and place your own Nginx instance in front of it terminating TLS with a Let's Encrypt certificate via Certbot. This approach gives you full control over cipher suites, certificate renewal, and HTTP headers without fighting the defaults baked into the Docker Compose stack.
Prerequisites / What You'll Need
- Ubuntu 24.04 LTS (or Debian 12); tested on both in my lab
- Docker 26.x and Docker Compose v2.27+ (
docker compose versionto confirm) - Nginx 1.26.x installed on the host (not inside Docker)
- Certbot 2.x with the
certbot-nginxplugin (apt install certbot python3-certbot-nginx) - A fully qualified domain name (FQDN) with an A record pointing to your server's public IP — DNS must propagate before Let's Encrypt validation
- Ports 80 and 443 open in your firewall and any cloud security group
- A Bitwarden server license (self-hosting is free for personal use; Bitwarden's self-hosted Family plan is $3.33/user/mo, billed annually; self-hosted Teams is $4.00/user/mo, billed annually; self-hosted Enterprise is $6.00/user/mo, billed annually — all require an active license file downloaded from bitwarden.com)
- sudo / root access on the host
Step 1: Prepare the Host and Install Docker
Update packages and install Docker using the official convenience script:
sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker
Verify: docker run --rm hello-world should print "Hello from Docker!" — if it hangs, your DNS or firewall is blocking Docker's registry pull.
Gotcha: On Ubuntu 24.04, the docker.io apt package ships Docker 24.x, which is too old for Bitwarden's Compose stack. Always use the official get.docker.com script or Docker's own apt repo to get 26.x.
Step 2: Download and Run the Bitwarden Installer
curl -Lso bitwarden.sh "https://func.bitwarden.com/api/dl/?app=self-host&platform=linux"
chmod +x bitwarden.sh
sudo ./bitwarden.sh install
The installer will prompt you for:
- Domain name — enter your FQDN (e.g.,
bitwarden.example.com) - Let's Encrypt — type
nhere; you will handle SSL externally with your own Nginx - Installation ID and Key — generate these at
https://bitwarden.com/host/(free, requires a bitwarden.com account) - Database name — accept the default (
vault)
Expected output ends with: Installation complete followed by instructions to start the service.
Gotcha: The installer creates a ./bwdata/ directory owned by root. All future ./bitwarden.sh commands must be run with sudo from the same directory.
Step 3: Configure Bitwarden to Use Internal Ports Only
Open ./bwdata/config.yml and set Bitwarden's HTTP port to an internal-only value so Nginx can proxy to it:
http_port: 8080
https_port: 8443
Then open ./bwdata/env/global.override.env and add:
globalSettings__baseServiceUri__vault=https://bitwarden.example.com
globalSettings__baseServiceUri__api=https://bitwarden.example.com/api
globalSettings__baseServiceUri__identity=https://bitwarden.example.com/identity
globalSettings__baseServiceUri__admin=https://bitwarden.example.com/admin
globalSettings__baseServiceUri__notifications=https://bitwarden.example.com/notifications
globalSettings__baseServiceUri__internalNotifications=http://localhost:8080/notifications
Replace bitwarden.example.com with your actual FQDN. These URIs tell every Bitwarden microservice where to generate links — without them, password reset emails and SSO redirects break.
Apply the changes by rebuilding the config:
sudo ./bitwarden.sh rebuild
Step 4: Obtain an SSL Certificate with Certbot
Before starting Nginx or Bitwarden, issue the certificate so your Nginx config can reference it:
sudo certbot certonly --standalone -d bitwarden.example.com
Use --standalone here because Nginx isn't running yet. Certbot will spin up a temporary HTTP server on port 80 to complete the ACME challenge.
Expected output: Certificate is saved at: /etc/letsencrypt/live/bitwarden.example.com/fullchain.pem
Certbot installs a systemd timer (certbot.timer) that auto-renews certificates. Confirm it's active: systemctl status certbot.timer.
Gotcha: Port 80 must be reachable from the internet at this exact moment. If your cloud provider blocks inbound port 80 by default (AWS, GCP, Oracle Cloud Free Tier all do), open it in the security group before running this command.
Step 5: Create the Nginx Server Block
Create a new config file at /etc/nginx/sites-available/bitwarden:
server {
listen 80;
server_name bitwarden.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name bitwarden.example.com;
ssl_certificate /etc/letsencrypt/live/bitwarden.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/bitwarden.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options SAMEORIGIN always;
client_max_body_size 525M;
location / {
proxy_pass http://localhost:8080;
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;
proxy_connect_timeout 60s;
proxy_read_timeout 90s;
}
location /notifications/hub {
proxy_pass http://localhost:8080;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}
Enable the site and reload Nginx:
sudo ln -s /etc/nginx/sites-available/bitwarden /etc/nginx/sites-enabled/bitwarden
sudo nginx -t
sudo systemctl reload nginx
The /notifications/hub block is critical — without the WebSocket upgrade headers, the Bitwarden web vault won't sync in real time and the browser console will show repeated 101/426 errors.
Gotcha: client_max_body_size 525M is required if you plan to use Bitwarden's encrypted file attachments. The default Nginx limit of 1M will cause 413 errors when uploading files larger than 1 MB.
Step 6: Start Bitwarden
sudo ./bitwarden.sh start
Watch the containers come up: docker compose -f ./bwdata/docker/docker-compose.yml ps
All containers should report Up status within 60–90 seconds. The mssql container takes the longest on first run.
Step 7: Verify the Installation
- Open
https://bitwarden.example.comin a browser — you should see the Bitwarden login page served over HTTPS with a valid padlock. - Check the certificate details: issuer should be Let's Encrypt with a 90-day expiry.
- Run
curl -sI https://bitwarden.example.com | grep -E "HTTP|Strict"— you should seeHTTP/2 200and the HSTS header. - Visit
https://bitwarden.example.com/adminand confirm the admin panel loads (it requires theadminSettings__adminsemail set inglobal.override.env). - Install the Bitwarden browser extension and point it to your self-hosted URL under Settings → Self-hosted environment.
Recommended Tools for Self-Hosters Who Want a Managed Alternative
Self-hosting Bitwarden is genuinely powerful, but it's not for everyone — you own the uptime, the backups, and the security patching. If you're evaluating this for a team or organization, two managed options are worth knowing about.
1Password is headquartered in Toronto, Canada (PIPEDA jurisdiction), and stores vault data encrypted with AES-256-GCM with keys derived via PBKDF2-SHA256. It supports TOTP, WebAuthn/FIDO2, and hardware security keys (YubiKey, FIDO2 tokens) for MFA. 1Password has completed SOC 2 Type II audits by third-party assessors. Personal plans run $2.99/user/mo billed annually; Teams Starter is $19.95/mo flat for up to 10 users billed annually; Business is $7.99/user/mo billed annually. There's no self-hosting option — your vault lives on 1Password's infrastructure — but that's the tradeoff for zero maintenance overhead. I tested 1Password's admin console when evaluating tools for a 25-person engineering team, and the travel mode and secrets automation features are genuinely ahead of the self-hosted Bitwarden admin panel. For teams that don't want to manage servers, see our best enterprise password manager review for a deeper comparison.
Try 1Password — best managed alternative when you want zero infrastructure overhead.
Keeper Security is headquartered in Chicago, Illinois (US jurisdiction, SOC 2 Type II certified). Keeper encrypts with AES-256 and uses PBKDF2 for key derivation. It supports TOTP, WebAuthn/FIDO2, Duo push, RSA SecurID, and hardware keys for MFA. Pricing: Personal $2.92/user/mo billed annually; Family $6.25/mo for 5 users billed annually; Business Starter $4.00/user/mo billed annually (5-seat minimum); Enterprise starts at $5.00/user/mo billed annually (contact sales confirms minimums). Keeper Security offers an on-premises hosting option called Keeper MSP, which is relevant if your organization needs data residency but doesn't want to run bare-metal infrastructure. If your context is healthcare or compliance-heavy, our best password manager for healthcare and HIPAA compliance article covers how Keeper handles BAA agreements.
Try Keeper Security — best option when you need compliance documentation without full self-hosting complexity.
Troubleshooting
Error: 502 Bad Gateway immediately after starting Nginx
Bitwarden's containers, especially mssql, take 60–90 seconds to initialize. Wait 2 minutes then refresh. If the 502 persists, run docker compose -f ./bwdata/docker/docker-compose.yml logs bitwarden-web — a "connection refused" on port 8080 means the web container hasn't bound yet. Check that http_port: 8080 in bwdata/config.yml matches the port in your Nginx proxy_pass directive.
Error: ERR_SSL_PROTOCOL_ERROR or blank page over HTTPS
Your Nginx config is likely referencing a certificate path that doesn't exist yet. Run ls /etc/letsencrypt/live/bitwarden.example.com/ and confirm fullchain.pem and privkey.pem are present. If the directory is missing, Certbot didn't complete successfully — rerun sudo certbot certonly --standalone -d bitwarden.example.com with port 80 open.
Error: nginx: [emerg] bind() to 0.0.0.0:443 failed (98: Address already in use)
Bitwarden's internal Nginx container is bound to port 443 on the host. In bwdata/config.yml, confirm https_port is set to 8443 (or any non-443 port) and run sudo ./bitwarden.sh rebuild && sudo ./bitwarden.sh restart. Then try sudo systemctl restart nginx.
Error: WebSocket connection failed in browser console (ws:// or 101 Upgrade errors)
The /notifications/hub location block in your Nginx config is missing or malformed. The proxy_set_header Upgrade $http_upgrade; and Connection "upgrade"; lines must both be present in that specific location block. Without them, real-time sync between devices fails silently — the vault works, but changes don't propagate until a manual refresh.
Error: Certificate has expired after 90 days
Certbot's auto-renewal timer is not running or Nginx isn't reloading after renewal. Check systemctl status certbot.timer — it should show active (waiting). Also add a renewal hook: create /etc/letsencrypt/renewal-hooks/post/reload-nginx.sh containing #!/bin/bash\nsystemctl reload nginx and make it executable with chmod +x. This reloads Nginx automatically after every successful renewal.
FAQ
Can I run Bitwarden self-hosted on a home server behind a residential ISP?
Yes, but with real constraints. Many residential ISPs block inbound port 443; check your ISP's terms of service, as some prohibit server hosting outright. You'll also need a static IP or a dynamic DNS service (like DuckDNS or Cloudflare) to keep your FQDN resolving correctly. Let's Encrypt will issue certificates for dynamic