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

boolean

default:"false"

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

globalSettings__selfHosted=true

string

default:"Bitwarden"

Display name for the installation.

globalSettings__siteName="My Company Vault"

string

required

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

globalSettings__projectName=Api

Database Configuration

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;"

string

Optional read replica connection string for read operations.

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

string

default:"sqlserver"

Database provider: sqlserver, postgres, or mysql.

globalSettings__databaseProvider=postgres

Certificate Configuration

string

SHA-1 thumbprint of Identity Server signing certificate.

globalSettings__identityServer__certificateThumbprint=ABC123DEF456789...

string

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

globalSettings__identityServer__certificatePath=/etc/bitwarden/identity_server.pfx

string

Password for Identity Server certificate PFX file.

globalSettings__identityServer__certificatePassword=your_password

string

SHA-1 thumbprint of Data Protection certificate.

globalSettings__dataProtection__certificateThumbprint=ABC123DEF456789...

Storage Configuration

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;"

string

Separate storage for attachments (optional).

globalSettings__attachment__connectionString="DefaultEndpointsProtocol=https;..."

string

Separate storage for Send files (optional).

globalSettings__send__connectionString="DefaultEndpointsProtocol=https;..."

Mail Configuration

string

required

Reply-to email address for system emails.

globalSettings__mail__replyToEmail=no-reply@example.com

string

SendGrid API key for email delivery.

globalSettings__mail__sendGridApiKey=SG.xxxxxxxxxx

string

SMTP server hostname.

globalSettings__mail__smtp__host=smtp.gmail.com

integer

default:"587"

SMTP server port.

globalSettings__mail__smtp__port=587

boolean

default:"true"

Enable SSL/TLS for SMTP.

globalSettings__mail__smtp__ssl=true

string

SMTP authentication username.

globalSettings__mail__smtp__username=user@example.com

string

SMTP authentication password.

globalSettings__mail__smtp__password=your_password

Service URLs

string

required

Public URL for API service.

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

string

required

Public URL for Identity service.

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

string

Public URL for Admin service.

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

string

Public URL for Notifications service.

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

string

Public URL for SSO service.

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

string

required

Public URL for web vault.

globalSettings__baseServiceUri__vault=https://vault.example.com

Message Bus Configuration

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"

boolean

default:"false"

Use RabbitMQ instead of Azure Service Bus.

globalSettings__serviceBus__useRabbitMq=true

Cache Configuration

string

Redis connection string for distributed caching.

globalSettings__redis__connectionString="redis:6379,password=your_password"

string

default:"memory"

Cache provider: memory, redis, or cosmos.

globalSettings__distributedCache__provider=redis

Service-Specific Variables

API Service

boolean

default:"true"

Enable rate limiting.

IpRateLimitOptions__EnableEndpointRateLimiting=true

string

default:"X-Forwarded-For"

Header containing real client IP (when behind proxy).

IpRateLimitOptions__RealIpHeader=X-Real-IP

Identity Service

string

Override issuer URI for tokens.

IdentityServerOptions__IssuerUri=https://identity.example.com

Notifications Service

string

Azure Notification Hub connection string.

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

string

Azure Notification Hub name.

globalSettings__notificationHub__hubName=bitwarden-hub

SSO Service

integer

default:"5"

SSO configuration cache lifetime.

SsoSettings__CacheLifetimeInMinutes=10

ASP.NET Core Variables

string

default:"Production"

Runtime environment: Development, Staging, or Production.

ASPNETCORE_ENVIRONMENT=Production

string

default:"http://+:5000"

URLs to listen on.

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

string

Path to Kestrel HTTPS certificate.

ASPNETCORE_Kestrel__Certificates__Default__Path=/etc/ssl/cert.pfx

string

Password for Kestrel HTTPS certificate.

ASPNETCORE_Kestrel__Certificates__Default__Password=your_password

Logging Configuration

string

default:"Information"

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

Logging__LogLevel__Default=Warning

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

​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