Skip to content

guide.md

Latest commit

 

History

History
445 lines (299 loc) · 13.4 KB

guide.md

File metadata and controls

445 lines (299 loc) · 13.4 KB
Raw
sidebar_position 1

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

:::

:::info

A guide for developing in VS Code Dev containers can be found here if you prefer developing in a containerized environment.

:::

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.

:::

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.

Navigate to the dev folder in your server repo and perform the following commands.

MacOS

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

    sh create_certificates_mac.sh

  2. You will be prompted to enter a password 3 times. Create a complex password and type it into the Export Password field on each prompt. You will not be able to copy/paste.

  3. You will receive output similar to the following. You will need to collect the generated certificate fingerprints for use in the Configure User Secrets section.

    Certificate fingerprints:
Identity Server Dev: 0BE8A0072214AB37C6928968752F698EEC3A68B5
Data Protection Dev: C3A6CECAD3DB580F91A52FC9C767FE780300D8AB

  4. Open Keychain Access and go to your login keychain.

  5. Double-click the Bitwarden Data Protection Dev and Bitwarden Identity Server Dev certificates.

  6. 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 to collect the generated certificate fingerprints for use in the Configure User Secrets section.

    PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My

Thumbprint                                Subject
----------                                -------
0BE8A0072214AB37C6928968752F698EEC3A68B5  CN=Bitwarden Identity Server Dev
C3A6CECAD3DB580F91A52FC9C767FE780300D8AB  CN=Bitwarden Data Protection Dev

Linux

  1. Generate the certificates and save them to your certificate store:

    ./create_certificates_linux.sh

  2. You will receive output similar to the following. You will need to collect the generated certificate fingerprints for use in the Configure User Secrets section.

    Certificate fingerprints:
Identity Server Dev: 0BE8A0072214AB37C6928968752F698EEC3A68B5
Data Protection Dev: C3A6CECAD3DB580F91A52FC9C767FE780300D8AB

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.

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 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
    • identityServer > certificateThumbprint: insert your Identity certificate thumbprint from the previous step
    • dataProtection > certificateThumbprint: insert your Data Protection certificate thumbprint from the previous step

  3. Once you have your secrets.json complete, run this command to 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.