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.
Clone the repository
Clone the Bitwarden Server project:
git clone https://github.com/bitwarden/server.git
Open a terminal and navigate to the root of the cloned repository.
Configure Git to ignore the Prettier revision:
git config blame.ignoreRevsFile .git-blame-ignore-revs
(Optional) Set up the pre-commit
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 formatfrom the command line when convenient (e.g. before requesting a PR review).
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.
Some Docker settings are configured in the environment file,
dev/.env. Copy the example environment file:
cp .env.example .env
.envwith your preferred editor.
MSSQL_PASSWORDvariable. 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 (%).
You can change the other variables or use their default values. Save and quit this file.
Start the Docker containers.
Using PowerShell, navigate to the cloned server repo location, into the
devfolder 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.
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
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.
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
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.
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:
Azmodule. 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"
Run the setup script:
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
Navigate to the
dev folder in your server repo and perform the following steps:
Create the database and run all migrations:
You should receive confirmation that each migration script has run successfully:
If migrations are being skipped even though this is a new database, see MSSQL Database Troubleshooting.
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.
Configure User Secrets
are a method for managing application settings on a per-developer basis. They override the settings
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.
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
devfolder in your server repo and copy the example
cp secrets.json.example secrets.json
secrets.jsonwith your own values:
connectionString: insert your password where indicated
key: request a hosting installation Id and Key and insert them here
licenseDirectory: set this to an empty directory, this is where uploaded license files will be stored.
Once you have your
secrets.jsoncomplete, run the below command to add the secrets to each Bitwarden server project.
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.
Open a new terminal window in the root of the repository.
Restore the nuget packages required for the Identity service:
Start the Identity service:
Test that the Identity service is alive by navigating to http://localhost:33656/.well-known/openid-configuration
In another terminal window, restore the nuget packages required for the Api service:
Start the Api Service:
Test that the Api service is alive by navigating to http://localhost:4000/alive
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.
If you cannot connect to the Api or Identity projects, check the terminal output to confirm the ports they are running on.
We recommend continuing with the Web Vault afterwards, since many administrative operations can only be performed in it.
On macOS, you must run
dotnet restore for each Project before it can be launched in the a
- On Windows, right-click on each project > click Debug > click Start New Instance
- On macOS, right-click each project > click Start Debugging Project
Launch the Api project and the Identity project by clicking the "Play" button for each project separately.