Install and Deploy - Unified (Beta)

注意

This is a beta release, which means that this deployment option may be unstable and have issues. If you manage a Bitwarden organization vault, we recommend using the officially-supported, standard deployment option.

Learn how to report issues.

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, MySQL/MariaDB.

  • Run on ARM architecture for alternative systems such as Raspberry Pi and NAS servers.

System requirements

Bitwarden unified deployment requires:

  • At least 200 MB RAM

  • Storage 1GB

  • Docker Engine 19+

Install Docker

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:

Run Bitwarden unified

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.

Specify environment variables

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 bitwarden.yourdomain.com with the domain where Bitwarden will be accessed.
BW_DB_PROVIDER The database provider you will be using for your Bitwarden server. Available options are sqlserver, postgresql, or mysql/mariadb.
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_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/.
備考

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.

Using docker run

The unified deployment can be run with the docker run command, as in the following example:

docker 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. bitwarden is used in the example.
--volume , -v Bind mount a volume. At a minimum, mount /etc/bitwarden.
--publish , -p Map container ports to the host. The example shows the port 80:8080 mapped. Port 8443 is required when configuring SSL.
--env-file Path of the file to read environment variables from. Alternatively, use the --env flag to declare environment variables inline (learn more).

Once you run the command, verify that the container is running and healthy with:

docker 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.

Using Docker Compose

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:

---
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:

docker compose up -d

Verify that all containers are running correctly:

docker 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.

Update your server

To update your unified deployment:

  1. Stop the running Docker container:

    docker stop bitwarden

  2. Remove the Docker container:

    docker rm bitwarden

  3. Run the following command to pull the most recent Bitwarden unified image:

    docker pull bitwarden/self-host:beta

  4. Run the Docker container again:

    docker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env bitwarden/self-host:beta


  1. Stop the running Docker container:

    docker compose down

  2. Run the following command to pull the most recent Bitwarden unified image:

    docker compose pull

  3. Recreate any containers that need to be updated:

    docker compose up -d

  4. Verify that the containers are running:

    docker compose ps


Environment variables

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.

備考

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, 8080.
BW_PORT_HTTPS Change the port used for HTTPS traffic. By default, 8443.

SSL

Use these values to change certificate settings. For additional information, see Certificate Options.

Variable Description
BW_ENABLE_SSL Use SSL/TLS. true/false. Default false.

SSL is required for Bitwarden to function properly. If you are not using SSL configured in the Bitwarden container you should front Bitwarden with a SSL proxy.
BW_SSL_CERT The name of your SSL certificate file. The file must be located in the /etc/bitwarden directory within the container. Default ssl.crt.
If you wish to use an existing certificate, learn more here.
BW_SSL_KEY The name of your SSL key file. The file must be located in the /etc/bitwarden directory within the container. Default ssl.key.
If you wish to use an existing certificate, learn more here.
BW_ENABLE_SSL_CA Use SSL with certificate authority(CA) backed service. true/false. Default false.
BW_SSL_CA_CERT The name of your SSL CA certificate. The file must be located in the /etc/bitwarden directory within the container. Default ca.crt.
BW_ENABLE_SSL_DH Use SSL with Diffie-Hellman key exchange. true/false. Default false.
BW_SSL_DH_CERT The name of your Diffie-Hellman parameters file. The file must be located in the /etc/bitwarden directory within the container. Default dh.pem.
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.

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 true.
BW_ENABLE_API Do not disable this service. Default true.
BW_ENABLE_EVENTS Enable or disable Bitwarden events logs for teams and enterprise event monitoring. Default false.
BW_ENABLE_ICONS Enable or disable Bitwarden brand icons that are set with the login item URI's. Learn more here. Default true.
BW_ENABLE_IDENTITY Do not disable this service. Default true.
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 true.
BW_ENABLE_SCIM Enable or disable SCIM for Enterprise organizations. Default false.
BW_ENABLE_SSO Enable or disable SSO services for Enterprise organizations. Default false.
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.
If choosing to use this setting, BW_ENABLE_ICONS should be set to false in order to reduce container load. Default false.
BW_ENABLE_KEY_CONNECTOR Set to true to enable Key Connector.
BW_KEY_CONNECTOR_INTERNAL_URL Internal URL to be used by Key Connector.

Mail

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 true.

Set value to false if your host uses TLS service.
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.

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 nginx.conf in a comma seperated list. Useful for defining proxy servers that forward the client IP address. Learn more.
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.

Restart the container

To restart your Docker container after changing environment variables, run the following commands from the Bitwarden unified deployment directory:

  1. Stop the running Docker container:

    docker stop bitwarden

  2. Remove the Docker container:

    docker rm bitwarden

  3. Run the Docker container again:

    docker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080  --env-file settings.env bitwarden/self-host:beta

  1. Stop the running Docker container:

    docker compose down

  2. Recreate the containers:

    docker compose up -d
  3. Ensure that the containers are running properly with:

    docker compose ps

Memory usage

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:

services:
  bitwarden:
    env_file:
      - settings.env
    image: bitwarden/self-host:beta
    restart: always
    mem_limit: 200m

Reporting issues

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.

Additional resources

For more information on Bitwarden's standard self-hosted deployment see:


言語
© 2023 Bitwarden, Inc.
利用規約プライバシーポリシーサイトマップ