### install

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

Initializes a new Bitwarden installation at the specified output directory.

```APIDOC
## ./bitwarden.sh install

### Description
Initializes a new Bitwarden installation at the specified output directory. It validates the directory, downloads the necessary run script, and creates the required directory structure.

### Parameters
#### Positional Parameters
- **OUTPUT_DIR** (string) - Optional - Target directory for Bitwarden installation (Default: ./bwdata)

### Example
./bitwarden.sh install /opt/bitwarden
```

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

### Install Bitwarden

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

Initializes a new installation in the specified directory.

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

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

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

### Install Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Initializes a new installation with interactive prompts for domain and database configuration.

```bash
./run.sh install [OUTPUT_DIR] [COREVERSION] [WEBVERSION] [KEYCONNECTORVERSION]
```

```bash
./bitwarden.sh install
# Triggers: ./bwdata/scripts/run.sh install ./bwdata 2026.7.0 2026.7.0 2025.11.0
```

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

### start / restart

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

Starts or restarts a Bitwarden installation.

```APIDOC
## ./bitwarden.sh start / restart

### Description
Starts or restarts a Bitwarden installation using Docker Compose.

### Parameters
#### Positional Parameters
- **OUTPUT_DIR** (string) - Optional - Installation directory to restart (Default: ./bwdata)

### Example
./bitwarden.sh restart /opt/bitwarden
```

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

### Docker Installation Provisioner

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Installs Docker by setting up the official APT repository and GPG keys.

```bash
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get -qqy update
sudo apt-get -qqy -o Dpkg::Options::='--force-confdef' -o Dpkg::Options::='--force-confold' install ${var.docker_packages}
```

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

### Traditional Multi-Container Deployment Workflow

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

Visual representation of the multi-container setup process initiated by the installation script.

```text
User runs: ./bitwarden.sh install
    ↓
Downloads: run.sh from CDN
    ↓
Setup tool prompts for: domain, SSL, database
    ↓
Generates: docker-compose.yml with 10+ services
    ↓
Pulls images: Admin, API, Events, Icons, Identity, Notifications, SSO, Web, Nginx, Database
    ↓
Starts: All services via docker-compose up
    ↓
Result: Production-ready Bitwarden instance
```

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

### Install Multiple Bitwarden Instances

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

Commands to initialize separate Bitwarden installations in distinct directories for multi-instance hosting.

```bash
./bitwarden.sh install /opt/bitwarden-1
./bitwarden.sh install /opt/bitwarden-2
# Edit each docker-compose.override.yml to use different external ports
```

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

### 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
```

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

### Start or Restart Bitwarden

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

Manages the lifecycle of the Docker containers for the specified installation.

```bash
./bitwarden.sh start [OUTPUT_DIR]
./bitwarden.sh restart [OUTPUT_DIR]
```

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

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

### Marketplace VM Deployment Workflow

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

Visual representation of the cloud-init and setup wizard process for Marketplace VM images.

```text
User launches: Marketplace image (AWS/Azure/DigitalOcean)
    ↓
cloud-init runs: /var/lib/cloud/scripts/per-instance/001_onboot
    ↓
User SSH's into VM
    ↓
Shell sources: /etc/profile.d/bitwarden-first-login.sh
    ↓
User runs: /opt/bitwarden/setup-wizard.sh
    ↓
Wizard offers: Traditional or Lite deployment
    ↓
Runs: bitwarden.sh install or docker-compose up
    ↓
Result: Fully configured VM with running Bitwarden
```

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

### Build the Bitwarden Lite Image

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Example command to build the container with specific version tags.

```bash
docker build \
  --build-arg SERVER_TAG=2026.7.0 \
  --build-arg WEB_TAG=2026.7.0 \
  -t bitwarden/lite:2026.7.0 \
  bitwarden-lite/
```

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

### Configure Minimal Lite Deployment

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

Environment variable setup and startup command for a minimal Bitwarden Lite deployment.

```bash
# Create .env
export BW_DOMAIN=bitwarden.example.com
export BW_INSTALLATION_ID=<from bitwarden.com/host>
export BW_INSTALLATION_KEY=<from bitwarden.com/host>
export BW_DB_PROVIDER=mysql
export BW_DB_SERVER=db
export BW_DB_DATABASE=bitwarden_vault
export BW_DB_USERNAME=bitwarden
export BW_DB_PASSWORD=<strong-password>

