Skip to main content
This quickstart guide will help you get Bitwarden Server running locally for development or evaluation purposes.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Quick Start with Docker

The fastest way to get started is using Docker Compose for the development environment.
1

Clone the Repository

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

Start the Development Environment

Start the required infrastructure services (database, storage, mail):
cd dev
docker compose --profile cloud up -d
This starts:
  • SQL Server on port 1433
  • Azure Storage Emulator (Azurite) on ports 10000-10002
  • MailCatcher on port 1080 (web UI) and 1025 (SMTP)
Wait about 30 seconds for SQL Server to initialize before proceeding.
3

Initialize the Database

Apply database migrations:
cd ../util/Migrator
dotnet run
You should see output indicating successful migration application.
4

Run the API Service

Start the main API service:
cd ../../src/Api
dotnet run
The API will start on https://localhost:4000 and http://localhost:5000.
5

Run the Identity Service

In a new terminal, start the Identity service:
cd src/Identity
dotnet run
The Identity service will start on https://localhost:33656.
Your Bitwarden Server is now running! The API is available at https://localhost:4000.

​
Verify Installation

Test the API with a health check: 
curl https://localhost:4000/healthz
You should receive a 200 OK response.

​
Next Steps

Local Setup Guide

Configure your development environment for full-featured development

Architecture

Understand the microservices architecture and service relationships

API Reference

Explore the REST API endpoints and authentication flows

Deploy with Docker

Deploy a production-ready instance with Docker

​
Alternative: Run All Services

To run all services at once, use the docker-compose configuration: 
cd dev
docker compose --profile cloud --profile idp up -d
This includes:
  • All infrastructure services
  • Test identity provider (SimpleSAMLphp) on port 8090

​
Troubleshooting

If you see database connection errors:
  1. Ensure SQL Server is running: docker ps
  2. Wait 30-60 seconds for SQL Server to fully initialize
  3. Check the connection string in dev/.env or src/Api/appsettings.json
  4. Try restarting the SQL Server container: 
    docker compose restart mssql
If ports are already in use:
  1. Check what’s using the port: lsof -i :4000 (Linux/Mac) or netstat -ano | findstr :4000 (Windows)
  2. Either stop the conflicting service or modify the port in launchSettings.json
  3. Common conflicting ports: 4000 (API), 33656 (Identity), 1433 (SQL Server)
If you encounter HTTPS certificate warnings:
# Trust the development certificate
dotnet dev-certs https --trust
On Linux, you may need to accept the certificate in your browser.

​
Environment Variables

For local development, create a dev/.env file with your configuration: 
# Database
MSSQL_PASSWORD=YourStrongPassword123!

# Storage (using Azurite defaults)
globalSettings__attachment__baseDirectory=/mnt/data/attachments
globalSettings__send__baseDirectory=/mnt/data/sends

# Mail (using MailCatcher)
globalSettings__mail__smtp__host=localhost
globalSettings__mail__smtp__port=1025
See Environment Variables for a complete reference.

​
Development Workflow

Once your environment is set up:
  1. Make changes to the code in src/
  2. Run tests: dotnet test from the solution root
  3. Build: dotnet build
  4. Debug: Use your IDE’s debugging features with breakpoints
See the Development Guide for IDE-specific configuration.

​
Docker Compose Profiles

The development docker-compose configuration supports multiple profiles:
  • cloud - Core infrastructure (SQL, Azurite, MailCatcher)
  • mssql - SQL Server only
  • postgres - PostgreSQL (alternative to SQL Server)
  • mysql - MySQL (alternative to SQL Server)
  • idp - SimpleSAMLphp test identity provider
  • storage - Azurite storage emulator
Example: 
docker compose --profile postgres --profile storage up -d

​
Need Help?

Contributing Guide

Learn how to contribute to Bitwarden Server

Community Forums

Get help from the community

GitHub Issues

Report bugs or request features

Security

Report security vulnerabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us