Ansible Role: Bitwarden

Deploy Bitwarden with Docker and Docker-Compose using the bitwarden.sh.

This role is an automated wrapper around the Bitwarden setup scripts. It makes heavy use of handlers to trigger reconfigure and update tasks.

If you need any task not covered by the role it's totally fine to use the setup script on the machine directly. Use the official docs as reference: https://bitwarden.com/help/article/install-on-premise/

Usage

Add the role to your playbook:

- hosts: server
  roles:
    - { role: breuninger.bitwarden }

Known issues

Certbot

We currently only support static TLS certificates for Nginx. The Certbot integration is not configured. Feel free to add this feature as a PR if needed.

Bitwarden version

Bitwarden has a different version in the setup files than in the tagged version of the repo may indicates. This is due to their release strategy, which always increases the actual version only in the master. We are already in talks with Bitwarden and hope for a different mode of release.

SSL Modes

The Bitwarden setup script allows for four different ways of setting up SSL (or the lack thereof): a user provided SSL cert, an SSL cert that is created by Let's Encrypt, a self-signed cert generated by the setup container, and no SSL (not recommended for installs being used normally).

User Provided

To maintain backwards compatibility, this is the default mode for this role. While the Bitwarden setup script allows for untrusted certs provided by the user, this role requires it to be trusted (signed by a CA, not self signed).

- hosts: server
  roles:
    - role: breuninger.bitwarden
      vars:
        bitwarden_ssl_mode: provided
        bitwarden_nginx_cert_path: /path/to/ssl/cert
        bitwarden_nginx_key_path: /path/to/ssl/key

If an untrusted-user-provided-cert usecase is needed, it can be added with a new ssl_mode and corresponding inputs in defaults/main.yml.

Let's Encrypt

Use the Certbot SSL integration that comes with the Bitwarden setup script

- hosts: server
  roles:
    - role: breuninger.bitwarden
      vars:
          bitwarden_ssl_mode: lets_encrypt
          bitwarden_lets_encrypt_email: alice@email.com

Generated self signed

The Bitwarden setup script allows for generating a self-signed SSL cert to utilize SSL, but from an untrusted source. The two methods above are better for running Bitwarden in a Production environment. Please choose from one of them instead of using this option, unless absolutely necessary.

- hosts: server
  roles:
    - role: breuninger.bitwarden
      vars:
        bitwarden_ssl_mode: generate

No SSL

Please heavily consider your use case before using this option. One legitimate usecase for this is SSL termination at a reverse proxy.

- hosts: server
  roles:
    - role: breuninger.bitwarden
      vars:
        bitwarden_ssl_mode: disable

Install and configure bitwarden on premise in docker-compose fashion.

Table of content

• Requirements
• Default Variables
  • bitwarden_domain_name
  • bitwarden_global_env
  • bitwarden_lets_encrpyt_email
  • bitwarden_lets_encrypt_email
  • bitwarden_nginx_cert_path
  • bitwarden_nginx_key_path
  • bitwarden_region
  • bitwarden_script_version
  • bitwarden_setup_config
  • bitwarden_ssl_mode
  • bitwarden_ssl_provider
  • bitwarden_test_install_script
• Dependencies
• License
• Author

---

Default Variables

bitwarden_domain_name

Domain name which used for Bitwarden

Default value

bitwarden_domain_name: localhost

bitwarden_global_env

Map of global Bitwarden environment variables. Each entire is mapped to the global.override.env. See https://bitwarden.com/help/article/environment-variables/

Default value

bitwarden_global_env: {}

Example usage

bitwarden_global_env:
  globalSettings__mail__smtp__host: localhost
  globalSettings__mail__smtp__port: 25

bitwarden_lets_encrpyt_email

Lets Encrypt email account if bitwarden_ssl_mode set to "lets_encrypt"

bitwarden_lets_encrypt_email

Default value

bitwarden_lets_encrypt_email:

bitwarden_nginx_cert_path

Path of the certificate file used for the Nginx container (required if bitwarden_ssl_mode == "provided"). The user of the role is responsible for providing a valid certificate file. File is copied from the provided location to Bitwardens user home in order to garantue the correct mapping inside the container.

Default value

bitwarden_nginx_cert_path:

bitwarden_nginx_key_path

Path of the key file used for the Nginx container (required if bitwarden_ssl_mode == "provided"). The user of the role is responsible for providing a valid key file. File is copied from the provided location to Bitwardens user home in order to garantue the correct mapping inside the container.

Default value

bitwarden_nginx_key_path:

bitwarden_region

Region which is used for Bitwarden. Options: US, EU

Default value

bitwarden_region: US

bitwarden_script_version

Default value

bitwarden_script_version: v2023.12.0

bitwarden_setup_config

Map of Bitwarden setup configuration values to override. Use this to change values in the generated config.yml file from Bitwarden.

Default value

bitwarden_setup_config: {}

Example usage

bitwarden_setup_config:
  database_docker_volume: true

bitwarden_ssl_mode

Default value

bitwarden_ssl_mode: provided

bitwarden_ssl_provider

Provides the SSL mode to use when setting up the installation Options: provided, generate, lets_encrypt, disable

bitwarden_test_install_script

A flag to disable downloading the bitwarden.sh script. Used in cases where the Let's Encrypt ssl_mode needs to be tested without fear of hitting the Let's Encrypt rate limit. Or to test changes to the bitwarden.sh or run.sh scripts. Hopefully this flag can be added to the bitwarden.sh script in the future instead of being used here.

Default value

bitwarden_test_install_script: false

Dependencies

None.

License

MIT

Author

Operations Core Toolig ops-core-tooling@breuninger.de