Local Development Setup

Set up your local development environment for Bitwarden Server

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:

   • Installation ID - Get from https://bitwarden.com/host
   • Installation Key - Get from https://bitwarden.com/host

   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:

Service	Port	Description
API	4000	Main API server
Identity	33656	Authentication service
SQL Server	1433	Microsoft SQL Server
MySQL	3306	MySQL (optional)
PostgreSQL	5432	PostgreSQL (optional)
MailCatcher	1080	Email 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

• Database Migrations - Learn how to create and run migrations
• Testing Guide - Run and write tests
• Project Structure - Understand the codebase organization
• Contribution Guide - Submit your first contribution