Note: Vaultwarden was formerly known as bitwarden_rs.
This is not a common configuration, and not recommended compared to running on a VPS or similar, but sometimes an organization only has access to a shared hosting service and only wants to use that. This repo contains an example of how that can be accomplished on DreamHost specifically, though with minor changes, it can probably be applied to many other shared hosting services.
Shared hosting is generally geared towards running PHP apps. Many hosts also support Ruby, Python, and/or Node.js apps, but there is generally no direct support for reverse proxying to an arbitrary backend service. The example provided here uses a small Python WSGI app to proxy to the Vaultwarden backend.
This document assumes basic familiarity with Linux (knowing how to SSH into a host, copy files to the host, make and change into directories, etc.).
In the DreamHost admin panel, create a new subdomain (e.g., bw.example.org
)
and enable HTTPS and Passenger.
For more details, see How do I enable Passenger on my domain?
SSH into your subdomain account. From your home directory, run
$ git clone https://github.com/jjlin/vaultwarden-shared-hosting.git vaultwarden
This makes a copy of this repo in a directory called vaultwarden
. You can use
a different directory name if you prefer, but you'll have to modify the value
of VAULTWARDEN_HOME
in passenger_wsgi.py
accordingly.
If the git
command above isn't available for some reason, you can also just
download a zip file of the repo and extract it:
$ wget https://github.com/jjlin/vaultwarden-shared-hosting/archive/main.zip
$ unzip main.zip
$ mv vaultwarden-shared-hosting-main vaultwarden
Stay logged in via SSH, as the rest of the steps below will need SSH as well.
Dreamhost defaults to python2, but this script uses python3.
So note the use of pip3
and some sys.executable
magic at the top
of the passenger_wsgy.py file.
Run this command:
$ pip3 install WebOb WSGIProxy2
The output should look like:
Collecting WebOb
Using cached https://files.pythonhosted.org/packages/18/3c/de37900faff3c95c7d55dd557aa71bd77477950048983dcd4b53f96fde40/WebOb-1.8.6-py2.py3-none-any.whl
Collecting WSGIProxy2
Using cached https://files.pythonhosted.org/packages/2d/a5/3afac2542081b890de83e0089a0057cfb7dc9ad877ccc5594e6c6e1976b8/WSGIProxy2-0.4.6-py3-none-any.whl
Collecting six (from WSGIProxy2)
Using cached https://files.pythonhosted.org/packages/65/eb/1f97cb97bfc2390a276969c6fae16075da282f5058082d4cb10c6c5c1dba/six-1.14.0-py2.py3-none-any.whl
Installing collected packages: WebOb, six, WSGIProxy2
Successfully installed WSGIProxy2-0.4.6 WebOb-1.8.6 six-1.14.0
Copy the passenger_wsgi.py
file in this repo into your
/home/<user>/<subdomain>
directory. NOT the public
folder within the subdomain.
Note that Passenger starts a persistent Python process that loads the
passenger_wsgi.py
script. If you need to modify the script, you'll need to
kill the Python process (e.g., pkill python3
) to force it to reload the
modified script. Dreamhost suggests touch restart.txt
as a way to request that
passenger restart the wsgi script, but I have found that to be unreliable --
better to manually kill the script yourself.
For more details, see Passenger and Python WSGI.
If you visit your subdomain now (e.g., https://bw.example.org
), you should
see a 502 Bad Gateway
message. This is because the Vaultwarden backend is
not yet running.
Make sure you're in the vaultwarden
directory for the steps below.
Run this command:
$ ./docker-image-extract vaultwarden/server:alpine
The output should look like the following (the layer IDs will likely all be different) :
Getting multi-arch manifest list...
Platform linux/amd64 resolved to 'sha256:deec30b3985444c8efc42338717a9b64f3185e1f3e149a7137afc98ebeb815e1'...
Getting API token...
Getting image manifest for vaultwarden/server:alpine...
Fetching and extracting layer c158987b05517b6f2c5913f3acef1f2182a32345a304fe357e3ace5fadcad715...
Fetching and extracting layer d58d1c0e0c7df3aac19cadde4e0910a04ab277976c90ab6973bd6018edd02588...
Fetching and extracting layer 630c69c2a5502c32eace11f461d2db3308aaa800b2f1207f5e194195d44b765b...
Fetching and extracting layer c655444a35c3827719e17f549f5421b211193d3bab3f1ff430ec3154651cecd4...
Fetching and extracting layer a940b1feefa501c534ededd3e6dee86cd6827fc5c100c798e07d33c4a0012097...
Fetching and extracting layer 857810bada4c372d6aa453ba9f7c0f1a029ab1a32bb20eb35790d8df76a61df2...
Image contents extracted into ./output.
This pulls the latest Vaultwarden server Docker image and extracts its files
into a directory called output
. Move the server binary and web vault files
into your vaultwarden
directory. The other files in output
aren't needed,
so you can delete the directory afterwards.
$ mv output/vaultwarden output/web-vault .
$ rm -rf output
For purposes of this tutorial, start by copying config.json.template
to
config.json
and editing it as described below.
$ cp data/config.json.template data/config.json
$ # Now edit data/config.json with your preferred editor.
The initial config.json
looks like
{
"domain": "https://bw.example.org",
"admin_token": "<output of 'vaultwarden hash'>"
}
Do the following:
- Change the value of
domain
to the subdomain URL you selected. - Run
vaultwarden hash
and follow the prompts to generate a hashed master password. - Set
admin_token
to the string returned. - You'll use the password enterred to generate the hash to log into the /admin page to perform further configuration.
Passenger calls passenger_wsgi.py
automatically for all requests to the subdomain.
passenger_wsgi.py
transparently proxies all requests to the vaultwarden backend
and then then directly returns the output. If an attempt to proxy a request to
the backend returns a 502 error, then passenger_wsgi.py
will pkill vaultwarden
,
and then run the vaultwarden
executable in the background, with logs saved
in vaultwarden.log
. Then it will retry proxying the request. So vaultwarden
should never need to be manually started, restarted, or monitored.
After moving vaultwarden
and web-vault
into the cwd, visiting
https://bw.example.org should show the Bitwarden web
vault interface, and https://bw.example.org/admin should lead to the admin
page (after you input the admin password).
You can run pkill vaultwarden; pkill python3
to restart the backend server if needed.
You'll probably want to lock down your settings a bit, and set up email service. From the admin page, you should review at least the following settings:
- General settings
Allow new signups
-- you might want to disable this so random users can't create accounts on your server.Require email verification on signups
- SMTP Email Settings
- You can use your hosting service's SMTP server, in which case you should consult their documentation (e.g., Email client protocols and port numbers for DreamHost).
- Your hosting service's SMTP service may not deliver email promptly. In that case, you might consider using an external SMTP service like SendGrid or MailJet. These both provide 100-200 outgoing emails per day on their free tier, which is probably enough for small organizations.
There are a lot more things that can be configured in Vaultwarden, and a detailed treatment is beyond the scope of this tutorial. For more details, the best place to start is https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview.
From time to time, you may want to upgrade Vaultwarden to access bug fixes
or new features. To do this, change into the vaultwarden
directory, stop
the Vaultwarden server, and delete the existing vaultwarden and web vault
files:
$ pkill vaultwarden
$ pkill python3
$ rm -rf vaultwarden web-vault
Then repeat the steps from Download the Vaultwarden server and web vault and Run the Vaultwarden backend server.
This configuration supports WebSocket notifications.
As of vaultwarden 1.29.0, and tested working (getting 101
on the websocket
request to /notification/hub) on a shared dreamhost on 2023-07-26.