Skip to main content

​
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=[email protected]
​
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=[email protected]
​
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=[email protected]
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

Build docs developers (and LLMs) love

Get started for freeTalk to us