Unified Deployment beta
note
This solution is in beta and intended for personal use. Business plans should use the officially-supported, standard deployment option.
While the Bitwarden unified self-hosted deployment is in beta, those installing unified should not setup automatic upgrade procedures that pull the latest images available. Bitwarden recommends allowing some time for stabilization of a release before upgrading.
This article will walk you through installing and launching the Bitwarden unified self-hosted deployment. Use this deployment method to:
Simplify configuration and optimize resource usage (CPU, memory) by deploying Bitwarden with a single Docker image.
Utilize different database solutions such as MSSQL, PostgreSQL, SQLite, and MySQL/MariaDB.
Run on ARM architecture for alternative systems such as Raspberry Pi and NAS servers.
Bitwarden unified deployment requires:
At least 200 MB RAM
Storage 1GB
Docker Engine 26+
The unified deployment will run on your machine using a Docker container. The unified deployment can be run with any Docker edition or plan. Evaluate which edition is best for your installation.
Install Docker on your machine before proceeding with installation. Refer to the following Docker documentation for help:
The unified deployment can be run using the docker run
command (see here) or using Docker Compose (see here). In either case, you'll need to specify environment variables for the container.
Running the unified deployment will require environment variables to be set for the container. Environment variables can be specified by creating a settings.env
file, which you can find an example of in our GitHub repository, or by using the --env
flag if you're using the docker run
method. Several optional variables are available for use for a more personalized unified deployment experience. Additional details on these variables can be located here.
At a minimum, set values for the variables that fall under the # Required Settings #
section of the example .env
file:
Variable | Description |
---|---|
BW_DOMAIN | Replace |
BW_DB_PROVIDER | The database provider you will be using for your Bitwarden server. Available options are |
BW_DB_SERVER | The name of the server on which your database is running. |
BW_DB_DATABASE | The name of your Bitwarden database. |
BW_DB_USERNAME | The username for accessing the Bitwarden database. |
BW_DB_PASSWORD | The password for accessing the Bitwarden database. |
BW_DB_FILE | Only required for |
BW_INSTALLATION_ID | A valid installation ID generated from https://bitwarden.com/host/. |
BW_INSTALLATION_KEY | A valid installation key generated from https://bitwarden.com/host/. |
note
Unlike the Bitwarden standard deployment, unified deployment does not come out-of-the-box with a database. You can use an existing database, or create a new one as documented in this example, and in both cases you must enter valid information in the BW_DB_...
variables documented here.
Using non-MSSQL database providers may result in performance issues, as support for these platforms continues to be worked on throughout the beta. Please use this issue template to report anything related to your Bitwarden unified deployment and check out this page to track known issues or join the discussion.
The unified deployment can be run with the docker run
command, as in the following example:
Bashdocker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env bitwarden/self-host:beta
The command featured above has several required options for the docker run
command, including:
Name, shorthand | Description |
---|---|
--detach , -d | Run the container in the background and print container ID. |
--name | Provide a name for the container. |
--volume , -v | Bind mount a volume. At a minimum, mount |
--publish , -p | Map container ports to the host. The example shows the port |
--env-file | Path of the file to read environment variables from. Alternatively, use the |
Once you run the command, verify that the container is running and healthy with:
Bashdocker ps
Congratulations! Your unified deployment is now up and running at https://your.domain.com
. Visit the web vault in your browser to confirm that it's working. You may now register a new account and log in.
Running the unified deployment with Docker Compose will require Docker Compose version 1.24+. To run the unified deployment with Docker compose, create a docker-compose.yml
file, for example:
Bash---
version: "3.8"
services:
bitwarden:
depends_on:
- db
env_file:
- settings.env
image: bitwarden/self-host:beta
restart: always
ports:
- "80:8080"
volumes:
- bitwarden:/etc/bitwarden
db:
environment:
MARIADB_USER: "bitwarden"
MARIADB_PASSWORD: "super_strong_password"
MARIADB_DATABASE: "bitwarden_vault"
MARIADB_RANDOM_ROOT_PASSWORD: "true"
image: mariadb:10
restart: always
volumes:
- data:/var/lib/mysql
volumes:
bitwarden:
data:
In the docker-compose.yml
file, make any desired configurations including:
Mapping volumes for logs and Bitwarden data.
Mapping ports.
Configuring a database image.
ª
ª
Only setup a database in docker-compose.yml
, as in the above example, if you want to create a new database server to use with Bitwarden. Sample configurations for MySQL, MSSQL, and PostgreSQL are included in our example file.
Once your docker-compose.yml
and settings.env
file are created, start your unified server by running:
Bashdocker compose up -d
Verify that all containers are running correctly:
Bashdocker ps
Congratulations! Your unified deployment is now up and running at https://your.domain.com
. Visit the web vault in your browser to confirm that it's working. You may now register a new account and log in.
To update your unified deployment:
Stop the running Docker container:
Bashdocker stop bitwarden
Remove the Docker container:
Bashdocker rm bitwarden
Run the following command to pull the most recent Bitwarden unified image:
Bashdocker pull bitwarden/self-host:beta
Run the Docker container again:
Bashdocker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env bitwarden/self-host:beta
Stop the running Docker container:
Bashdocker compose down
Run the following command to pull the most recent Bitwarden unified image:
Bashdocker compose pull
Recreate any containers that need to be updated:
Bashdocker compose up -d
Verify that the containers are running:
Bashdocker compose ps
The unified deployment will operate by default without several of the standard Bitwarden services. This allows for increased customization and optimization of your unified deployment. Configure these services, and more optional settings, by editing various environment variables.
note
Whenever you change an environment variable, the Docker container will need to be recreated. Learn more here.
Webserver ports
Variable | Description |
---|---|
BW_PORT_HTTP | Change the port used for HTTP traffic. By default, |
BW_PORT_HTTPS | Change the port used for HTTPS traffic. By default, |
SSL
Use these values to change certificate settings.
Variable | Description |
---|---|
BW_ENABLE_SSL | Use SSL/TLS. |
BW_SSL_CERT | The name of your SSL certificate file. The file must be located in the |
BW_SSL_KEY | The name of your SSL key file. The file must be located in the |
BW_ENABLE_SSL_CA | Use SSL with certificate authority(CA) backed service. |
BW_SSL_CA_CERT | The name of your SSL CA certificate. The file must be located in the |
BW_ENABLE_SSL_DH | Use SSL with Diffie-Hellman key exchange. |
BW_SSL_DH_CERT | The name of your Diffie-Hellman parameters file. The file must be located in the |
BW_SSL_PROTOCOLS | SSL version used by NGINX. Leave empty for recommended default. Learn more. |
BW_SSL_CIPHERS | SSL ciphersuites used by NGINX. Leave empty for recommended default. Learn more. |
note
If you are using an existing SSL certificate, you will have to enable the appropriate SSL options in settings.env
. SSL files must be stored in /etc/bitwarden
, which can be referenced in the the docker-compose.yml
file. These files must match the names configured in settings.env
.
The default behavior is to generate a self-signed certificate if SSL is enabled and no existing certificate files are in the expected location (/etc/bitwarden
).
Services
Additional services can be enabled or disabled for specific use cases, such as enterprise or team needs, by changing the following values:
Variable | Description |
---|---|
BW_ENABLE_ADMIN | Do not disable this service. Learn more about Admin panel capabilities here. Default |
BW_ENABLE_API | Do not disable this service. Default |
BW_ENABLE_EVENTS | Enable or disable Bitwarden events logs for teams and enterprise event monitoring. Default |
BW_ENABLE_ICONS | Enable or disable Bitwarden brand icons that are set with the login item URI's. Learn more here. Default |
BW_ENABLE_IDENTITY | Do not disable this service. Default |
BW_ENABLE_NOTIFICATIONS | Enable or disable notification services for receiving push notifications to mobile devices, using login with device, mobile vault sync, and more. Default |
BW_ENABLE_SCIM | Enable or disable SCIM for Enterprise organizations. Default |
BW_ENABLE_SSO | Enable or disable SSO services for Enterprise organizations. Default |
BW_ICONS_PROXY_TO_CLOUD | Enabling this service will proxy icon service requests to operate through cloud services in order to lower system memory load. |
Configure SMTP settings for your unified deployment. Copy information from your chosen mail SMTP provider into the following fields:
Variable | Description |
---|---|
globalSettings__mail__replyToEmail | Enter the reply email for your server. |
globalSettings__mail__smtp__host | Enter host domain for your SMTP server. |
globalSettings__mail__smtp__port | Enter the port number from the SMTP host. |
globalSettings__mail__smtp__ssl | If your SMTP host uses SSL enter Set value to |
globalSettings__mail__smtp__username | Enter the SMTP username. |
globalSettings__mail__smtp__password | Enter the SMTP password. |
Yubico API (YubiKey)
Variable | Description |
---|---|
globalSettings__yubico__clientId | Replace value with ID received from your Yubico Key. Sign up for Yubico Key here. |
globalSettings__yubico__key | Input the key value received from Yubico. |
Utilizing the variety of database options that are compatible with the unified deployment will require additional .env
configurations.
In settings.env
:
Bash# Database
BW_DB_PROVIDER=mysql
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password
In settings.env
:
Bash# Database
BW_DB_PROVIDER=sqlserver
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password
In settings.env
:
Bash# Database
BW_DB_PROVIDER=sqlite
BW_DB_FILE=/path/to/.db
Assigning the sqlite
value will create a vault.db
file in the /etc/bitwarden
volume automatically. BW_DB_FILE
is only required if you would like to specify the path to a different database file.
In settings.env
:
Bash# Database
BW_DB_PROVIDER=postgresql
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password
Other
Variable | Description |
---|---|
globalSettings__disableUserRegistration | Enable or disable user account registration capabilities. |
globalSettings__hibpApiKey | Enter the API key provided by Have I Been Pwnd. Register to receive the API key here. |
adminSettings__admins | Enter admin email addresses. |
BW_REAL_IPS | Define real IPs in |
BW_CSP | Content-Security-Policy parameter. Reconfiguring this parameter may break features. By changing this parameter, you become responsible for maintaining this value. |
BW_DB_PORT | Specify a custom port for database traffic. If unspecified, the default will depend on your chosen database provider. |
To restart your Docker container after changing environment variables, run the following commands from the Bitwarden unified deployment directory:
Stop the running Docker container:
Bashdocker stop bitwarden
Remove the Docker container:
Bashdocker rm bitwarden
Run the Docker container again:
Bashdocker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env bitwarden/self-host:beta
Stop the running Docker container:
Bashdocker compose down
Recreate the containers:
Bashdocker compose up -d
Ensure that the containers are running properly with:
Bashdocker compose ps
By default, the Bitwarden container will consume memory that is available to it, often being more than the minimum needed to run. For memory conscious environments, you can use docker -m
or --memory=
to limit the Bitwarden container's memory usage.
Name, shorthand | Description |
---|---|
--memory=, -m | The maximum amount of memory the container can use. Bitwarden requires at least 200m. See the Docker documentation to learn more. |
To control memory usage with Docker Compose, use the mem_limit
key:
Bashservices: bitwarden: env_file: - settings.env image: bitwarden/self-host:beta restart: always mem_limit: 200m
While the Bitwarden unified deployment remains in beta release, we encourage you to report issues and give feedback via GitHub. Please use this issue template to report anything related to your Bitwarden unified deployment and check out this page to track known issues or join the discussion.
If you are planning to self-host a Bitwarden organization, see self-host an organization to get started.
For more information on Bitwarden's standard self-hosted deployment see:
Suggest changes to this page
How can we improve this page for you?
For technical, billing, and product questions, please contact support