Skip to main content

Setup Guide

This page will show you how to set up a local Bitwarden server for development purposes.

The Bitwarden server is comprised of several services that can run independently. For a basic development setup, you will need the Api and Identity services.

info

Before you start: make sure you’ve installed the recommended Tools and Libraries, including:

  • Docker Desktop
  • Visual Studio 2022
  • Powershell
  • NET 6.0 SDK
  • Azure Data Studio

Clone the repository​

  1. Clone the Bitwarden Server project:

    git clone https://github.com/bitwarden/server.git

  2. Open a terminal and navigate to the root of the cloned repository.

Configure Git​

  1. Configure Git to ignore the Prettier revision:

    git config blame.ignoreRevsFile .git-blame-ignore-revs

  2. (Optional) Set up the pre-commit dotnet format hook:

    git config --local core.hooksPath .git-hooks

    Formatting requires a full build, which may be too slow to do every commit. As an alternative, you can run dotnet format from the command line when convenient (e.g. before requesting a PR review).

Configure Docker​

We provide a Docker Compose configuration, which is used during development to provide the required dependencies. This is split up into multiple service profiles to facilitate easily customization.

  1. Some Docker settings are configured in the environment file, dev/.env. Copy the example environment file:

    cd dev
    cp .env.example .env

  2. Open .env with your preferred editor.

  3. Set the MSSQL_PASSWORD variable. This will be the password for your MSSQL database server.

    caution

    Your MSSQL password must comply with the following password complexity guidelines

    • It must be at least eight characters long.
    • It must contain characters from three of the following four categories:
    • Latin uppercase letters (A through Z)
    • Latin lowercase letters (a through z)
    • Base 10 digits (0 through 9)
    • Non-alphanumeric characters such as: exclamation point (!), dollar sign ($), number sign (#), or percent (%).

  4. You can change the other variables or use their default values. Save and quit this file.

  5. Start the Docker containers.

    Using PowerShell, navigate to the cloned server repo location, into the dev folder and run the docker command below.

    docker compose --profile mssql --profile mail up -d

    Which starts the MSSQL and local mail server containers, which should be suitable for most community contributions.

     
    docker compose --profile cloud --profile mail up -d

    Which starts MSSQL, mail, and Azurite container. The additional Azurite container is required to emulate Azure used by the Bitwarden cloud environment.

After you’ve run the docker compose command, you can use the Docker Dashboard to manage your containers. You should see your containers running under the bitwardenserver group.

caution

Changing MSSQL_PASSWORD variable after first running docker compose will require a re-creation of the storage volume.

Warning: this will delete your development database.

To do this, run

docker compose --profile mssql down
docker volume rm bitwardenserver_edgesql_dev_data

After that, rerun the docker compose command from Step 5.

SQL Server​

In order to support ARM based development environments such as the M1 Macs, we use the Azure SQL Edge docker container instead of a normal Microsoft SQL Server container. It behaves mostly identical to a regular SQL Server instance and runs on port 1433.

You can connect to it using Azure Data Studio using the following credentials:

  • Server: localhost
  • Username: sa
  • Password: (the password you set in dev/.env)

Mailcatcher​

The server uses emails for many user interactions. We provide a pre-configured instance of MailCatcher, which catches any outbound email and prevents it from being sent to real email addresses. You can open its web interface at http://localhost:1080.

Azurite​

note

This section applies to Bitwarden developers only.

Azurite is an emulator for Azure Storage API and supports Blob, Queues and Table storage. We use it to minimize the online dependencies required for developing in a cloud environment.

To bootstrap the local Azurite instance, navigate to the dev directory in your server repo and run the following commands:

  1. Install the Az module. This may take a few minutes to complete without providing any user feedback (it may appear frozen).

    pwsh -Command "Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force"

  2. Run the setup script:

    pwsh setup_azurite.ps1

Create database​

You now have the MSSQL server running in Docker. The next step is to create the database that will be used by the Bitwarden server.

We provide a helper script which will create the development database vault_dev and also run all migrations.

Navigate to the dev folder in your server repo and perform the following steps:

  1. Create the database and run all migrations:

    pwsh migrate.ps1

  2. You should receive confirmation that each migration script has run successfully:

    Performing /mnt/migrator/DbScripts/2017-08-19_00_InitialSetup.sql
    Performing /mnt/migrator/DbScripts/2017-08-22_00_LicenseCheckScripts.sql
    Performing /mnt/migrator/DbScripts/2017-08-30_00_CollectionWriteOnly.sql
    [...]

If migrations are being skipped even though this is a new database, see MSSQL Database Troubleshooting.

note

You’ll need to re-run the migration helper script regularly to keep your local development database up-to-date. See MSSQL Database for more information.

Install Licensing Certificate​

To run your local server environment as a licensed instance, you will need to download the Licensing Certificate - Dev from the shared Engineering collection and install it. This can be done by double-clicking on the downloaded certificate.

  1. Log in to your company-issued Bitwarden account
  2. On the "Vaults" page, scroll down to the "Licensing Certificate - Dev" item
  3. View attachments and download both files
  4. Go to Keychain Access and set the dev.cer certificate to "Always Trust"
  5. The dev.pfx file will ask for a password. You can get this by clicking and opening the Licensing Certificate - Dev item in the vault

Configure User Secrets​

User secrets are a method for managing application settings on a per-developer basis. They override the settings in appSettings.json of each project. Your user secrets file should match the structure of the appSettings.json file for the settings you intend to override.

We provide a helper script which simplifies setting user secrets for all projects in the server repository.

  1. Get a template secrets.json. We need to get an initial version of secrets.json, which you will modify for your own secrets values.

    Navigate to the dev folder in your server repo and copy the example secrets.json file.

    cp secrets.json.example secrets.json
    • Copy the user secrets file from the shared Development collection (Your Bitwarden Vault) into the dev folder.
    • If you don't have access to the Development collection, contact our IT Manager to arrange access. Make sure you have first set up a Bitwarden account using your company email address.
    • This secrets.json is configured to use the dockerized Azurite and MailCatcher instances and is recommended for this guide.

  2. Update secrets.json with your own values:

    • sqlServer > connectionString: insert your password where indicated

  3. Once you have your secrets.json complete, run the below command to add the secrets to each Bitwarden server project.

    pwsh setup_secrets.ps1

The helper script also supports an optional -clear switch which removes all existing settings before re-applying them:

pwsh setup_secrets.ps1 -clear

Build and Run the Server​

You are now ready to build and run your development server.

  1. Open a new terminal window in the root of the repository.

  2. Restore the nuget packages required for the Identity service:

    cd src/Identity
    dotnet restore

  3. Start the Identity service:

    dotnet run

  4. Test that the Identity service is alive by navigating to http://localhost:33656/.well-known/openid-configuration

  5. In another terminal window, restore the nuget packages required for the Api service:

    cd src/Api
    dotnet restore

  6. Start the Api Service:

    dotnet run

  7. Test that the Api service is alive by navigating to http://localhost:4000/alive

  8. Connect a client to your local server by configuring the client’s Api and Identity endpoints. Refer to https://bitwarden.com/help/article/change-client-environment/ and the instructions for each client in the Contributing Documentation.

info

If you cannot connect to the Api or Identity projects, check the terminal output to confirm the ports they are running on.

note

We recommend continuing with the Web Vault afterwards, since many administrative operations can only be performed in it.

Debugging​

info

On macOS, you must run dotnet restore for each Project before it can be launched in the a debugger.

Visual Studio​

To debug:

  • On Windows, right-click on each project > click Debug > click Start New Instance
  • On MacOS, right-click each project > click Start Debugging Project

Rider​

Launch the Api project and the Identity project by clicking the "Play" button for each project separately.