Skip to main content
This guide will help you set up your local development environment for working with the Bitwarden Server codebase.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • .NET SDK 8.0 - The server is built with .NET 8.0
  • Docker - For running local dependencies (databases, mail catcher)
  • Docker Compose - For orchestrating development containers
  • Git - For version control
  • PowerShell (optional) - For running setup scripts on Windows
The recommended .NET version is 8.0.100 or later. Check global.json in the repository root for the exact version.

​
Development Container Setup

Bitwarden Server includes development container configurations for easy setup.
1

Clone the repository

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

Choose your dev container

There are multiple dev container configurations available in .devcontainer/:
  • community_dev - For community contributors (recommended)
  • internal_dev - For Bitwarden team members
  • bitwarden_common - Base configuration shared by others
3

Initialize data directories

The dev container will automatically create these directories:
mkdir -p dev/.data/keys
mkdir -p dev/.data/mssql
mkdir -p dev/.data/azurite
mkdir -p dev/helpers/mssql
4

Configure environment variables

Create a dev/.env file with your database password:
MSSQL_SA_PASSWORD=your_strong_password_here
5

Set up secrets and certificates

Run the post-create setup script:
bash .devcontainer/community_dev/postCreateCommand.sh
You’ll be prompted for:For local development, you can use test values:
  • Installation ID: 00000000-0000-0000-0000-000000000001
  • Installation Key: (leave empty for local dev)
6

Run database migrations

dotnet run --project ./util/MsSqlMigratorUtility "Server=localhost;Database=vault_dev;User Id=SA;Password=your_password;Encrypt=True;TrustServerCertificate=True"

​
Manual Setup (Without Dev Container)

If you prefer not to use dev containers:
1

Start required services

Using Docker Compose:
docker-compose -f .devcontainer/bitwarden_common/docker-compose.yml up -d
This starts:
  • SQL Server 2022 - Main database (port 1433)
  • MailCatcher - Email testing (port 1080)
2

Configure secrets

Copy the example secrets file:
cp dev/secrets.json.example dev/secrets.json
Update connection strings in dev/secrets.json:
{
  "globalSettings": {
    "sqlServer": {
      "connectionString": "Server=localhost;Database=vault_dev;User Id=SA;Password=your_password;Encrypt=True;TrustServerCertificate=True"
    },
    "installation": {
      "id": "00000000-0000-0000-0000-000000000001",
      "key": ""
    }
  }
}
3

Run migrations

See the Database Migrations guide for details.
4

Build the solution

dotnet build bitwarden-server.sln

​
IDE Configuration

​
Visual Studio Code

Recommended extensions are configured in .vscode/extensions.json:
  • C# Dev Kit - For C# development
  • EditorConfig - For consistent code formatting
The dev container automatically installs these extensions.

​
JetBrains Rider / Visual Studio

Open the solution file: 
bitwarden-server.sln
Both IDEs will automatically detect the EditorConfig settings.

​
Running the API

To run the API project locally: 
cd src/Api
dotnet run
The API will be available at https://localhost:4000.
The API uses settings from appsettings.Development.json when running in development mode.

​
Running the Identity Service

cd src/Identity
dotnet run
The Identity service will be available at https://localhost:33656.

​
Running Tests

See the Testing Guide for comprehensive testing instructions.

​
Port Configuration

The development environment uses these ports:
ServicePortDescription
API4000Main API server
Identity33656Authentication service
SQL Server1433Microsoft SQL Server
MySQL3306MySQL (optional)
PostgreSQL5432PostgreSQL (optional)
MailCatcher1080Email testing UI

​
Git Hooks

Bitwarden uses git hooks for automatic code formatting: 
git config --local core.hooksPath .git-hooks
This enables pre-commit hooks that run dotnet format automatically.

​
Troubleshooting

​
Database Connection Issues

  1. Ensure SQL Server is running: 
    docker ps | grep mssql
  2. Verify your connection string in dev/secrets.json
  3. Check SQL Server logs: 
    docker logs bitwarden_mssql

​
Build Errors

  1. Clean and restore: 
    dotnet clean
dotnet restore
dotnet build
  2. Verify .NET SDK version: 
    dotnet --version

​
Port Conflicts

If ports are already in use, update the port mappings in:
  • .devcontainer/community_dev/devcontainer.json - forwardPorts section
  • docker-compose.yml - ports section

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us