# Start
docker-compose -f bitwarden-lite/docker-compose.yml up -d
```

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

### Installation Directory Layout

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

Visual representation of the default directory structure for a Bitwarden self-hosted instance.

```text
bwdata/                          # Installation root (default)
├── docker/
│   ├── docker-compose.yml      # Main compose file
│   ├── docker-compose.override.yml  # Local overrides (optional)
│   ├── nginx/
│   │   └── conf.d/
│   │       └── bitwarden.conf  # Generated nginx config
│   └── app/
│       └── AppSettings.json    # Application settings
├── env/
│   ├── .env                    # Environment variables
│   └── uid.env                 # Container user IDs
├── scripts/
│   ├── run.sh                  # Downloaded orchestration script
│   └── install.sh              # Old install script (removed after update)
├── core/
│   └── attachments/            # User file attachments
├── logs/
│   ├── admin/                  # Admin service logs
│   ├── api/                    # API service logs
│   ├── events/                 # Events service logs
│   ├── icons/                  # Icons service logs
│   ├── identity/               # Identity service logs
│   ├── mssql/                  # Database logs (SQL Server)
│   ├── nginx/                  # Web server logs
│   ├── notifications/          # Notifications service logs
│   ├── sso/                    # SSO service logs
│   └── portal/                 # Portal service logs
├── mssql/
│   └── backups/                # Database backups (SQL Server)
└── letsencrypt/                # Let's Encrypt certificates (if used)
    ├── live/
    │   └── {domain}/
    │       ├── cert.pem
    │       ├── chain.pem
    │       ├── fullchain.pem
    │       └── privkey.pem
    └── logs/
```

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

### Manifest Output Format

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Example structure of the generated manifest.json file containing build metadata.

```json
{
  "builds": [
    {
      "name": "amazon-ebs.bitwarden_self_host",
      "builder_type": "amazon-ebs",
      "build_time": 1234567890,
      "files": [],
      "artifact_id": "ami-0123456789abcdef0",
      "artifact_type": "amazon.image"
    }
  ],
  "last_run_uuid": "12345678-1234-1234-1234-123456789012"
}
```

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

### Start or Restart Services

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Starts or restarts all containers using Docker Compose, ensuring volumes and permissions are correct.

```bash
./run.sh restart [OUTPUT_DIR] [COREVERSION] [WEBVERSION] [KEYCONNECTORVERSION]
./run.sh start [OUTPUT_DIR] [COREVERSION] [WEBVERSION] [KEYCONNECTORVERSION]
```

```bash
./run.sh restart ./bwdata 2026.7.0 2026.7.0 2025.11.0
```

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

### 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
```

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

### Configure Resource Limits

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Example YAML configuration for setting CPU and memory limits on the Bitwarden service.

```yaml
bitwarden:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '1.0'
      memory: 1G
```

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

### Make Scripts Executable

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/marketplace-provisioning.md

Sets executable permissions for various Bitwarden initialization and setup scripts.

```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
```

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

### Version Configuration

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

Defines the current versions for core components used during installation and updates.

```bash
COREVERSION="2026.7.0"
WEBVERSION="2026.7.0"
KEYCONNECTORVERSION="2025.11.0"
```

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

### Enable Service at Runtime

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Modifies the configuration file and reloads Supervisord to start a service without a full container restart.

```bash
# SSH into container or use docker exec
docker-compose exec bitwarden /bin/bash

# Edit the configuration
sed -i 's/autostart=false/autostart=true/' /etc/supervisor.d/events.ini

# Reload supervisord configuration
supervisorctl reread
supervisorctl update events

# Start the service
supervisorctl start events

# Verify
supervisorctl status events
```

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

### UID/GID Environment Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Example content for the env/uid.env file used to map container users to the host user.

```bash
LOCAL_UID=1000
LOCAL_GID=1000
```

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

### 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
```

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

### Common Docker Compose Commands

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Standard commands for starting, monitoring, and stopping Bitwarden services.

```bash
docker-compose up -d
```

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

```bash
docker-compose restart bitwarden
```

```bash
docker-compose down
```

```bash
docker-compose down -v  # Deletes volumes too!
```

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

### Install Alpine Packages

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Installs required system dependencies using apk. The --no-cache flag is used to keep the image size minimal.

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

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

### Initialize Nginx log rotation

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/bitwarden-lite-entrypoint.md

Starts the log rotation script in a background loop process.

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

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

### Manage Bitwarden Deployment Lifecycle

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

Commands for installing, updating, stopping, and uninstalling Bitwarden services.

```bash
# Install traditional deployment
./bitwarden.sh install

