Environment Variables - Bitwarden Server

Overview

Bitwarden Server services can be configured using environment variables. Environment variables override settings from appsettings.json files.

Environment variable names use double underscores (__) to represent nested configuration sections.Example: globalSettings__sqlServer__connectionString

Variable Naming Convention

Configuration path to environment variable conversion:

appsettings.json

{
  "globalSettings": {
    "sqlServer": {
      "connectionString": "Server=localhost;..."
    }
  }
}

Becomes:

globalSettings__sqlServer__connectionString="Server=localhost;..."

Core Configuration

Global Settings

globalSettings__selfHosted

boolean

default:"false"

Enable self-hosted mode. Disables cloud-specific features.

globalSettings__selfHosted=true

globalSettings__siteName

string

default:"Bitwarden"

Display name for the installation.

globalSettings__siteName="My Company Vault"

globalSettings__projectName

string

required

Service name (Api, Identity, Admin, etc.).

globalSettings__projectName=Api

Database Configuration

globalSettings__sqlServer__connectionString

string

required

Primary database connection string.SQL Server:

globalSettings__sqlServer__connectionString="Server=mssql;Database=vault;User Id=sa;Password=YourPassword;TrustServerCertificate=True;"

PostgreSQL:

globalSettings__sqlServer__connectionString="Host=postgres;Database=vault;Username=postgres;Password=YourPassword;"

MySQL:

globalSettings__sqlServer__connectionString="Server=mysql;Database=vault;Uid=root;Pwd=YourPassword;"

globalSettings__sqlServer__readOnlyConnectionString

string

Optional read replica connection string for read operations.

globalSettings__sqlServer__readOnlyConnectionString="Server=replica;Database=vault;User Id=readonly;Password=pass;"

globalSettings__databaseProvider

string

default:"sqlserver"

Database provider: sqlserver, postgres, or mysql.

globalSettings__databaseProvider=postgres

Certificate Configuration

globalSettings__identityServer__certificateThumbprint

string

SHA-1 thumbprint of Identity Server signing certificate.

globalSettings__identityServer__certificateThumbprint=ABC123DEF456789...

globalSettings__identityServer__certificatePath

string

Path to Identity Server certificate PFX file (alternative to thumbprint).

globalSettings__identityServer__certificatePath=/etc/bitwarden/identity_server.pfx

globalSettings__identityServer__certificatePassword

string

Password for Identity Server certificate PFX file.

globalSettings__identityServer__certificatePassword=your_password

globalSettings__dataProtection__certificateThumbprint

string

SHA-1 thumbprint of Data Protection certificate.

globalSettings__dataProtection__certificateThumbprint=ABC123DEF456789...

Storage Configuration

globalSettings__storage__connectionString

string

required

Blob storage connection string for attachments.Azure Blob Storage:

globalSettings__storage__connectionString="DefaultEndpointsProtocol=https;AccountName=account;AccountKey=key;"

Local Development (Azurite):

globalSettings__storage__connectionString="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://storage:10000/devstoreaccount1;"

globalSettings__attachment__connectionString

string

Separate storage for attachments (optional).

globalSettings__attachment__connectionString="DefaultEndpointsProtocol=https;..."

globalSettings__send__connectionString

string

Separate storage for Send files (optional).

globalSettings__send__connectionString="DefaultEndpointsProtocol=https;..."

Mail Configuration

globalSettings__mail__replyToEmail

string

required

Reply-to email address for system emails.

globalSettings__mail__replyToEmail=no-reply@example.com

globalSettings__mail__sendGridApiKey

string

SendGrid API key for email delivery.

globalSettings__mail__sendGridApiKey=SG.xxxxxxxxxx

globalSettings__mail__smtp__host

string

SMTP server hostname.

globalSettings__mail__smtp__host=smtp.gmail.com

globalSettings__mail__smtp__port

integer

default:"587"

SMTP server port.

globalSettings__mail__smtp__port=587

globalSettings__mail__smtp__ssl

boolean

default:"true"

Enable SSL/TLS for SMTP.

globalSettings__mail__smtp__ssl=true

globalSettings__mail__smtp__username

string

SMTP authentication username.

globalSettings__mail__smtp__username=user@example.com

globalSettings__mail__smtp__password

string

SMTP authentication password.

globalSettings__mail__smtp__password=your_password

Service URLs

globalSettings__baseServiceUri__api

string

required

Public URL for API service.

globalSettings__baseServiceUri__api=https://api.vault.example.com

globalSettings__baseServiceUri__identity

