### Bitwarden Standard Deployment via Cloud-Init

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

This example illustrates deploying the standard Bitwarden setup using the `bitwarden.sh` script, typically invoked after initial instance provisioning.

```bash
#!/bin/bash

# Download the Bitwarden installation script
curl -Lso bitwarden.sh https://bitwarden.sh
chmod 700 bitwarden.sh

# Run the installation script for the standard multi-container setup
./bitwarden.sh install

echo "Bitwarden Standard deployed successfully."
```

--------------------------------

### Bitwarden Lite Deployment via Cloud-Init

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

This example shows how Bitwarden Lite can be deployed as part of a cloud-init first-boot script. It demonstrates pulling the Docker image and running the single-container setup.

```bash
#!/bin/bash

# Pull the latest Bitwarden Lite image
docker pull ghcr.io/bitwarden/lite:latest

# Start the container with mounted volumes
docker run -d \
  --name bitwarden \
  -v /opt/bitwarden/etc:/etc/bitwarden \
  -v /opt/bitwarden/vault:/data \
  -p 80:80 \
  -p 443:443 \
  ghcr.io/bitwarden/lite:latest

echo "Bitwarden Lite deployed successfully."
```

--------------------------------

### Install Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Initializes a new Bitwarden installation in a specified directory. If no directory is provided, it defaults to './bwdata'.

```bash
./bitwarden.sh install [output_directory]
```

```bash
./bitwarden.sh install /opt/bitwarden
```

--------------------------------

### Start or Restart Bitwarden Services

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Starts or restarts the Bitwarden services using the existing installation directory.

```bash
./bitwarden.sh start
```

```bash
./bitwarden.sh restart
```

--------------------------------

### Install and Manage Bitwarden Services

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Perform essential management tasks for a traditional Bitwarden deployment using the 'bitwarden.sh' script. This includes installation, starting, stopping, restarting, and updating services.

```bash
./bitwarden.sh install   # Interactive setup (domain, SSL, DB)
./bitwarden.sh start
./bitwarden.sh stop
./bitwarden.sh restart
./bitwarden.sh update    # Pull latest images
```

--------------------------------

### Install Bitwarden with Custom Output Directory

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Installs Bitwarden, allowing you to specify a custom directory for the installation files. The default is './bwdata'.

```bash
./bitwarden.sh install /custom/path
```

--------------------------------

### Bitwarden Installation CLI Commands

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

These commands are used to manage the Bitwarden installation via the `bitwarden.sh` script. They cover initialization, starting/stopping services, updating, and uninstallation.

```bash
install
start / restart
stop
update
rebuild
updateconf
updatedb
renewcert
updaterun
updateself
uninstall
compresslogs
help
```

--------------------------------

### Invoke Bitwarden Installer

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Executes the appropriate Bitwarden installation script based on the selected edition ('standard' or 'lite').

```bash
if [ "$EDITION" = "standard" ]; then
    /opt/bitwarden/install-standard.sh
else
    /opt/bitwarden/install-lite.sh
fi
```

--------------------------------

### Verify Installation Directory Does Not Exist

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Checks if the specified output directory for Bitwarden installation exists. Throws an error if it does, indicating a potential pre-existing installation.

```powershell
function Test-Output-Dir-Not-Exists {
    if (Test-Path -Path "$output\docker") {
        throw "Looks like Bitwarden is already installed at $output."
    }
}
```

--------------------------------

### docker-compose.override.yml Example

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

YAML configuration for local overrides to the standard Docker Compose setup. Used for custom port mappings, volume mounts, and environment variables.

```yaml
export COMPOSE_FILE="$DOCKER_DIR/docker-compose.yml:$DOCKER_DIR/docker-compose.override.yml"
```

--------------------------------

### Make Marketplace Scripts Executable

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Sets execute permissions for various startup and setup scripts used in the Bitwarden marketplace image.

```bash
chmod +x /var/lib/cloud/scripts/per-instance/001_onboot
chmod +x /etc/update-motd.d/99-bitwarden-welcome
chmod +x /opt/bitwarden/setup-wizard.sh
chmod +x /opt/bitwarden/install-standard.sh
chmod +x /opt/bitwarden/install-lite.sh
```

--------------------------------

### Example Docker Run Command

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

This command demonstrates how to run the Bitwarden Lite container, mapping ports, mounting volumes for persistent data, and using an environment file for configuration.

```bash
docker run -d \
  --name bitwarden \
  -p 8080:8080 \
  -p 8443:8443 \
  -v /data/bitwarden/config:/etc/bitwarden \
  -v /data/bitwarden/logs:/var/log/bitwarden \
  -v /data/bitwarden/attachments:/etc/bitwarden/attachments \
  --env-file settings.env \
  ghcr.io/bitwarden/lite:2026.6.0
```