# Install Lite deployment (via docker-compose.yml)
docker-compose -f bitwarden-lite/docker-compose.yml up -d

# Update to latest version
./bitwarden.sh update

# Stop services
./bitwarden.sh stop

# Uninstall (destructive)
./bitwarden.sh uninstall
```

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

### Logging Operations

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/marketplace-provisioning.md

Example of logging script progress to assist in debugging build failures.

```bash
echo "Creating bitwarden user..."
useradd -m -s /bin/bash bitwarden
echo "✓ User created"
```

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

### 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
```

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

### Execute Supervisord

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/bitwarden-lite-entrypoint.md

Starts the supervisord process using su-exec to drop privileges to the configured user.

```bash
exec su-exec $PUID:$PGID /usr/bin/supervisord
```

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

### 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
```

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

### Manage Services via Docker Compose

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Commands to check status, restart, stop, or start services from outside the container.

```bash
# From outside container
docker-compose exec bitwarden supervisorctl status

# Restart a service
docker-compose exec bitwarden supervisorctl restart api

# Stop a service
docker-compose exec bitwarden supervisorctl stop identity

# Start a service
docker-compose exec bitwarden supervisorctl start events
```

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

### Troubleshoot service startup

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Use these commands to inspect logs and verify the status of the Bitwarden and database services.

```bash
# Check logs
docker-compose logs bitwarden
docker-compose logs db

# Verify database is ready
docker-compose exec bitwarden /bin/sh -c "sleep 30 && supervisorctl status"
```

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

### Display help with bitwarden.sh

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

Prints a list of all available commands and a link to official documentation.

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

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

### Troubleshoot service startup

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

Use these commands to inspect container logs, process status, and database connectivity.

```bash
# Check logs
docker-compose logs bitwarden

# Check process status (Lite)
docker-compose exec bitwarden supervisorctl status

# Check database connection
docker-compose logs db
```

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

### Create platform directory

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/marketplace-provisioning.md

Initializes the directory structure required for a new marketplace platform.

```bash
mkdir -p {Platform}Marketplace/scripts
```

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

### stop

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

Stops a running Bitwarden installation.

```APIDOC
## ./bitwarden.sh stop

### Description
Stops a running Bitwarden installation using Docker Compose.

### Parameters
#### Positional Parameters
- **OUTPUT_DIR** (string) - Optional - Installation directory to stop (Default: ./bwdata)

### Example
./bitwarden.sh stop /opt/bitwarden
```

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

### update

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

Updates a Bitwarden installation to the latest images.

```APIDOC
## ./bitwarden.sh update

### Description
Updates a Bitwarden installation to the latest images by re-downloading the run script and pulling new Docker images.

### Parameters
#### Positional Parameters
- **OUTPUT_DIR** (string) - Optional - Installation directory to update (Default: ./bwdata)

### Example
./bitwarden.sh update /opt/bitwarden
```

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

### Create Application Directories

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Sets up the required file system hierarchy for Bitwarden services, logs, and Nginx configuration.

```dockerfile
RUN mkdir -p \
    /etc/bitwarden/attachments/send \
    /etc/bitwarden/data-protection \
    /etc/bitwarden/licenses \
    /etc/bitwarden/logs \
    /etc/supervisor \
    /etc/supervisor.d \
    /var/log/bitwarden \
    /var/log/nginx/logs \
    /etc/nginx/http.d \
    /var/run/nginx \
    /var/lib/nginx/tmp \
    /app \
    && touch /var/run/nginx/nginx.pid
```

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

### Stop Bitwarden

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

Stops all running containers for the specified installation.

```bash
./bitwarden.sh stop [OUTPUT_DIR]
```

```bash
./bitwarden.sh stop /opt/bitwarden
```

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

### Update Database Schema

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

Executes database migrations for the specified installation.

```bash
./bitwarden.sh updatedb [OUTPUT_DIR]
```

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

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

### Troubleshoot Service Startup

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Commands to inspect logs, check process status, and restart services that fail to initialize.

```bash
docker-compose exec bitwarden supervisorctl tail api 100