string

required

Public URL for Identity service.

globalSettings__baseServiceUri__identity=https://identity.vault.example.com

globalSettings__baseServiceUri__admin

string

Public URL for Admin service.

globalSettings__baseServiceUri__admin=https://admin.vault.example.com

globalSettings__baseServiceUri__notifications

string

Public URL for Notifications service.

globalSettings__baseServiceUri__notifications=wss://notifications.vault.example.com

globalSettings__baseServiceUri__sso

string

Public URL for SSO service.

globalSettings__baseServiceUri__sso=https://sso.vault.example.com

globalSettings__baseServiceUri__vault

string

required

Public URL for web vault.

globalSettings__baseServiceUri__vault=https://vault.example.com

Message Bus Configuration

globalSettings__serviceBus__connectionString

string

Azure Service Bus or RabbitMQ connection string.Azure Service Bus:

globalSettings__serviceBus__connectionString="Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=key"

RabbitMQ:

globalSettings__serviceBus__connectionString="amqp://username:password@rabbitmq:5672"

globalSettings__serviceBus__useRabbitMq

boolean

default:"false"

Use RabbitMQ instead of Azure Service Bus.

globalSettings__serviceBus__useRabbitMq=true

Cache Configuration

globalSettings__redis__connectionString

string

Redis connection string for distributed caching.

globalSettings__redis__connectionString="redis:6379,password=your_password"

globalSettings__distributedCache__provider

string

default:"memory"

Cache provider: memory, redis, or cosmos.

globalSettings__distributedCache__provider=redis

Service-Specific Variables

API Service

IpRateLimitOptions__EnableEndpointRateLimiting

boolean

default:"true"

Enable rate limiting.

IpRateLimitOptions__EnableEndpointRateLimiting=true

IpRateLimitOptions__RealIpHeader

string

default:"X-Forwarded-For"

Header containing real client IP (when behind proxy).

IpRateLimitOptions__RealIpHeader=X-Real-IP

Identity Service

IdentityServerOptions__IssuerUri

string

Override issuer URI for tokens.

IdentityServerOptions__IssuerUri=https://identity.example.com

Notifications Service

globalSettings__notificationHub__connectionString

string

Azure Notification Hub connection string.

globalSettings__notificationHub__connectionString="Endpoint=sb://namespace.servicebus.windows.net/;SharedAccessKeyName=DefaultFullSharedAccessSignature;SharedAccessKey=key"

globalSettings__notificationHub__hubName

string

Azure Notification Hub name.

globalSettings__notificationHub__hubName=bitwarden-hub

SSO Service

SsoSettings__CacheLifetimeInMinutes

integer

default:"5"

SSO configuration cache lifetime.

SsoSettings__CacheLifetimeInMinutes=10

ASP.NET Core Variables

ASPNETCORE_ENVIRONMENT

string

default:"Production"

Runtime environment: Development, Staging, or Production.

ASPNETCORE_ENVIRONMENT=Production

ASPNETCORE_URLS

string

default:"http://+:5000"

URLs to listen on.

ASPNETCORE_URLS=http://+:5000;https://+:5001

ASPNETCORE_Kestrel__Certificates__Default__Path

string

Path to Kestrel HTTPS certificate.

ASPNETCORE_Kestrel__Certificates__Default__Path=/etc/ssl/cert.pfx

ASPNETCORE_Kestrel__Certificates__Default__Password

string

Password for Kestrel HTTPS certificate.

ASPNETCORE_Kestrel__Certificates__Default__Password=your_password

Logging Configuration

Logging__LogLevel__Default

string

default:"Information"

Default log level: Trace, Debug, Information, Warning, Error, Critical.

Logging__LogLevel__Default=Warning

Logging__LogLevel__Microsoft

string

default:"Warning"

Log level for Microsoft libraries.

Logging__LogLevel__Microsoft=Information

Docker Compose Example

Complete example with all common variables:

docker-compose.yml