--------------------------------

### Start Supervisord Process Manager

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Starts the supervisord process manager, optionally using 'su-exec' for privilege dropping if available, to manage all enabled Bitwarden services.

```bash
if command -v su-exec >/dev/null 2>&1; then
  exec su-exec $PUID:$PGID /usr/bin/supervisord
else
  exec /usr/bin/supervisord
fi
```

--------------------------------

### Check if Cloud-Init is Installed

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Verifies if the cloud-init utility is available on the system. This is used for first-boot customization.

```bash
if hash cloud-init 2>/dev/null; then
  echo -en "\e[32m[PASS]\e[0m Cloud-init is installed.\n"
fi
```

--------------------------------

### Verify Installation Directory Exists

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Checks if the specified output directory for Bitwarden installation exists. Throws an error if it does not.

```powershell
function Test-Output-Dir-Exists {
    if (!(Test-Path -Path $output)) {
        throw "Cannot find a Bitwarden installation at $output."
    }
}
```

--------------------------------

### Supervisord Configuration for a Service

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Example INI configuration for a .NET service within Bitwarden Lite's supervisord setup. Specifies command, logging, and restart behavior.

```ini
[program:{service}]
command=/app/{Service}/{Service}.dll
directory=/app/{Service}
autostart=true
autorestart=true
priority=20
stdout_logfile=/var/log/bitwarden/{service}.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5
redirect_stderr=true
```

--------------------------------

### Error: Service Failed to Start

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

When a specific service fails to start, it often points to an invalid configuration or unmet dependencies. Check the logs for the specific service using `docker-compose logs X`.

```text
"Service X failed to start"
```

--------------------------------

### Error: Bitwarden Installation Not Found

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

This error occurs when the installation commands cannot locate an existing Bitwarden installation. Ensure you have run the `install` command first.

```text
"Cannot find a Bitwarden installation"
```

--------------------------------

### Initialize Bitwarden Configuration and Containers

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Initializes Bitwarden configuration and Docker containers. It prompts for domain, database name, and Let's Encrypt settings, then runs the setup container to generate configuration files.

```bash
function install() {
    # Interactive prompts for domain, database, and Let's Encrypt
}
```

--------------------------------

### Marketplace Image Build Scripts

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Scripts used for building consistent VM images across cloud providers. Includes setup, firewall rules, cleanup, and platform-specific validation.

```bash
CommonMarketplace/scripts/01-setup-first-run.sh
```

```bash
CommonMarketplace/scripts/02-ufw-bitwarden.sh
```

```bash
CommonMarketplace/scripts/90-cleanup.sh
```

```bash
{Platform}Marketplace/scripts/99-img-check.sh
```

--------------------------------

### Create Bitwarden Installation Directory

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Creates a directory within the output path if it does not already exist. It ensures that parent directories are also created as needed.

```bash
function createDir() {
    if [ ! -d "${OUTPUT_DIR}/$1" ]
    then
        echo "Creating directory $OUTPUT_DIR/$1"
        mkdir -p $OUTPUT_DIR/$1
    fi
}
```

--------------------------------

### Check Docker Compose Plugin Installation

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Ensures the Docker Compose v2 plugin is installed and functional. Standalone v1 is not supported.

```bash
if docker compose version > /dev/null 2>&1; then
  echo -en "\e[32m[PASS]\e[0m Docker Compose plugin is installed.\n"
fi
```

--------------------------------

### Check if Docker is Installed

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Verifies that Docker is installed and accessible in the system's PATH. This is a prerequisite for running Bitwarden containers.

```bash
if hash docker 2>/dev/null; then
  echo -en "\e[32m[PASS]\e[0m Docker is installed.\n"
fi
```

--------------------------------

### Remove Setup Wizard Trigger Script

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Cleans up by removing the script that triggers the setup wizard on first login, preventing it from running again.

```bash
rm -f /etc/profile.d/bitwarden-first-login.sh
```

--------------------------------

### UFW Firewall Setup Script

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Shell script for configuring the Uncomplicated Firewall (UFW) to harden VM network security for Bitwarden.

```bash
CommonMarketplace/scripts/02-ufw-bitwarden.sh
```

--------------------------------

### Install CA Certificate

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Installs the Bitwarden SSL certificate and optionally a custom CA certificate into the system's trusted CA store. This is done if BW_ENABLE_SSL is true.

```bash
if [ "$BW_ENABLE_SSL" = "true" ]; then
  cp /etc/bitwarden/${BW_SSL_CERT:-ssl.crt} /usr/local/share/ca-certificates/bitwarden.crt
  if [ -f /etc/bitwarden/${BW_SSL_CA_CERT:-ca.crt} ]; then
    cp /etc/bitwarden/${BW_SSL_CA_CERT:-ca.crt} /usr/local/share/ca-certificates/bitwarden-ca.crt
  fi
  update-ca-certificates >/dev/null
fi
```