# Check if process is hung
docker-compose exec bitwarden ps aux | grep Api

# Force restart
docker-compose exec bitwarden supervisorctl restart api
```

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

### Set Working Directory and Entrypoint

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Configures the application directory and the primary startup command.

```dockerfile
WORKDIR /app
ENTRYPOINT ["/entrypoint.sh"]
```

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

### Uninstall Bitwarden with bitwarden.sh

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

Removes the Bitwarden installation, including containers and volumes.

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

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

### Marketplace VM Deployment Workflow

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

Sequence of steps for deploying Bitwarden via a cloud marketplace image.

```text
1. Cloud provider launches VM from marketplace image
2. cloud-init runs /var/lib/cloud/scripts/per-instance/001_onboot
3. User SSH's into instance
4. shell sources /etc/profile.d/bitwarden-first-login.sh
5. User runs setup-wizard.sh or install-standard.sh or install-lite.sh
6. Bitwarden starts in selected deployment model (Traditional or Lite)
```

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

### Configure Container Entrypoint

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Copies the initialization script into the container and sets the necessary execution permissions.

```dockerfile
COPY bitwarden-lite/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
```

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

### Build Docker Images

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Commands for building the Bitwarden Lite image for local development, release, or multi-platform deployment.

```bash
docker build -t bitwarden/lite:local bitwarden-lite/
```

```bash
docker build \
  --build-arg SERVER_TAG=2026.7.0 \
  --build-arg WEB_TAG=2026.7.0 \
  -t ghcr.io/bitwarden/lite:2026.7.0 \
  bitwarden-lite/
```

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --build-arg SERVER_TAG=2026.7.0 \
  --build-arg WEB_TAG=2026.7.0 \
  -t ghcr.io/bitwarden/lite:2026.7.0 \
  --push \
  bitwarden-lite/
```

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

### Include Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Loads additional service configuration files from the specified directory.

```ini
[include]
files = /etc/supervisor.d/*.ini
```

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

### Configure launch block device mappings

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Sets the root volume size and type for the build instance, ensuring cleanup upon termination.

```hcl
launch_block_device_mappings {
  device_name           = "/dev/sda1"
  volume_size           = 32        # 32 GB
  volume_type           = "gp3"     # General purpose SSD (faster than gp2)
  delete_on_termination = true      # Clean up after build
}
```

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

### Override Environment Variables

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Demonstrates how to override specific environment variables at runtime or use a .env file for configuration.

```bash
# Override specific variable
docker-compose -f docker-compose.yml run -e BW_DOMAIN=newdomain.com bitwarden /entrypoint.sh

# Use .env file in docker-compose directory
# Create .env file with: REGISTRY=my-registry, TAG=custom-version
docker-compose up
```

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

### Wait for cloud-init

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Ensures the base system is fully initialized before proceeding with further provisioning steps.

```shell
cloud-init status --wait
```

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

### Lite All-in-One Deployment Workflow

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

Visual representation of the single-container deployment process using the Lite image.

```text
User runs: docker-compose -f bitwarden-lite/docker-compose.yml up -d
    ↓
(or: ./bitwarden.sh install, selects Lite during setup)
    ↓
Pulls image: ghcr.io/bitwarden/lite:VERSION
    ↓
Entrypoint:
  - Creates user/group
  - Generates certificates
  - Configures services
  - Starts supervisord
    ↓
Result: Single container with all services
```

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

### Define Web Application Build Stage

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Initializes the web-app stage using the specified web image and tag.

```dockerfile
FROM ${WEB_IMAGE}:${WEB_TAG} AS web-app
```

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

### Docker Compose Configuration Usage

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Usage note for the dockerComposeFiles function which handles environment variable setup for compose commands.

```bash
# Automatically called before every docker-compose command
# Allows users to customize without editing main compose file
```

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

### Override Docker Image Environment Variables

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

Use environment variables to specify custom registry, image name, and tag when starting the service.

```bash
REGISTRY=my-registry IMAGE=bitwarden-lite TAG=custom ./bitwarden.sh start
```

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

### Configure SSL Settings

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

Commands to enable HTTPS using self-signed certificates or Let's Encrypt.

