Lite Deployment

[!TIP] Who is Lite for? Bitwarden lite is intended for personal use and home-labs, not for use in business contexts. Businesses should use one of the standard deployment options.

This article will walk you through installing and launching Bitwarden lite. Use this deployment method to:

• Simplify configuration and optimize resource usage (CPU, memory) by deploying Bitwarden with a single Docker image.
• Utilize different database solutions such as MSSQL, PostgreSQL, SQLite, and MySQL/MariaDB. Only lite deployments can currently leverage these databases, standard deployments require MSSQL.
• Run on ARM architecture for alternative systems such as Raspberry Pi and NAS servers.

[!TIP] Transitioning from Unified to Lite. In December, 2025 Bitwarden Unified exited beta and was renamed Bitwarden lite. If you participated in the beta, make sure that you use the new image name (ghcr.io/bitwarden/lite) when updating to the latest version.

System requirements

Bitwarden lite requires:

• RAM: At least 200 MB
• Storage: At least 1GB
• Docker Engine: Version 26+

Setup

Before running a Bitwarden lite server, install Docker, setup your settings.env file, and decide on your database configuration:

Install Docker

Bitwarden lite will run on your machine using a Docker container. Lite can be run with any Docker edition or plan, but you must install Docker on your machine before proceeding with installation. Refer to the following Docker documentation for help:

• Install Docker Engine

Required environment variables

Environment variables can be specified by creating a settings.env file, which you can find an example of in our GitHub repository, or by using the --env flag if you're using the docker run method. At a minimum, set values for the variables that fall under the # Required Settings # section of the example .env file:

[!TIP] More Lite environment variables. More optional environment variables are available than those listed in this table.

Database examples

Unlike standard Bitwarden deployments, lite does not come out-of-the-box with a database. You can use an existing database, or create a new one. Which # Required Settings # you'll be required to include in your settings.env file or --env flags will depend on which supported database provider you're using:

[!NOTE] Lite database require your management. Because Bitwarden lite databases are not provided by or collocated with the application container, database maintenance, including updates, maintenance, and backups, must be fully managed by you.

MySQL/MariaDB

The following variables are required for a MySQL or MariaDB database:

# Database
BW_DB_PROVIDER=mysql
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password

MSSQL

The following variables are required for an MSSQL database:

BW_DB_PROVIDER=sqlserver
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password

SQLite

The following variables are required for an SQLite database:

BW_DB_PROVIDER=sqlite
BW_DB_FILE=/path/to/.db

Assigning the sqlitevalue will create a vault.dbfile in the /etc/bitwarden volume automatically. BW_DB_FILE is only required if you would like to specify the path to a different database file.

PostgreSQL

The following variables are required for an PostgreSQL database:

BW_DB_PROVIDER=postgresql
BW_DB_SERVER=db
BW_DB_DATABASE=bitwarden_vault
BW_DB_USERNAME=bitwarden
BW_DB_PASSWORD=super_strong_password

Run the server

The lite deployment can be run using the docker run command or using Docker Compose. In either case, make sure that you've set your environment variables and made your database available before proceeding.

Docker run

The lite deployment can be run with the docker run command, as in the following example:

docker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env ghcr.io/bitwarden/lite

Running the server with the docker run command has several required options, including:

Once you run the command, verify that the container is running and healthy with:

docker ps

Congratulations! Bitwarden lite is now up and running at https://your.domain.com. Visit the web vault in your browser to confirm that it's working. You may now register a new account and log in.

Docker Compose

Running the lite deployment with Docker Compose will require Docker Compose version 1.24+. To run the lite deployment with Docker compose, create a docker-compose.yml file, for example:

---
version: "3.8"

services:
 bitwarden:
 depends_on:
 - db
 env_file:
 - settings.env
 image: ghcr.io/bitwarden/lite
 restart: always
 ports:
 - "80:8080"
 volumes:
 - bitwarden:/etc/bitwarden

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

volumes:
 bitwarden:
 data:

In the docker-compose.yml file, make any desired configurations including:

• Mapping volumes for logs and Bitwarden data.
• Mapping ports.
• Configuring a database image.ª

ªOnly setup a database in docker-compose.yml, as in the above example, if you want to create a new database server to use with Bitwarden. Sample configurations for MySQL, MSSQL, and PostgreSQL are included in our example file.

Once your docker-compose.yml and settings.env file are created, start your lite server by running:

docker compose up -d

Verify that all containers are running correctly:

docker ps

Congratulations! Your lite deployment is now up and running at https://your.domain.com. Visit the web vault in your browser to confirm that it's working. You may now register a new account and log in.

Update or restart the server

It's important to keep your Bitwarden lite server up to date. Like running the server, you can update it using either docker run commands or Docker Compose:

Docker run

[!TIP] Lite, if you're restarting instead of updating If you're restarting instead of updating the server, for example after making environment variable changes, skip the step that requires you to pull the most recent Bitwarden lite image.

To update the server:

1. Stop the running Docker container:

docker stop bitwarden

1. Remove the Docker container:

docker rm bitwarden

1. Pull the most recent Bitwarden lite image:

docker pull ghcr.io/bitwarden/lite

1. Restart the server:

docker run -d --name bitwarden -v /$(pwd)/bwdata/:/etc/bitwarden -p 80:8080 --env-file settings.env ghcr.io/bitwarden/lite

Docker Compose

[!TIP] Lite, if you're restarting instead of updating If you're restarting instead of updating the server, for example after making environment variable changes, skip the step that requires you to pull the most recent Bitwarden lite image.

To update the server:

1. Stop the running Docker container:

docker compose down

1. Pull the most recent Bitwarden lite image:

docker compose pull

1. Restart the server:

docker compose up -d

Optional environment variables

Bitwarden lite works, by default, with some available services deactivated. These services, and many other server characteristics, can optionally be activated and customized with your settings.env file or --env flags:

[!WARNING] When editing Lite environment variables Whenever you change an environment variable, you will need to restart your server in order for changes to take effect.

Services

Additional services can be activated or deactivated using the following variables:

Certificates

Use these variables to change certificate settings:

[!NOTE] Using existing SSL with Lite. If you are using an existing SSL certificate, you will have to enable the appropriate SSL options in settings.env. SSL files must be stored in /etc/bitwarden, which can be referenced in the the docker-compose.yml file. These files must match the names configured in settings.env.

The default behavior is to generate a self-signed certificate if SSL is enabled and no existing certificate files are in the expected location (/etc/bitwarden).

SMTP

Use these variables to setup or change an SMTP provider for your server:

Ports

Use these variables to configure the ports used for traffic:

Yubico API

Use these variables to connect with Yubico Web Services:

Miscellaneous

Use these variables to configure other characteristics of your Bitwarden lite server:

Troubleshooting

Memory usage

By default, the Bitwarden container will consume memory that is available to it, often being more than the minimum needed to run. For memory conscious environments, you can use docker -m or --memory=to limit the Bitwarden container's memory usage.

To control memory usage with Docker Compose, use the mem_limit key:

services:
 bitwarden:
 env_file:
 - settings.env
 image: ghcr.io/bitwarden/lite
 restart: always
 mem_limit: 200m