--------------------------------

### Start Log Rotation

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Launches the log rotation script in the background to manage Nginx log file sizes daily.

```bash
/bin/sh -c "/logrotate.sh loop >/dev/null 2>&1 &"
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Brings all Bitwarden Docker Compose services online in detached mode. It ensures necessary configurations and volumes are set up beforehand.

```bash
function dockerComposeUp() {
    dockerComposeFiles
    dockerComposeVolumes
    $dccmd up -d
}
```

--------------------------------

### Dockerfile Packages Installation

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Installs essential packages required for the Bitwarden Lite container. This includes utilities for SSL, HTTP, JSON processing, web serving, cryptography, process management, and more.

```dockerfile
RUN apk add --no-cache \
    ca-certificates \
    curl \
    jq \
    nginx \
    openssl \
    supervisor \
    tzdata \
    unzip \
    su-exec \
    icu-libs \
    gcompat
```

--------------------------------

### Run Bitwarden Lite Locally with Docker Compose

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Set up and run Bitwarden Lite services locally using Docker Compose. This involves copying and editing the 'settings.env' file, starting services, monitoring logs, and stopping them.

```bash
cd bitwarden-lite/
# 1. Copy and edit settings.env
# 2. Start services
docker-compose up -d
docker-compose logs -f bitwarden
docker-compose down
```

--------------------------------

### View Global Environment Variables

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Displays all environment variables configured for the Bitwarden installation, typically found in the global.override.env file. This is useful for verifying configuration settings.

```bash
# List all environment variables
cat bwdata/env/global.override.env
```

--------------------------------

### Check Docker and Docker Compose Versions

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Verifies that Docker and Docker Compose are installed and accessible in the environment. Essential for ensuring the containerization platform is ready.

```bash
# Verify Docker/Docker Compose
docker --version
docker compose version
```

--------------------------------

### Bitwarden Data Directory Structure

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/02-configuration.md

The standard file structure for a traditional Bitwarden self-hosted deployment, created by the 'bitwarden.sh install' script.

```tree
bwdata/
├── env/
│   ├── uid.env                  # PUID, PGID
│   ├── global.env               # Application configuration
│   ├── global.override.env       # Customizations
│   └── [service].override.env    # Per-service configs
├── docker/
│   ├── docker-compose.yml       # Service definitions
│   └── docker-compose.override.yml  # Local customizations (optional)
├── core/
│   ├── attachments/             # User file attachments
│   └── vault.db                 # SQLite database (if using SQLite)
├── logs/
│   ├── admin/
│   ├── api/
│   ├── events/
│   ├── icons/
│   ├── identity/
│   ├── mssql/
│   ├── nginx/
│   ├── notifications/
│   ├── sso/
│   └── portal/
├── mssql/
│   ├── data/                    # SQL Server database files (if using MSSQL)
│   └── backups/
├── letsencrypt/                 # Let's Encrypt certificates (if configured)
│   └── live/{domain}/
│       ├── fullchain.pem
│       └── privkey.pem
└── scripts/
    └── run.sh                   # Downloaded runtime orchestrator
```

--------------------------------

### Error: Docker Compose Not Found

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

This error indicates that Docker or Docker Compose is not installed or not accessible in the system's PATH. Ensure Docker Desktop or Docker Engine with Compose plugin is installed.

```text
"Neither 'docker compose' nor 'docker-compose'"
```

--------------------------------

### Nginx Reverse Proxy Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Example Nginx configuration for proxying traffic to different Bitwarden services.

```nginx
upstream api {
  server localhost:5001;
}

upstream identity {
  server localhost:5005;
}

vault {
  server localhost:8080;
}