services:
  api:
    image: ghcr.io/bitwarden/api:latest
    environment:
      # Core Settings
      globalSettings__selfHosted: "true"
      globalSettings__siteName: "Bitwarden"
      globalSettings__projectName: "Api"
      
      # Database
      globalSettings__sqlServer__connectionString: "Server=mssql;Database=vault;User Id=sa;Password=${MSSQL_PASSWORD};TrustServerCertificate=True;"
      
      # Certificates
      globalSettings__identityServer__certificatePath: "/etc/bitwarden/identity_server.pfx"
      globalSettings__identityServer__certificatePassword: "${IDENTITY_CERT_PASSWORD}"
      globalSettings__dataProtection__certificatePath: "/etc/bitwarden/data_protection.pfx"
      globalSettings__dataProtection__certificatePassword: "${DATA_PROTECTION_CERT_PASSWORD}"
      
      # Storage
      globalSettings__storage__connectionString: "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://storage:10000/devstoreaccount1;"
      
      # Mail
      globalSettings__mail__replyToEmail: "no-reply@${DOMAIN}"
      globalSettings__mail__smtp__host: "${SMTP_HOST}"
      globalSettings__mail__smtp__port: "${SMTP_PORT}"
      globalSettings__mail__smtp__ssl: "true"
      globalSettings__mail__smtp__username: "${SMTP_USERNAME}"
      globalSettings__mail__smtp__password: "${SMTP_PASSWORD}"
      
      # Service URLs
      globalSettings__baseServiceUri__api: "https://${DOMAIN}/api"
      globalSettings__baseServiceUri__identity: "https://${DOMAIN}/identity"
      globalSettings__baseServiceUri__vault: "https://${DOMAIN}"
      
      # Message Bus
      globalSettings__serviceBus__connectionString: "amqp://${RABBITMQ_USER}:${RABBITMQ_PASS}@rabbitmq:5672"
      globalSettings__serviceBus__useRabbitMq: "true"
      
      # Redis
      globalSettings__redis__connectionString: "redis:6379,password=${REDIS_PASSWORD}"
      
      # Rate Limiting
      IpRateLimitOptions__EnableEndpointRateLimiting: "true"
      IpRateLimitOptions__RealIpHeader: "X-Forwarded-For"
      
      # ASP.NET Core
      ASPNETCORE_ENVIRONMENT: "Production"
      
      # Logging
      Logging__LogLevel__Default: "Warning"

Environment File

Store variables in .env file:

.env

# Domain
DOMAIN=vault.example.com

# Database
MSSQL_PASSWORD=YourStrongPassword123!

# Certificates
IDENTITY_CERT_PASSWORD=CertPassword123!
DATA_PROTECTION_CERT_PASSWORD=CertPassword123!

# Redis
REDIS_PASSWORD=RedisPassword123!

# RabbitMQ
RABBITMQ_USER=bitwarden
RABBITMQ_PASS=RabbitMQPassword123!

# SMTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=user@example.com
SMTP_PASSWORD=SmtpPassword123!

Security: Never commit .env files to version control. Add to .gitignore.

Validation

Test configuration after setting environment variables:

# Print effective configuration (redacted)
docker exec bitwarden-api dotnet run --project /app/Api.dll --print-config

# Check specific setting
docker exec bitwarden-api env | grep globalSettings__sqlServer__connectionString

# Verify service starts without errors
docker logs bitwarden-api

Security Best Practices

Use Secrets Management

Store sensitive values in:

Docker secrets
Kubernetes secrets
Azure Key Vault
HashiCorp Vault
AWS Secrets Manager

Restrict Access

Limit who can view environment variables
Use read-only volumes for certificates
Rotate credentials regularly

Audit Logging

Log configuration changes
Monitor secret access
Alert on configuration errors

Validation

Validate on startup
Use strong passwords
Test in staging first

Next Steps

Configuration

Learn about appsettings.json configuration

Docker Deployment

Deploy with Docker Compose

SSL Certificates

Configure certificates

Troubleshooting

Resolve configuration issues

Documentation Index

​Overview

​Variable Naming Convention

​Core Configuration

​Global Settings

​Database Configuration

​Certificate Configuration

​Storage Configuration

​Mail Configuration

​Service URLs

​Message Bus Configuration

​Cache Configuration

​Service-Specific Variables

​API Service

​Identity Service

​Notifications Service

​SSO Service

​ASP.NET Core Variables

​Logging Configuration

​Docker Compose Example

​Environment File

​Validation

​Security Best Practices

Use Secrets Management

Restrict Access

Audit Logging

Validation

​Next Steps

Configuration

Docker Deployment

SSL Certificates

Troubleshooting

Overview

Variable Naming Convention

Core Configuration

Global Settings

Database Configuration

Certificate Configuration

Storage Configuration

Mail Configuration

Service URLs

Message Bus Configuration

Cache Configuration

Service-Specific Variables

API Service

Identity Service

Notifications Service

SSO Service

ASP.NET Core Variables

Logging Configuration

Docker Compose Example

Environment File

Validation

Security Best Practices

Next Steps