ttionya/vaultwarden-backup Docker backup and restore guide

What Vaultwarden Backup Stores

This project addresses the operational problem of copying persistent Vaultwarden data to remote storage while Vaultwarden runs as a Docker container. Its target users are Vaultwarden operators who already understand Vaultwarden configuration, Docker volumes and database deployment choices. The project does not replace the Vaultwarden application itself. It packages backup logic around the data directory and sends selected files through Rclone.

The documented file set covers the common persistence boundaries of Vaultwarden. For SQLite deployments it handles `db.sqlite3`; for PostgreSQL it handles `db.dump`; and for MySQL or MariaDB it handles `db.sql`. It also covers `config.json`, all files matching `rsa_key*`, and the `attachments` and `sends` directories. That scope is broader than a database-only snapshot. A restore can therefore address application configuration, encryption-related RSA key files and user-associated directories, provided the operator selects the corresponding backup files.

The backup format depends on settings described in the project documentation. The Compose file exposes controls such as `ZIP_ENABLE`, `ZIP_TYPE`, `ZIP_PASSWORD`, `BACKUP_FILE_SUFFIX` and `BACKUP_KEEP_DAYS`. The documentation also describes restore choices for a compressed `backup` package or independent files such as `db.sqlite3`, `config.json`, `rsakey.tar`, `attachments.tar` and `sends.tar`. The exact generated layout should be checked before a restore because the documentation distinguishes these formats.

Docker Architecture and Database Flow

The repository presents the project as a Docker container whose entrypoint is `entrypoint.sh`. Based on the Dockerfile, the image starts from `rclone/rclone:1.75.2`, copies the shell scripts into `/app/`, and adds backup-related tools including `7zip`, `bash`, `curl`, MariaDB client packages, `postgresql18-client`, `sqlite`, `supercronic`, `s-nail` and `tzdata`.

The database client choices match the database formats in the README. SQLite can operate on `db.sqlite3`, PostgreSQL uses a dump named `db.dump`, and MySQL or MariaDB use a SQL dump named `db.sql`. The project then combines these database outputs with the configuration file, RSA key files, attachments and sends. Rclone handles the transfer to remote storage, while the scheduled execution mechanism supports recurring jobs.

The Compose file connects the backup service to two Docker volumes. `vaultwarden-data` is mounted at `/bitwarden/data/`, and `vaultwarden-rclone-data` is mounted at `/config/`. The first volume gives the backup process access to Vaultwarden data. The second stores the Rclone configuration. The backup service is configured with `restart: always`, and its default schedule is represented by `CRON: '5 * * * *'`, described in the README as an automatic backup at five minutes past every hour.

This design keeps the backup container separate from the Vaultwarden service while sharing the relevant volume. It also means that correct volume mapping is part of correctness. A container can start successfully while still being unable to see the data or Rclone configuration it needs.

Configuring Rclone Before the First Backup

Rclone configuration is a prerequisite for backup. The README states that the tool will not work without it, and that Rclone configuration is not required for restore. The documented way to create the configuration uses the backup image interactively and stores it in the named volume `vaultwarden-rclone-data`. The command mounts that volume at `/config/` and runs `rclone config`.

Use the following command in the shell. It opens the interactive Rclone configuration process inside a temporary container:

docker run --rm -it \
  --mount type=volume,source=vaultwarden-rclone-data,target=/config/ \
  ttionya/vaultwarden-backup:latest \
  rclone config

The README recommends naming the remote `BitwardenBackup`. If a different remote name is selected, the `RCLONE_REMOTE_NAME` environment variable must identify that name. After configuration, inspect the stored content with the documented check command:

docker run --rm -it \
  --mount type=volume,source=vaultwarden-rclone-data,target=/config/ \
  ttionya/vaultwarden-backup:latest \
  rclone config show

The README includes a Microsoft OneDrive example, showing a remote named `BitwardenBackup` with a `type = onedrive` entry and token fields. Token contents are sensitive credentials. The displayed output should be treated as secret material and should not be copied into tickets, chat messages or source control. The actual storage provider and token acquisition process are external to this repository.

Starting Docker Compose Backups

For a new Vaultwarden deployment or a rebuild, the README recommends downloading `docker-compose.yml`, editing its environment variables and starting it from the directory containing that file. The repository file defines the `vaultwarden` service with image `vaultwarden/server:latest`, binds port `127.0.0.1:8200` to container port `80`, and mounts `vaultwarden-data` at `/data/`.

The same Compose file defines the `backup` service with `ttionya/vaultwarden-backup:latest`, `restart: always`, a mount of `vaultwarden-data` at `/bitwarden/data/`, and a mount of `vaultwarden-rclone-data` at `/config/`. The Compose file marks the Rclone volume as `external: true`, so that volume must already exist. The README's Rclone configuration command creates or uses the named volume `vaultwarden-rclone-data`.

The documented lifecycle commands are:

# Start
docker-compose up -d

