Getting started

This page covers the minimum needed to clone, build, and run the Bitwarden Server stack locally. The canonical setup walk-through is the upstream Server Setup Guide; the section below summarises what the repo itself ships.

Prerequisites

• .NET 8 SDK — exact version pinned in global.json ("sdk": { "version": "8.0.100", "rollForward": "latestFeature" }).
• Docker + Docker Compose for the developer database and ancillary services.
• PowerShell 7+ — the install/seed/migrate scripts in dev/ are written in pwsh.
• Node.js (only for src/Admin/, which uses webpack to bundle CSS/JS — see src/Admin/package.json).
• Rust toolchain — only required if you build util/RustSdk/ (used by the seeder and the in-process Bitwarden SDK bindings).

The .devcontainer/ directory provides a ready-to-run VS Code dev container that bundles all the above.

Cloning

git clone https://github.com/bitwarden/server.git bitwarden_server
cd bitwarden_server
git config --local core.hooksPath .git-hooks   # optional dotnet-format pre-commit

Bringing up the developer stack

Bitwarden's developer environment is driven from dev/docker-compose.yml. It uses Docker Compose profiles so you only start the dependencies you need:

cd dev
cp .env.example .env
# Default cloud-style stack (SQL Server + Azurite + Redis):
docker compose --profile cloud up -d
# Optional: mailcatcher, RabbitMQ, Service Bus emulator, MySQL/Postgres/MariaDB, SimpleSAMLphp IdP
docker compose --profile mail up -d

Profiles defined: cloud, mssql, storage, mail, postgres, ef, mysql, mariadb, idp, rabbitmq, proxy, servicebus, redis. See dev/docker-compose.yml for what each one starts.

One-time secrets and certs

# Linux / macOS / Windows: generate the IdentityServer signing cert
./dev/create_certificates_linux.sh   # or _mac.sh / _windows.ps1

# Set up the secrets store + dev secrets
./dev/setup_secrets.ps1

# Initialize Azurite (blob storage emulator) directories and queues
./dev/setup_azurite.ps1

setup_secrets.ps1 reads dev/secrets.json.example and writes user-secrets entries for each project. dev/.env.example documents every env var the compose stack expects (passwords, ports, IdP config, etc.).

Migrating the database

# SQL Server (canonical) — runs MsSqlMigratorUtility
./dev/migrate.ps1

# Entity Framework providers — Postgres / MySQL / SQLite
./dev/ef_migrate.ps1 -DatabaseProvider Postgres

migrate.ps1 invokes util/MsSqlMigratorUtility/ against the connection string in user secrets. SQL change scripts live in util/Migrator/DbScripts/ (one per migration, applied in alphabetical order; the migrator records applied scripts in dbo.Migration). EF migrations live under util/MySqlMigrations/, util/PostgresMigrations/, and util/SqliteMigrations/.

Seed data:

./dev/seed.ps1

This calls util/Seeder/ (.NET console) which inserts demo users/orgs/ciphers via util/SeederApi/ and the Rust SDK in util/RustSdk/.

Building and running

# Restore everything from the solution file
dotnet restore bitwarden-server.sln

# Build all projects
dotnet build bitwarden-server.sln

# Run a single service
dotnet run --project src/Identity/Identity.csproj
dotnet run --project src/Api/Api.csproj

There are VS / Rider run profiles in .run/ and a launch.json equivalent for VS Code. Default ports:

Service	Default port (dev)
Identity	33656 (configurable in src/Identity/appsettings.Development.json)
Api	4000
Admin	33657
Notifications	61840
Events	46273
Sso	51822
Scim	44559
Icons	50024
Billing	47002

Hostnames bitwarden.localhost and localhost are pre-allowed in the dev CORS policy (CoreHelpers.IsCorsOriginAllowed).

Running the test suite

# Unit tests
dotnet test test/Core.Test/Core.Test.csproj
# Integration tests (require database + Azurite)
dotnet test test/Api.IntegrationTest/Api.IntegrationTest.csproj
# Full solution
dotnet test bitwarden-server.sln

There are 30+ test projects under test/ and bitwarden_license/test/. See how-to-contribute/testing for a deeper dive (in particular the IntegrationTestCommon helpers and how the integration tests bootstrap the database).

Loading the Web Vault against your local server

Clone the bitwarden/clients repository, point its apps/web/config/development.json at http://localhost:4000 (and the matching local Identity URL), then npm run build:bit:watch inside apps/web/. The CORS policy in Api.Startup already trusts bitwarden.localhost.

Linting and formatting

The repository enforces formatting via dotnet format. Local Git hooks under .git-hooks/ run dotnet format --verify-no-changes on staged files; CI runs the same check in .github/workflows/test.yml. The pinned formatting rules live in .editorconfig (5,509 bytes — opinionated, do not relax without team buy-in).

There is also a Husky-style pre-commit script under .git-hooks/pre-commit.

Common dev tasks

I want to…	Do this
Add a new SQL stored procedure	Drop a .sql script into util/Migrator/DbScripts/{date}_{slug}.sql and add the canonical version under src/Sql/dbo/Stored Procedures/.
Add an EF migration	dotnet ef migrations add <Name> --project util/PostgresMigrations (and the equivalents for MySQL / SQLite).
Regenerate the Swagger document	./dev/generate_openapi_files.ps1 (see swagger/ output).
Add a feature flag	Add the flag name to src/Core/Constants.cs (FeatureFlagKeys) and gate code with IFeatureService.IsEnabled.
Reset Azurite	docker compose --profile storage down -v && ./dev/setup_azurite.ps1.

Troubleshooting

• Could not connect to mssql — make sure the mssql profile is up and the MSSQL_PASSWORD in dev/.env matches your user-secrets globalSettings:sqlServer:connectionString.
• Migration script not applied — migrate.ps1 only re-runs scripts that are not in the dbo.Migration table. Use verify_migrations.ps1 to compare DB state against util/Migrator/DbScripts/.
• CORS failure from web vault — check that the client origin is on globalSettings.AllowedOrigins or matches BitwardenCloudDomains / localhost rules in CoreHelpers.IsCorsOriginAllowed.
• Identity oidc-discovery failures — your dev cert is missing or untrusted; rerun dev/create_certificates_*.sh.

Once everything is running, head to architecture for the runtime model or to a feature page for code pointers.