server {
  listen 8080;
  listen [::]:8080;
  
  server_name _;
  
  location /identity { proxy_pass http://identity; }
  location /api { proxy_pass http://api; }
  location / { proxy_pass http://vault; }
}

server {
  listen 8443 ssl;
  listen [::]:8443 ssl;
  
  ssl_certificate /etc/bitwarden/ssl.crt;
  ssl_certificate_key /etc/bitwarden/ssl.key;
  
  # Similar upstream blocks and locations
}
```

--------------------------------

### Update Bitwarden Configuration Files

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Updates the configuration files for the Bitwarden installation without restarting the services.

```bash
./bitwarden.sh updateconf
```

--------------------------------

### Debug Bitwarden Docker Compose Logs

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Tail logs for all services in a Docker Compose setup, or for a specific service like 'api'. This is useful for diagnosing startup issues.

```bash
docker-compose logs -f
```

```bash
docker-compose logs -f api
```

--------------------------------

### Bitwarden Docker Compose Orchestrator Functions

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Functions provided by the `run.sh` script for orchestrating Docker Compose services. Use these for interactive setup, service management, and maintenance tasks.

```bash
install()
dockerComposeUp()
dockerComposeDown()
dockerComposePull()
updateDatabase()
updateLetsEncrypt()
dockerPrune()
createDir()
```

--------------------------------

### Bitwarden Lite Environment File Basic Syntax

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/02-configuration.md

Demonstrates the basic syntax for environment files used in Bitwarden Lite, including comments, key-value pairs, and handling of quoted values.

```bash
# Comments start with #
KEY=value

# No spaces around =
DOMAIN=bitwarden.example.com

# Quoted values
PASSWORD="my!complex@password"

# Unquoted values without special characters
SIMPLE_VALUE=true
```

--------------------------------

### Display Help for Bitwarden CLI

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Shows the list of available commands for the bitwarden.sh script. No parameters are required.

```bash
./bitwarden.sh help
```

--------------------------------

### Check Cloud-Init First-Boot Script

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Ensures the essential cloud-init first-boot script is present and executable at the expected location.

```bash
if [ -x /var/lib/cloud/scripts/per-instance/001_onboot ]; then
  echo -en "\e[32m[PASS]\e[0m Cloud-init first-boot script is present and executable.\n"
else
  echo -en "\e[41m[FAIL]\e[0m Cloud-init first-boot script not found at /var/lib/cloud/scripts/per-instance/001_onboot.\n"
fi
```

--------------------------------

### Configure Database Provider and Connection Strings

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Sets the active database provider and exports connection strings for various database types if they are not already configured.

```bash
export globalSettings__databaseProvider=$BW_DB_PROVIDER
export globalSettings__mysql__connectionString=${globalSettings__mysql__connectionString:-$MYSQL_CONNECTION_STRING}
export globalSettings__postgreSql__connectionString=${globalSettings__postgreSql__connectionString:-$POSTGRESQL_CONNECTION_STRING}
export globalSettings__sqlServer__connectionString=${globalSettings__sqlServer__connectionString:-$SQLSERVER_CONNECTION_STRING}
export globalSettings__sqlite__connectionString=${globalSettings__sqlite__connectionString:-$SQLITE_CONNECTION_STRING}
```

--------------------------------

### Download Runtime Script (run.sh)

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Downloads the run.sh script required for the current platform. The download URL is provided. Exits with an error code on failure.

```bash
#### downloadRunFile()

Downloads the runtime script (`run.sh`) for the current platform.

**Download URL**: `https://func.bitwarden.com/api/dl/?app=self-host&platform=linux&variant=run`

Returns exit code 0 on success (HTTP 200-299), otherwise exits with error.
```

--------------------------------

### Uninstall Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Removes a Bitwarden installation completely, including containers and volumes.

```bash
./bitwarden.sh uninstall
```

--------------------------------

### Interactive Edition Selection

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Prompts the user to select either the 'standard' or 'lite' deployment edition. The selection is saved to a file.

```bash
while true; do
    read -rp "  Enter selection [1 or 2]: " SELECTION || exit 0
    case "$SELECTION" in
        1)
            EDITION="standard"
            break
            ;;
        2)
            EDITION="lite"
            break
            ;;
        *)
            echo "  Please enter 1 or 2."
            ;;
    esac
done
```

--------------------------------

### Update Bitwarden Database Schema

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Updates the database schema and data for the Bitwarden installation.

```bash
./bitwarden.sh updatedb
```

--------------------------------

### Build and Scan Bitwarden Lite Locally

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Build the Bitwarden Lite Docker image for local use and scan it for vulnerabilities using Grype. Ensure Docker buildx is configured for multi-platform builds.

```bash
docker buildx build --platform linux/amd64 -t bitwarden/lite:local bitwarden-lite/
```

```bash
grype bitwarden/lite:local
```

--------------------------------

### Build Bitwarden Lite Docker Image

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Build the Bitwarden Lite Docker image locally. Navigate to the 'bitwarden-lite' directory and use 'docker buildx build' to create the image tagged 'bitwarden/lite:local'.

```bash
cd bitwarden-lite/
docker buildx build --platform linux/amd64 -t bitwarden/lite:local .
```

--------------------------------

### Rebuild Bitwarden Docker Images

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Rebuilds the Docker images for the current Bitwarden installation without updating the versions.

```bash
./bitwarden.sh rebuild
```

--------------------------------

### Renew Bitwarden SSL/TLS Certificates

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Renews the SSL/TLS certificates for the Bitwarden installation, primarily used for Let's Encrypt.

```bash
./bitwarden.sh renewcert
```

--------------------------------

### Test Database Connection

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Use this command from within a container to verify connectivity to the database server and check credentials. Ensure environment variables like BW_DB_SERVER, BW_DB_USERNAME, and BW_DB_PASSWORD are set.

```bash
# From container, test database connection
mysql -h$BW_DB_SERVER -u$BW_DB_USERNAME -p$BW_DB_PASSWORD -e "SELECT 1"
```

--------------------------------

### Required Environment Variables for Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

These environment variables are mandatory for a Bitwarden installation. Ensure they are correctly set in your configuration, typically in `settings.env`.

```env
BW_DOMAIN=bitwarden.example.com
BW_DB_PROVIDER=mysql
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=(strong password)
BW_INSTALLATION_ID=00000000-0000-0000-0000-000000000000
BW_INSTALLATION_KEY=(from bitwarden.com/host)
```

--------------------------------

### Deploy Bitwarden Lite with Docker Run

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

This script deploys a single-container Bitwarden Lite instance using `docker run`. It handles configuration directory creation, environment file generation, image pulling, and container startup with volume mounts.

```bash
#!/bin/bash