```bash
# Enable HTTPS with self-signed cert (auto-generated)
export BW_ENABLE_SSL=true

# Or use Let's Encrypt (during traditional install)
./bitwarden.sh install
# Choose "y" when prompted for Let's Encrypt
```

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

### System Update Provisioner

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Updates the package index and performs a full system upgrade while forcing default configurations for conflicts.

```bash
sudo apt-get -qqy update
sudo apt-get -qqy -o Dpkg::Options::='--force-confdef' -o Dpkg::Options::='--force-confold' full-upgrade
sudo apt-get -qqy -o Dpkg::Options::='--force-confdef' -o Dpkg::Options::='--force-confold' install ${var.apt_packages}
sudo apt-get -qqy clean
```

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

### 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
```

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

### Configure MariaDB Database Service

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

Sets up the MariaDB database service with required environment variables for user and database initialization.

```yaml
db:
  environment:
    MARIADB_USER: "bitwarden"
    MARIADB_PASSWORD: "password"
    MARIADB_DATABASE: "bitwarden_vault"
    MARIADB_RANDOM_ROOT_PASSWORD: "true"
  image: mariadb:10
  restart: always
  volumes:
    - data:/var/lib/mysql
```

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

### 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 .
```

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

### Define Service Build Stages

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Imports pre-built .NET service binaries from upstream Bitwarden server images.

```dockerfile
FROM ${SERVER_REGISTRY}/admin:${SERVER_TAG} AS admin-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/api:${SERVER_TAG} AS api-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/events:${SERVER_TAG} AS events-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/icons:${SERVER_TAG} AS icons-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/identity:${SERVER_TAG} AS identity-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/notifications:${SERVER_TAG} AS notifications-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/scim:${SERVER_TAG} AS scim-app
```

```dockerfile
FROM ${SERVER_REGISTRY}/sso:${SERVER_TAG} AS sso-app
```

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

### Required Environment Variables

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

These variables must be configured prior to container initialization.

```text
BW_DOMAIN
BW_INSTALLATION_ID
BW_INSTALLATION_KEY
BW_DB_PROVIDER
BW_DB_SERVER (if not sqlite)
BW_DB_DATABASE (if not sqlite)
BW_DB_USERNAME (if not sqlite)
BW_DB_PASSWORD (if not sqlite)
```

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

### Configure source AMI filter

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Filters for selecting the latest Ubuntu 24.04 LTS HVM SSD GP3 image from Canonical.

```hcl
source_ami_filter {
  filters = {
    name                = "ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*"
    root-device-type    = "ebs"
    virtualization-type = "hvm"
  }
  most_recent = true
  owners      = ["099720109477"]  # Canonical (Ubuntu publisher)
}
```

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

### View Directory Structure

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Visual representation of the resulting /app directory structure after copying service binaries.

```text
/app/
├── Admin/          (Admin service binaries)
├── Api/            (API service binaries)
├── Events/         (Events service binaries)
├── Icons/          (Icons service binaries)
├── Identity/       (Identity service binaries)
├── Notifications/  (Notifications service binaries)
├── Scim/           (SCIM service binaries)
├── Sso/            (SSO service binaries)
└── Web/            (Web client static assets)
```

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

### 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 Directory Helper

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Syntax for the createDir helper function used to initialize volume directories with correct permissions.

```bash
createDir "directory_name"
```

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

### Nginx Web Server Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Defines the Nginx web server configuration with a 3-second startup delay.

```ini
[program:nginx]
autostart=true
autorestart=true
command=/usr/sbin/nginx
redirect_stderr=true
startsecs=3
stdout_logfile=/var/log/nginx/access.log
stdout_logfile_maxbytes=10485760
stdout_logfile_backups=5
```

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

### Bitwarden Settings Template

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

Template for the settings.env file containing required and optional configuration parameters for Bitwarden self-hosting.