# Stop
docker-compose stop

# Restart
docker-compose restart

# Remove
docker-compose down

The first real operational step is therefore to configure Rclone, confirm the external volume exists, edit the Compose environment settings and then start the services. The README does not document a command for inspecting a completed backup or verifying remote file contents, so an operator will need to verify the destination through the configured Rclone remote separately.

Automatic Backup for an Existing Vaultwarden Container

The project also supports a running Vaultwarden container without adopting its Compose file. The README requires the Vaultwarden container to be named `vaultwarden`, or requires the name in `--volumes-from` to be replaced. It assumes the default Vaultwarden data directory is `/data` and says that a different data directory must be passed through `DATA_DIR`.

The documented automatic backup command starts a detached backup container with automatic restart. It mounts the Vaultwarden container's volumes, mounts the Rclone configuration volume at `/config/`, and sets `DATA_DIR="/data"`:

docker run -d \
  --restart=always \
  --name vaultwarden_backup \
  --volumes-from=vaultwarden \
  --mount type=volume,source=vaultwarden-rclone-data,target=/config/ \
  -e DATA_DIR="/data" \
  ttionya/vaultwarden-backup:latest

The backup service is scheduled through the `CRON` environment variable. The Compose example uses `CRON: '5 * * * *'`, and the README describes this as an automatic backup at five minutes past every hour. Other backup controls include `RCLONE_REMOTE_DIR`, `RCLONE_GLOBAL_FLAG`, `ZIP_ENABLE`, `ZIP_PASSWORD`, `BACKUP_FILE_SUFFIX` and `BACKUP_KEEP_DAYS`.

The main operational limitation is visibility. Notifications are supported through Ping and SMTP mail, but the README does not explain how to inspect the full backup manifest or compare it against the Vaultwarden data directory. A successful notification should not be treated as a substitute for checking that the expected database and file categories were actually produced and uploaded.

Restore Boundaries and Failure Cases

Restore overwrites existing files, and the README requires the Vaultwarden Docker container to be stopped first. The backup files must be downloaded to the host because host files are not automatically visible inside the container. The current directory is mapped to `/bitwarden/restore/`, while the Vaultwarden data volume is mapped separately.

For the Compose deployment, the documented command maps `vaultwarden-data` to `/bitwarden/data/` and the current directory to `/bitwarden/restore/`:

docker run --rm -it \
  --mount type=volume,source=vaultwarden-data,target=/bitwarden/data/ \
  --mount type=bind,source=$(pwd),target=/bitwarden/restore/ \
  ttionya/vaultwarden-backup:latest restore \
  [OPTIONS]

For an existing deployment, the README gives separate examples for mapping a host directory or a Docker volume to `/data/`, then adds `DATA_DIR="/data"` and maps the restore directory. The options depend on the backup format. `-f` or `--force-restore` skips confirmation and is explicitly marked for caution. `--zip-file` selects a compressed package, while `-p` or `--password` supplies its password. The README warns that password entry is insecure. Independent backups use `--db-file`, `--config-file`, `--rsakey-file`, `--attachments-file` and `--sends-file`.

A wrong file selection, mismatched volume or missing RSA key can leave Vaultwarden without a complete, compatible data set. The README does not document integrity verification, retention guarantees for remote copies, or rollback behavior. Those points must be checked before relying on the archive for disaster recovery.

Licensing, Maintenance and Alternative Backup Approaches

The repository is licensed under `MIT`. That permits use, modification and redistribution subject to the MIT license terms, but this review does not provide legal advice. The operational cost is tied to Docker, Rclone configuration, remote storage credentials, scheduled container execution and the operator's responsibility for testing restores.

The repository is not archived, and its last push was on 2026-10-12. Recent releases listed in the repository are `v1.27.2` on 2026-10-12, `v1.27.1` on 2026-09-07 and `v1.27.0` on 2026-08-04. The documentation does not specify a long-term support policy or compatibility policy for Vaultwarden, Docker, Rclone or database server versions. Upgrading the image can therefore require checking the release notes and container behavior rather than assuming automatic compatibility.

An alternative is a database-native backup job combined with a separate file-copy mechanism. For example, PostgreSQL or MySQL tooling can produce a database dump, while Docker or host-level synchronization copies `config.json`, RSA key files and data directories. That approach gives more control over dump format, retention and verification, but it requires the operator to assemble and test a complete Vaultwarden restore. `ttionya/vaultwarden-backup` reduces that assembly work by bundling the documented Vaultwarden file set, scheduling and Rclone transfer into one container.

Editorial conclusion

Adopt ttionya/vaultwarden-backup if Vaultwarden already runs in Docker and you need scheduled database, key and attachment backups through rclone. Do not adopt it without first confirming that your backup files, Rclone remote, Docker volumes and restore procedure match the documented layout. The first thing to verify is whether the required Rclone configuration is present and whether the selected database type produces the expected backup file.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. ttionya/vaultwarden-backup on GitHub