# Create configuration directories
mkdir -p /opt/bitwarden/etc
mkdir -p /opt/bitwarden/vault

# Generate settings.env from user input (example, replace with actual input mechanism)
cat <<EOF > /opt/bitwarden/etc/settings.env
# Bitwarden Lite Settings
ADMIN_EMAIL="admin@example.com"
WEBSOCKET_EMAIL="ws@example.com"
# Add other necessary settings here
EOF

# Pull the latest Bitwarden Lite image
docker pull ghcr.io/bitwarden/lite:latest

# Start the container with mounted volumes
docker run -d \
  --name bitwarden \
  -v /opt/bitwarden/etc:/etc/bitwarden \
  -v /opt/bitwarden/vault:/data \
  -p 80:80 \
  -p 443:443 \
  ghcr.io/bitwarden/lite:latest

echo "Bitwarden Lite deployed successfully."
```

--------------------------------

### Enable Verbose Shell Tracing in Entrypoint

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Add 'set -x' to the entrypoint.sh script to enable verbose shell tracing. This will print each command as it's executed, aiding in debugging script logic.

```bash
set -x
```

--------------------------------

### Create Bitwarden User and Group

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Sets up a dedicated 'bitwarden' user and group with specified PUID and PGID. This ensures the service runs with appropriate permissions.

```bash
PGID="${PGID:-1000}"
addgroup -g $PGID bitwarden

PUID="${PUID:-1000}"
adduser -D -H -u $PUID -G bitwarden bitwarden
```

--------------------------------

### Test Database Connectivity

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Executes a simple SQL query against the database service ('db') using `sqlcmd` to verify connectivity. Assumes default credentials.

```bash
docker-compose exec api sqlcmd -S db -U sa -P password -Q "SELECT 1"
```

--------------------------------

### Run Bitwarden Lite Docker Container

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Deploys the Bitwarden Lite single-container instance. Ensure you have a `settings.env` file with necessary variables. Access the instance via `http://localhost:8080`.

```bash
docker run -d --name bitwarden \
  -p 8080:8080 \
  -v /data/config:/etc/bitwarden \
  --env-file settings.env \
  ghcr.io/bitwarden/lite:2026.6.0
```

--------------------------------

### Check HTTPS Connectivity

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Performs an HTTP HEAD request to the specified domain to check if the web server is responding and accessible over HTTPS. Useful for verifying network and SSL setup.

```bash
# Verify connectivity
curl -I https://bitwarden.example.com
```

--------------------------------

### Update Bitwarden Database Schema

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Runs database schema migrations and updates. Detects if using the included MSSQL container and connects the setup container to the MSSQL container network if necessary.

```bash
function updateDatabase() {
    pullSetup
    dockerComposeFiles

    if grep -q 'Data Source=tcp:mssql,1433' "$ENV_DIR/global.override.env"
    then
        MSSQL_ID=$($dccmd ps -q mssql)
        local docker_network_args="--network container:$MSSQL_ID"
    fi

    docker run -i --rm --name setup $docker_network_args \
        -v $OUTPUT_DIR:/bitwarden --env-file $ENV_DIR/uid.env ghcr.io/bitwarden/setup:$COREVERSION \
        /app/Setup -update 1 -db 1 -os $OS -corev $COREVERSION -webv $WEBVERSION -keyconnectorv $KEYCONNECTORVERSION
}
```

--------------------------------

### Service Enablement in Bitwarden Lite

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Bash script snippet demonstrating how environment variables control the enablement of .NET services in Bitwarden Lite via supervisord configuration.

```bash
# Services controlled by BW_ENABLE_* env vars in settings.env
# entrypoint.sh reads these and enables/disables supervisord .ini files
if [ "$BW_ENABLE_ADMIN" = "true" ]; then
    # Enable admin.ini in supervisord
fi
```

--------------------------------