```bash
#####################
# Required Settings #
#####################

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=super_strong_password
BW_INSTALLATION_ID=00000000-0000-0000-0000-000000000000
BW_INSTALLATION_KEY=xxxxxxxxxxxx

#####################
# Optional Settings #
#####################

PUID=1000
PGID=1000
BW_ENABLE_IPV6=true
BW_PORT_HTTP=8080
BW_PORT_HTTPS=8443
BW_ENABLE_SSL=false
BW_ENABLE_SSL_CA=false
BW_ENABLE_ADMIN=true
BW_ENABLE_API=true
BW_ENABLE_EVENTS=false
BW_ENABLE_ICONS=true
BW_ENABLE_IDENTITY=true
BW_ENABLE_NOTIFICATIONS=true
BW_ENABLE_SCIM=false
BW_ENABLE_SSO=false
globalSettings__mail__replyToEmail=noreply@bitwarden.example.com
globalSettings__mail__smtp__host=smtp.example.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
```

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

### Define Dockerfile Build Arguments

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Sets the default registry and tag variables for server and web client images.

```dockerfile
ARG SERVER_TAG=dev
ARG SERVER_REGISTRY=ghcr.io/bitwarden
ARG WEB_IMAGE=ghcr.io/bitwarden/web
ARG WEB_TAG=dev
```

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

### Download Handlebars Tool

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Queries the GitHub API for the latest release and downloads the platform-specific binary for the Handlebars configuration tool.

```dockerfile
RUN echo "$(curl --silent https://api.github.com/repos/bitwarden/Handlebars.conf/git/refs/tags | jq -r 'last(.[].ref)' | sed 's/refs\/tags\///')"  > /tmp/latest.txt
RUN LATEST_VERSION=$(cat /tmp/latest.txt) && if [ "$TARGETPLATFORM" = "linux/amd64" ] ; then curl --proto "=https" -L --output hbs.zip https://github.com/bitwarden/Handlebars.conf/releases/download/$LATEST_VERSION/hbs_linux-x64.zip; fi
RUN LATEST_VERSION=$(cat /tmp/latest.txt) && if [ "$TARGETPLATFORM" = "linux/arm/v7" ] ; then curl --proto "=https" -L --output hbs.zip https://github.com/bitwarden/Handlebars.conf/releases/download/$LATEST_VERSION/hbs_linux-arm.zip; fi
RUN LATEST_VERSION=$(cat /tmp/latest.txt) && if [ "$TARGETPLATFORM" = "linux/arm64" ] ; then curl --proto "=https" -L --output hbs.zip https://github.com/bitwarden/Handlebars.conf/releases/download/$LATEST_VERSION/hbs_linux-arm64.zip; fi
RUN unzip hbs.zip -d /usr/local/bin && mv /usr/local/bin/hbs* /usr/local/bin/hbs && rm hbs.zip
RUN chmod +x /usr/local/bin/hbs
```

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

### 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
```

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

### Database Connection Strings

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/bitwarden-lite-entrypoint.md

Connection string templates for supported database engines. Ensure all placeholders are replaced with valid environment-specific credentials.

```text
server=DB_SERVER;port=DB_PORT;database=DB_DATABASE;user=DB_USERNAME;password=DB_PASSWORD
```

```text
Host=DB_SERVER;Port=DB_PORT;Database=DB_DATABASE;Username=DB_USERNAME;Password=DB_PASSWORD
```

```text
Server=DB_SERVER,DB_PORT;Database=DB_DATABASE;User Id=DB_USERNAME;Password=DB_PASSWORD;Encrypt=True;TrustServerCertificate=True
```

```text
Data Source=DB_FILE;
```

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

### SQLite Connection String Configuration

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

Format for SQLite database connections, specifying the file path.

```text
Data Source=PATH;
```

```text
Data Source={string}    # File path to database
```

```text
Data Source=/etc/bitwarden/vault.db;
```

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

### Configure PostgreSQL Service

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Optional PostgreSQL 14 configuration. Uncomment and comment out the MariaDB section to enable.

```yaml
# db:
#   environment:
#     POSTGRES_USER: "bitwarden"
#     POSTGRES_PASSWORD: "super_strong_password"
#     POSTGRES_DB: "bitwarden_vault"
#   image: postgres:14
#   restart: always
#   volumes:
#     - data:/var/lib/postgresql/data
```

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

### View Container Process List

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Displays the process hierarchy where Supervisord acts as the init process managing child services.

```text
bitwarden   1  /usr/bin/supervisord    # Main process
bitwarden  XX  /app/Admin/Admin        # Admin service
bitwarden  YY  /app/Api/Api            # API service
bitwarden  ZZ  /app/Identity/Identity  # Identity service
bitwarden  XX  /usr/sbin/nginx         # Web server
# (etc for other enabled services)
```

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

### Configure Environment File for Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/docker-compose-lite.md

Reference the settings.env file to load required environment variables into the Bitwarden service.

```yaml
env_file:
  - settings.env
