Skip to 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
  • 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 blame#

Configure Git to ignore the Prettier revision:

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

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.

    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.

    If you’re a community developer, we recommend the following command. It starts the MSSQL and local mail server containers, which should be suitable for most community contributions.

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

    If you’re a Bitwarden developer, we recommend the following command. It starts both MSSQL and the Azurite container which is used to emulate Azure services used by the cloud instance.

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

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.

Warning

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:

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

  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.

Generate Certificates#

The next step is to create two self-signed certificates for local development. We provide a helper script that will generate these certificates and add them to your system’s keychain or certificate store.

MacOS#

  1. Generate the certificates and save them to your keychain:

    sh create_certificates_mac.sh
    
  2. You will receive output similar to the following. You will need this information for the next section.

    Certificate fingerprints:
    Identity Server Dev: 0BE8A0072214AB37C6928968752F698EEC3A68B5
    Data Protection Dev: C3A6CECAD3DB580F91A52FC9C767FE780300D8AB
    
  3. Open Keychain Access and go to your login keychain.

  4. Double-click the Bitwarden Data Protection Dev and Bitwarden Identity Server Dev certificates.
  5. In each certificate, change the Trust settings to “Always Trust”.

Windows#

  1. Generate the certificates and save them to the Certificate Store:

    .\create_certificates_windows.ps1
    
  2. You will receive output similar to the following. You will need this information for the next section.

    PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My
    
    Thumbprint                                Subject
    ----------                                -------
    0BE8A0072214AB37C6928968752F698EEC3A68B5  CN=Bitwarden Identity Server Dev
    C3A6CECAD3DB580F91A52FC9C767FE780300D8AB  CN=Bitwarden Data Protection Dev
    

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. Copy the example secret.json file.

    cp secrets.json.example secrets.json
    
  2. Edit secrets.json and update the following strings:

    • sqlServer > connectionString: insert your password where indicated
    • identityServer > certificateThumbprint: insert your Identity certificate thumbprint from the previous step
    • dataProtection > certificateThumbprint: insert your Data Protection certificate thumbprint from the previous step
  3. You also need the following additional user secrets:

  4. Add the secrets to each Bitwarden server project:

    pwsh setup_secrets.ps1
    

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

pwsh setup_secrets.ps1 -clear:$True

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.