### Generate Configuration Files

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Executes the Handlebars template engine to generate configuration files for Nginx, Supervisor, and other components based on environment variables.

```bash
/usr/local/bin/hbs
```

--------------------------------

### Bitwarden Lite Environment File Special Handling

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/02-configuration.md

Explains special handling rules for environment files in Bitwarden Lite, focusing on spaces and special characters within values, and noting the absence of variable expansion.

```text
- **Spaces in values**: Must be quoted
- **Special characters** (`$`, backticks, etc.): Must be escaped or quoted
- **No variable expansion**: Unlike shell scripts, `$VAR` is treated literally (not expanded)
```

--------------------------------

### Configure UFW Firewall for Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Sets up the Uncomplicated Firewall (UFW) to allow SSH and Bitwarden-specific ports, then enables the firewall.

```bash
#!/bin/sh

ufw allow ssh
ufw allow 'Bitwarden'
ufw --force enable
```

--------------------------------

### Test PostgreSQL Database Connection

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Attempt a simple query to verify connectivity to the PostgreSQL database from within the container.

```bash
docker-compose exec db psql -U $USER -c "SELECT 1"
```

--------------------------------

### Enable/Disable Bitwarden Services

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Demonstrates how to toggle specific Bitwarden services using environment variables. These flags control service enablement without rebuilding images.

```bash
BW_ENABLE_SSO=true    # Enable SSO service
```

```bash
BW_ENABLE_SCIM=false  # Disable SCIM service
```

--------------------------------

### Bitwarden Self-Host System Architecture Diagram

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Illustrates the flow from upstream repositories to various deployment targets, including traditional Docker Compose, Bitwarden Lite, and marketplace VM images.

```text
Upstream Repos (bitwarden/server, bitwarden/clients, bitwarden/key-connector)
         |
         | version.json tracks upstream versions
         v
    Release Pipeline (release.yml)
         |
    ┌────┴────────────────────┬──────────────────────┐
    |                         |                      |
    v                         v                      v
 Traditional              Bitwarden Lite         Marketplace Images
 (14 Docker images        (single container)     (Packer-built VMs)
  pushed to ghcr.io)           |
    |                         |              ┌────────┼────────┐
    v                         v              v        v        v
 bitwarden.sh/ps1     docker-compose.yml    AWS    Azure    DigitalOcean
 + run.sh/ps1         + settings.env        AMI    SIG      Droplet
 + Docker Compose     + entrypoint.sh

```

--------------------------------

### View Bitwarden Environment Variables

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

Displays the content of the global override environment file for Bitwarden. This helps in verifying configuration settings.

```bash
cat bwdata/env/global.override.env
```

--------------------------------

### Generate SQL Server Connection String

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Constructs a SQL Server connection string using environment variables, including server, port, database, user, password, and SSL settings.

```bash
SQLSERVER_CONNECTION_STRING="Server=$BW_DB_SERVER,${BW_DB_PORT:-1433};Database=$BW_DB_DATABASE;User Id=$BW_DB_USERNAME;Password=$BW_DB_PASSWORD;Encrypt=True;TrustServerCertificate=True"
```

--------------------------------

### Verify Database Connectivity with sqlcmd

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Connects to the SQL Server database using sqlcmd to verify connectivity and authentication. Requires the SA_PASSWORD environment variable to be set.

```bash
# Verify database
docker-compose exec mssql sqlcmd -S localhost -U sa -P $SA_PASSWORD -Q "SELECT 1"
```

--------------------------------

### Version Tracking Configuration

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

JSON file used as a single source of truth for upstream dependency versions in Bitwarden.

```json
{
  "coreVersion": "2026.3.1",
  "webVersion": "2026.3.0",
  "keyConnectorVersion": "2025.11.0"
}
```

--------------------------------

### Test MySQL Database Connection

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Attempt a simple query to verify connectivity to the MySQL database from within the container.

```bash
docker-compose exec db mysql -u$USER -p -e "SELECT 1"
```

--------------------------------

### Create Bitwarden User and Add to Docker Group

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Creates a dedicated 'bitwarden' user with a home directory and adds them to the 'docker' group for container management.

```bash
useradd -m -s /bin/bash bitwarden
usermod -aG docker bitwarden
```

--------------------------------

### Create Persistent Data Directories

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/01-cli-reference.md

Creates the necessary directory structure for persistent data and logs required by Bitwarden Docker containers. This includes directories for core data, attachments, and various service logs.

```bash
function dockerComposeVolumes() {
    createDir "core"
    createDir "core/attachments"
    createDir "logs/admin"
    createDir "logs/api"
    createDir "logs/events"
    createDir "logs/icons"
    createDir "logs/identity"
    createDir "logs/mssql"
    createDir "logs/nginx"
    createDir "logs/notifications"
    createDir "logs/sso"
    createDir "logs/portal"
    createDir "mssql/backups"
    createDir "mssql/data"
}
```

