Complete configuration guide for self-hosted Bitwarden deployments. Covers environment variables, application settings, database configuration, SMTP setup, and production hardening.
Bitwarden configuration is managed through:
| Variable | Description | Example | Required |
|---|---|---|---|
BW_DOMAIN |
Domain name for Bitwarden instance | bitwarden.example.com |
✅ |
BW_INSTALLATION_ID |
Installation ID from bitwarden.com/host | xxxxxxxx-xxxx-... |
✅ |
BW_INSTALLATION_KEY |
Installation Key from bitwarden.com/host | xxxxxxxxxxxxxxxx |
✅ |
| Variable | Description | Default | Example |
|---|---|---|---|
BW_DB_PROVIDER |
Database provider | sqlite |
sqlite, postgresql, mysql |
BW_DB_CONNECTION_STRING |
External database connection string | – | Host=db;Database=bw;Username=bw;Password=secret |
SQLite (Default):
BW_DB_PROVIDER=sqlite
# Database stored in ./data/vault.db
PostgreSQL:
BW_DB_PROVIDER=postgresql
BW_DB_CONNECTION_STRING="Host=postgres;Database=bitwarden;Username=bw;Password=secret;Port=5432"
MySQL/MariaDB:
BW_DB_PROVIDER=mysql
BW_DB_CONNECTION_STRING="Server=mysql;Database=bitwarden;User=bw;Password=secret;Port=3306"
| Variable | Description | Default | Example |
|---|---|---|---|
BW_SMTP_HOST |
SMTP server hostname | – | smtp.example.com |
BW_SMTP_PORT |
SMTP server port | 587 |
587, 465, 25 |
BW_SMTP_SSL |
Use SSL for SMTP | false |
true, false |
BW_SMTP_STARTTLS |
Use STARTTLS | true |
true, false |
BW_SMTP_FROM |
From address for emails | – | bitwarden@example.com |
BW_SMTP_USERNAME |
SMTP authentication username | – | smtp-user |
BW_SMTP_PASSWORD |
SMTP authentication password | – | smtp-password |
Example SMTP Configuration:
# Gmail SMTP
BW_SMTP_HOST=smtp.gmail.com
BW_SMTP_PORT=587
BW_SMTP_SSL=false
BW_SMTP_STARTTLS=true
BW_SMTP_FROM=bitwarden@example.com
BW_SMTP_USERNAME=your-gmail@gmail.com
BW_SMTP_PASSWORD=your-app-password
# Office 365 SMTP
BW_SMTP_HOST=smtp.office365.com
BW_SMTP_PORT=587
BW_SMTP_SSL=false
BW_SMTP_STARTTLS=true
BW_SMTP_FROM=bitwarden@example.com
BW_SMTP_USERNAME=user@example.com
BW_SMTP_PASSWORD=your-password
| Variable | Description | Default | Example |
|---|---|---|---|
PUID |
Process user ID | 1000 |
1000 |
PGID |
Process group ID | 1000 |
1000 |
BW_ADMIN_TOKEN |
Admin API token | – | your-secure-token |
BW_INVITATIONS_ALLOWED |
Allow new invitations | true |
true, false |
| Variable | Description | Example |
|---|---|---|
globalSettings__domain |
Public domain URL | https://bitwarden.example.com |
globalSettings__installation__id |
Installation ID | xxxxxxxx-xxxx-... |
globalSettings__installation__key |
Installation Key | xxxxxxxxxxxxxxxx |
globalSettings__connectionStrings__database |
MSSQL connection string | Server=bw-mssql;Database=bitwarden;User=sa;Password=xxx;TrustServerCertificate=true |
globalSettings__connectionStrings__redis |
Redis connection string | bw-redis:6379,ssl=false,abortConnect=false |
Microsoft SQL Server (Required for Standard):
globalSettings__connectionStrings__database=Server=bw-mssql;Database=bitwarden;User=sa;Password=YourStrongPassword123!;TrustServerCertificate=true
Redis Configuration:
globalSettings__connectionStrings__redis=bw-redis:6379,ssl=false,abortConnect=false,password=redis-password
| Variable | Description | Example |
|---|---|---|
globalSettings__mail__smtp__host |
SMTP hostname | smtp.example.com |
globalSettings__mail__smtp__port |
SMTP port | 587 |
globalSettings__mail__smtp__ssl |
Use SSL | false |
globalSettings__mail__smtp__username |
SMTP username | smtp-user |
globalSettings__mail__smtp__password |
SMTP password | smtp-password |
globalSettings__mail__replyToEmail |
Reply-to email | noreply@example.com |
globalSettings__mail__fromAddress |
From email address | bitwarden@example.com |
globalSettings__baseServiceUri__internalApi=http://bw-api:8080
globalSettings__baseServiceUri__internalIdentity=http://bw-identity:8080
globalSettings__baseServiceUri__internalNotifications=http://bw-notifications:8080
globalSettings__baseServiceUri__internalEvents=http://bw-events:8080
globalSettings__baseServiceUri__internalAdmin=http://bw-admin:8080
globalSettings__baseServiceUri__internalSso=http://bw-sso:8080
Enable 2FA Providers:
# TOTP (Authenticator apps)
globalSettings__disableEmailToken=true
# YubiKey
globalSettings__yubico__clientId=your-yubi-client-id
globalSettings__yubico__key=your-yubi-secret-key
# Duo Security
globalSettings__duo__apiEnvironment=API
globalSettings__duo__akey=your-duo-akey
globalSettings__duo__ikey=your-duo-ikey
globalSettings__duo__skey=your-duo-skey
# WebAuthn/FIDO2
globalSettings__disableWebAuthn=false
# SAML Settings
globalSettings__saml__spEntityId=bitwarden
globalSettings__saml__spMetadataUrl=https://bitwarden.example.com/sso/metadata
globalSettings__saml__spAcsUrl=https://bitwarden.example.com/sso/acs
globalSettings__saml__spNameIdFormat=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
globalSettings__saml__spOutboundSigningAlgorithm=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
globalSettings__saml__spSigningBehavior=Always
globalSettings__saml__spMinIncomingSigningAlgorithm=rsa-sha256
globalSettings__saml__spWantAssertionsSigned=true
globalSettings__saml__spValidateCertificates=true
# IdP Settings (example for Keycloak)
globalSettings__saml__idpEntityId=https://idp.example.com/realms/myrealm
globalSettings__saml__idpBindingType=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
globalSettings__saml__idpSingleSignOnServiceUrl=https://idp.example.com/realms/myrealm/protocol/saml
globalSettings__saml__idpSingleLogoutServiceUrl=https://idp.example.com/realms/myrealm/protocol/saml
globalSettings__saml__idpX509PublicCert=MIIC...
# OIDC Settings
globalSettings__oidc__clientId=bitwarden-client
globalSettings__oidc__clientSecret=your-client-secret
globalSettings__oidc__authority=https://idp.example.com/realms/myrealm
globalSettings__oidc__metadataAddress=https://idp.example.com/realms/myrealm/.well-known/openid-configuration
globalSettings__oidc__scope=openid profile email
globalSettings__oidc__callbackPath=/sso/callback
Configure in Admin Console or via environment:
# Minimum password length
globalSettings__passwordPolicy__minLength=12
# Require uppercase
globalSettings__passwordPolicy__requireUpper=true
# Require lowercase
globalSettings__passwordPolicy__requireLower=true
# Require numbers
globalSettings__passwordPolicy__requireNumber=true
# Require special characters
globalSettings__passwordPolicy__requireSpecial=true
# Password expiration (days)
globalSettings__passwordPolicy__expirationDays=90
# Prevent password reuse
globalSettings__passwordPolicy__preventReuse=5
# Session timeout (minutes)
globalSettings__sessionTimeout=60
# Maximum session duration (hours)
globalSettings__maxSessionDuration=24
# Token lifetime (minutes)
globalSettings__tokenLifetimeMinutes=5
# Refresh token expiration (days)
globalSettings__refreshTokenExpirationDays=30
# API rate limiting
globalSettings__rateLimiting__enableRateLimiting=true
globalSettings__rateLimiting__rateLimitPeriod=60
globalSettings__rateLimiting__rateLimit=100
# Authentication rate limiting
globalSettings__rateLimiting__authRateLimitPeriod=60
globalSettings__rateLimiting__authRateLimit=10
# Local storage (default)
globalSettings__attachment__baseDirectory=/etc/bitwarden/core/Attachments
# Amazon S3
globalSettings__attachment__storageType=amazonS3
globalSettings__attachment__amazonS3__accessKeyId=AKIA...
globalSettings__attachment__amazonS3__secretAccessKey=secret
globalSettings__attachment__amazonS3__bucket=bitwarden-attachments
globalSettings__attachment__amazonS3__region=us-east-1
# Azure Blob Storage
globalSettings__attachment__storageType=azureBlob
globalSettings__attachment__azureBlob__connectionString=DefaultEndpointsProtocol=https;...
globalSettings__attachment__azureBlob__containerName=attachments
# Send file base directory
globalSettings__send__baseDirectory=/etc/bitwarden/core/Sends
# Maximum Send file size (bytes)
globalSettings__send__maxFileSize=52428800 # 50MB
# Send expiration (hours)
globalSettings__send__expirationHours=168 # 7 days
# Enable syslog
globalSettings__syslog__enabled=true
globalSettings__syslog__destination=udp://localhost:514
globalSettings__syslog__application=bitwarden
globalSettings__syslog__facility=LOCAL0
# Minimum log level
globalSettings__logging__minimumLevel=Information
# Log file path
globalSettings__logging__file__path=/var/log/bitwarden/bitwarden.log
# Log file size limit (MB)
globalSettings__logging__file__fileSizeLimitBytes=10485760 # 10MB
# Number of backup log files
globalSettings__logging__file__retainedFileCountLimit=5
# Maximum pool size
globalSettings__database__maxPoolSize=100
# Minimum pool size
globalSettings__database__minPoolSize=10
# Connection timeout (seconds)
globalSettings__database__connectionTimeout=30
# Redis cache expiration (minutes)
globalSettings__cache__expirationMinutes=60
# Enable distributed cache
globalSettings__cache__enableDistributedCache=true
# Maximum concurrent requests
globalSettings__maxConcurrentRequests=100
# Request timeout (seconds)
globalSettings__requestTimeoutSeconds=30
.env File# === Domain and Identity ===
BW_DOMAIN=bitwarden.example.com
BW_INSTALLATION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BW_INSTALLATION_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
# === Database (SQLite Default) ===
BW_DB_PROVIDER=sqlite
# === SMTP Configuration ===
BW_SMTP_HOST=smtp.example.com
BW_SMTP_PORT=587
BW_SMTP_SSL=false
BW_SMTP_STARTTLS=true
BW_SMTP_FROM=bitwarden@example.com
BW_SMTP_USERNAME=smtp-username
BW_SMTP_PASSWORD=smtp-password
# === System Settings ===
PUID=1000
PGID=1000
# === Optional: Admin API ===
# BW_ADMIN_TOKEN=your-secure-admin-token
# === Optional: Restrict Invitations ===
# BW_INVITATIONS_ALLOWED=false
docker-compose.yml Environmentservices:
bitwarden-api:
environment:
# === Required Settings ===
- ASPNETCORE_URLS=http://+:8080
- globalSettings__domain=https://bitwarden.example.com
- globalSettings__installation__id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- globalSettings__installation__key=xxxxxxxxxxxxxxxxxxxxxxxx
# === Database ===
- globalSettings__connectionStrings__database=Server=bw-mssql;Database=bitwarden;User=sa;Password=YourStrongPassword123!;TrustServerCertificate=true
- globalSettings__connectionStrings__redis=bw-redis:6379,ssl=false,abortConnect=false
# === Internal Service URLs ===
- globalSettings__baseServiceUri__internalApi=http://bw-api:8080
- globalSettings__baseServiceUri__internalIdentity=http://bw-identity:8080
- globalSettings__baseServiceUri__internalNotifications=http://bw-notifications:8080
- globalSettings__baseServiceUri__internalEvents=http://bw-events:8080
- globalSettings__baseServiceUri__internalAdmin=http://bw-admin:8080
- globalSettings__baseServiceUri__internalSso=http://bw-sso:8080
# === SMTP ===
- globalSettings__mail__smtp__host=smtp.example.com
- globalSettings__mail__smtp__port=587
- globalSettings__mail__smtp__ssl=false
- globalSettings__mail__smtp__username=smtp-username
- globalSettings__mail__smtp__password=smtp-password
- globalSettings__mail__replyToEmail=noreply@example.com
- globalSettings__mail__fromAddress=bitwarden@example.com
# === Security ===
- globalSettings__passwordPolicy__minLength=12
- globalSettings__passwordPolicy__requireUpper=true
- globalSettings__passwordPolicy__requireLower=true
- globalSettings__passwordPolicy__requireNumber=true
- globalSettings__passwordPolicy__requireSpecial=true
# === Logging ===
- globalSettings__logging__minimumLevel=Information
# === Performance ===
- globalSettings__maxConcurrentRequests=100
Access via: https://bitwarden.example.com/admin
Policy Configuration:
User Management:
Collections:
Groups:
SQLite (Lite):
# Backup vault.db
cp /opt/bitwarden-lite/data/vault.db /backup/vault.db.$(date +%Y%m%d)
PostgreSQL:
docker exec postgres pg_dump -U bitwarden bitwarden > /backup/bitwarden-$(date +%Y%m%d).sql
MSSQL (Standard):
docker exec bw-mssql /opt/mssql-tools/bin/sqlcmd \
-S localhost -U sa -P 'YourPassword' \
-Q "BACKUP DATABASE [bitwarden] TO DISK = '/var/opt/mssql/backup/bitwarden.bak'"
# Backup entire configuration
tar -czf /backup/bitwarden-config-$(date +%Y%m%d).tar.gz \
/opt/bitwarden-lite/data \
/opt/bitwarden/bw-data \
/etc/nginx/sites-available/bitwarden \
/etc/letsencrypt
# Check environment variables
docker compose config
# Verify container environment
docker compose exec bitwarden-lite env | grep BW_
# Test database connection
docker compose exec bw-mssql /opt/mssql-tools/bin/sqlcmd \
-S localhost -U sa -P 'YourPassword' \
-Q "SELECT name FROM sys.databases"
SMTP not working:
# Test SMTP connection
docker compose exec bitwarden-lite telnet smtp.example.com 587
Database connection failed:
# Check connection string
docker compose logs | grep -i "connection"
# Verify database is accessible
docker compose exec bw-api ping bw-mssql
SSL/TLS errors:
# Verify certificate
openssl s_client -connect bitwarden.example.com:443 -servername bitwarden.example.com
# Check certificate expiry
openssl x509 -in /etc/letsencrypt/live/bitwarden.example.com/fullchain.pem -noout -dates
Any questions?
Feel free to contact us. Find all contact information on our contact page.