```

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

### Modify Service Autostart via sed

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Uses sed to dynamically update the autostart configuration in supervisord ini files based on 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
# ... (etc for all services)
```

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

### Backup and Restore Volumes

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/run-sh.md

Use these commands to stop the service, archive the data directories, and restore them later.

```bash
# Backup volumes
docker-compose down
tar -czvf bitwarden-backup.tar.gz ./core ./mssql ./logs

# Restore
tar -xzvf bitwarden-backup.tar.gz
docker-compose up -d
```

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

### API Service Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Defines the API service running on port 5001 with a 15-second startup delay.

```ini
[program:api]
autostart=true
autorestart=true
command=/app/Api/Api
directory=/app/Api
environment=ASPNETCORE_URLS="http://+:5001"
priority=2
redirect_stderr=true
startsecs=15
stdout_logfile=/var/log/bitwarden/api.log
stdout_logfile_maxbytes=10485760
stdout_logfile_backups=5
```

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

### Configure Nginx in Dockerfile

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/dockerfile-lite.md

Copies Nginx configuration files and makes the log rotation script executable.

```dockerfile
COPY bitwarden-lite/nginx/nginx.conf /etc/nginx
COPY bitwarden-lite/nginx/proxy.conf /etc/nginx
COPY bitwarden-lite/nginx/mime.types /etc/nginx
COPY bitwarden-lite/nginx/security-headers.conf /etc/nginx
COPY bitwarden-lite/nginx/security-headers-ssl.conf /etc/nginx
COPY bitwarden-lite/nginx/logrotate.sh /
RUN chmod +x /logrotate.sh
```

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

### Move Provisioned Files

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/packer-aws.md

Moves configuration files from the temporary /tmp directory to their final system locations with appropriate ownership and permissions.

```bash
sudo mkdir -p /etc/update-motd.d /etc/ufw/applications.d /opt/bitwarden /var/lib/cloud/scripts/per-instance
sudo mv /tmp/99-bitwarden-welcome /etc/update-motd.d/99-bitwarden-welcome
sudo mv /tmp/bitwarden-ufw /etc/ufw/applications.d/bitwarden
# ... (etc for all files)
sudo chown root:root /etc/update-motd.d/99-bitwarden-welcome ...
sudo chmod 644 /etc/ufw/applications.d/bitwarden /etc/profile.d/bitwarden-first-login.sh
```

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

### Backup and Restore Commands

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

Standard shell commands for backing up and restoring Bitwarden volumes.

```bash
# Backup all volumes
docker-compose down
tar -czvf backup.tar.gz bwdata/

# Restore
tar -xzvf backup.tar.gz
docker-compose up -d
```

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

### Configure UFW for Bitwarden

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/marketplace-provisioning.md

Configures UFW firewall rules for Bitwarden and enables the firewall.

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

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

### Supervisord Daemon Configuration

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/supervisord-config.md

Sets the main log file and ensures the process runs in the foreground for container compatibility.

```ini
[supervisord]
logfile=/var/log/supervisord.log
nodaemon=true
```

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

### Manage Firewall Rules

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/marketplace-provisioning.md

Individual commands for managing SSH and Bitwarden firewall access.

```bash
ufw allow ssh
```

```bash
ufw allow 'Bitwarden'
```

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

### Lite Deployment Architecture

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

Visual representation of the all-in-one container architecture managed by supervisord.

```text
Single container (supervisord manages all):
├── Admin (port 5000)
├── API (port 5001)
├── SCIM (port 5002)
├── Events (port 5003)
├── Icons (port 5004)
├── Identity (port 5005)
├── Notifications (port 5006)
├── SSO (port 5007)
└── Nginx (ports 80/443)

Database (external or SQLite):
└── Any provider supported
```

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

### Create Bitwarden User and Group

Source: https://github.com/bitwarden/self-host/blob/main/_autodocs/api-reference/bitwarden-lite-entrypoint.md

Creates a dedicated system user and group for running the application with configurable UID/GID.

```bash
addgroup -g $PGID bitwarden
adduser -D -H -u $PUID -G bitwarden bitwarden
```

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

### 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

```