--------------------------------

### View Bitwarden Container Logs

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Follows the logs of the main Bitwarden service container in a traditional deployment. Use Ctrl+C to exit the log stream.

```bash
# Traditional deployment
docker-compose logs -f bitwarden
```

--------------------------------

### Common Optional Environment Variables for Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

These optional environment variables allow for customization of Bitwarden's behavior, such as enabling SSL, SSO, or configuring ports. Defaults are provided where applicable.

```env
BW_ENABLE_SSL=false
BW_ENABLE_SSO=false
BW_ENABLE_SCIM=false
BW_ENABLE_EVENTS=false
BW_PORT_HTTP=8080
BW_PORT_HTTPS=8443
PUID=1000
PGID=1000
```

--------------------------------

### Generate PostgreSQL Connection String

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Constructs a PostgreSQL connection string using environment variables for server, port, database, username, and password.

```bash
POSTGRESQL_CONNECTION_STRING="Host=$BW_DB_SERVER;Port=${BW_DB_PORT:-5432};Database=$BW_DB_DATABASE;Username=$BW_DB_USERNAME;Password=$BW_DB_PASSWORD"
```

--------------------------------

### Bitwarden Lite Version Manifest Format

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/02-configuration.md

Shows the structure of the version manifest file (version.json) used in Bitwarden Lite, detailing the format and how versions are propagated.

```json
{
  "versions": {
    "coreVersion": "2026.6.0",
    "webVersion": "2026.6.0",
    "keyConnectorVersion": "2025.11.0"
  }
}
```

--------------------------------

### View Bitwarden Lite Container Logs

Source: https://github.com/bitwarden/self-host/blob/main/CLAUDE.md

Use this command to stream logs from the Bitwarden Lite container. This is useful for real-time debugging of application behavior.

```bash
docker-compose logs -f bitwarden
```

--------------------------------

### Bitwarden Lite Container Directory Structure

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/02-configuration.md

Overview of the directory structure within the bitwarden/lite container, showing the locations of configuration files, databases, certificates, application services, supervisor configurations, Nginx settings, and log files.

```text
/etc/bitwarden/
├── vault.db                     # SQLite database (if using SQLite)
├── identity.pfx                 # Identity Server certificate
├── ssl.crt                      # SSL certificate (if BW_ENABLE_SSL=true)
├── ssl.key                      # SSL private key (if BW_ENABLE_SSL=true)
├── ca.crt                       # CA certificate (if BW_ENABLE_SSL_CA=true)
├── data-protection/             # Data protection keys
├── attachments/                 # User file attachments
├── attachments/send/            # Send file attachments
└── licenses/                    # License files

/app/
├── Admin/                       # Admin portal service
├── Api/                         # Core API service
├── Events/                      # Events service
├── Icons/                       # Icons service
├── Identity/                    # Identity Server service
├── Notifications/               # Notifications service
├── Scim/                        # SCIM service
└── Sso/                         # SSO service

/etc/supervisor.d/
├── admin.ini                    # Admin service configuration
├── api.ini                      # API service configuration
├── events.ini                   # Events service configuration
├── icons.ini                    # Icons service configuration
├── identity.ini                 # Identity service configuration
├── notifications.ini            # Notifications service configuration
├── scim.ini                     # SCIM service configuration
└── sso.ini                      # SSO service configuration

/etc/nginx/
└── http.d/
    └── default.conf             # Nginx proxy configuration

/var/log/bitwarden/
├── admin.log
├── api.log
├── events.log
├── icons.log
├── identity.log
├── notifications.log
├── scim.log
└── sso.log
```

--------------------------------

### Dockerfile Application Binaries Copy

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Copies application binaries from previously defined build stages into the final image. Each service's binaries are placed in a dedicated subdirectory under /app.

```dockerfile
COPY --from=admin-app /app /app/Admin
COPY --from=api-app /app /app/Api
COPY --from=events-app /app /app/Events
COPY --from=icons-app /app /app/Icons
COPY --from=identity-app /app /app/Identity
COPY --from=notifications-app /app /app/Notifications
COPY --from=scim-app /app /app/Scim
COPY --from=sso-app /app /app/Sso
COPY --from=web-app /app /app/Vault
```

--------------------------------

### Generate MySQL Connection String

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Constructs a MySQL connection string using environment variables for server, port, database, username, and password.

```bash
MYSQL_CONNECTION_STRING="server=$BW_DB_SERVER;port=${BW_DB_PORT:-3306};database=$BW_DB_DATABASE;user=$BW_DB_USERNAME;password=$BW_DB_PASSWORD"
```

--------------------------------

### Enable/Disable Supervisor Services

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Modifies Supervisor configuration files to enable or disable services by setting their 'autostart' parameter based on corresponding BW_ENABLE_* environment variables.

```bash
sed -i "s/autostart=true/autostart=${BW_ENABLE_ADMIN}/" /etc/supervisor.d/admin.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_API}/" /etc/supervisor.d/api.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_EVENTS}/" /etc/supervisor.d/events.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_ICONS}/" /etc/supervisor.d/icons.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_IDENTITY}/" /etc/supervisor.d/identity.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_NOTIFICATIONS}/" /etc/supervisor.d/notifications.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_SCIM}/" /etc/supervisor.d/scim.ini
sed -i "s/autostart=true/autostart=${BW_ENABLE_SSO}/" /etc/supervisor.d/sso.ini
```

--------------------------------

### Test MSSQL Database Connection

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Attempt a simple query to verify connectivity to the MSSQL database from within the container using sqlcmd.

```bash
docker-compose exec mssql sqlcmd -S localhost -U sa -P $SA_PASSWORD -Q "SELECT 1"
```

--------------------------------

### PowerShell Exception Handling for Directory Check

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Demonstrates how to use try/catch blocks in PowerShell to handle potential errors during directory checks.

```powershell
try {
    Test-Output-Dir-Exists
}
catch {
    Write-Error $_ 
    exit 1
}
```

--------------------------------

### Check Service Status with Docker Compose

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Lists the status of all services managed by Docker Compose for the Bitwarden deployment. Helps in identifying which services are running or have failed.

```bash
# Check service status
docker-compose ps
```

--------------------------------

### Error: BW_DOMAIN Not Set

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

This error indicates that the essential `BW_DOMAIN` environment variable is missing. Set this variable to your server's hostname in your configuration file (e.g., `settings.env`).

```text
"BW_DOMAIN not set"
```

--------------------------------

### Configure Vault Service URI (HTTP/HTTPS)

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Determines and exports the internal vault service URI based on the BW_ENABLE_SSL environment variable, using HTTPS with a specified port or HTTP with a default port.

```bash
if [ "$BW_ENABLE_SSL" = "true" ]; then
  export globalSettings__baseServiceUri__internalVault=https://localhost:${BW_PORT_HTTPS:-8443}
else
  export globalSettings__baseServiceUri__internalVault=http://localhost:${BW_PORT_HTTP:-8080}
fi
```

--------------------------------

### Generate SQLite Connection String

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Creates a SQLite connection string using the specified data source file path.

```bash
SQLITE_CONNECTION_STRING="Data Source=$BW_DB_FILE;"
```

--------------------------------

### Validate OS Version in Marketplace Image

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/04-marketplace-infrastructure.md

Checks if the operating system is Ubuntu 24.04 LTS, reporting a PASS or FAIL status. This is a final validation step for marketplace compliance.

```bash
if [[ $OS == "Ubuntu" ]] && [[ $VER == "24.04" ]]; then
  echo -en "\e[32m[PASS]\e[0m Supported OS detected: ${OS} ${VER}\n"
  ((PASS++))
else
  echo -en "\e[41m[FAIL]\e[0m ${OS} ${VER} is not the expected OS (Ubuntu 24.04)\n"
  ((FAIL++))
fi
```

--------------------------------

### Error: Database Connection Failure

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/README.md

This error signifies an issue connecting to the database. Verify that the `BW_DB_SERVER`, `BW_DB_USERNAME`, and `BW_DB_PASSWORD` environment variables are correctly configured and that the database is reachable.

```text
"Cannot connect to database"
```

--------------------------------

### Dockerfile Server App Stages

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/03-dockerfile-entrypoint.md

Defines Docker build stages for pulling pre-built .NET service containers. Each service (admin, api, events, etc.) is pulled from the specified SERVER_REGISTRY and SERVER_TAG.

```dockerfile
FROM ${SERVER_REGISTRY}/admin:${SERVER_TAG} AS admin-app
FROM ${SERVER_REGISTRY}/api:${SERVER_TAG} AS api-app
FROM ${SERVER_REGISTRY}/events:${SERVER_TAG} AS events-app
FROM ${SERVER_REGISTRY}/icons:${SERVER_TAG} AS icons-app
FROM ${SERVER_REGISTRY}/identity:${SERVER_TAG} AS identity-app
FROM ${SERVER_REGISTRY}/notifications:${SERVER_TAG} AS notifications-app
FROM ${SERVER_REGISTRY}/scim:${SERVER_TAG} AS scim-app
FROM ${SERVER_REGISTRY}/sso:${SERVER_TAG} AS sso-app
```

--------------------------------

### Test DNS Resolution

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/05-data-types-errors.md

Use nslookup to test if the bitwarden container can resolve domain names, such as the database service.

```bash
docker-compose exec bitwarden nslookup database.example.com
```