Borgitory is a comprehensive web-based management interface for BorgBackup repositories that provides real-time monitoring, automated scheduling, and cloud synchronization capabilities. It offers complete backup lifecycle management including on-demand backups, automated pruning policies, interactive archive browsing with file downloads, and cloud sync to S3-compatible storage via Rclone. The FastAPI powered system features a modern responsive web interface built with HTMX, and Tailwind CSS.
- full documentation is available at https://borgitory.com
- Docker Installation (Recommended): Docker with Docker Compose for containerized deployment
- PyPI Installation: Python 3.14+ for direct installation from PyPI
-
Pull and run the Docker image
# Using Docker directly docker run -d \ -p 8000:8000 \ -v ./data:/app/data \ -v /path/to/backup/sources:/backup/sources:ro \ -v /path/to/borg/repos:/repos \ --cap-add SYS_ADMIN \ --device /dev/fuse \ --name borgitory \ mlapaglia/borgitory:latestOr using Docker Compose (create a
docker-compose.yml):version: '3.8' services: borgitory: image: mlapaglia/borgitory:latest ports: - "8000:8000" volumes: - ./data:/app/data # database and encryption key location - /path/to/backup/sources:/sources:ro - /path/to/any/backup/repos:/repos:ro cap_add: - SYS_ADMIN # optional, needed to mount borg archives and browse them devices: - /dev/fuse # borg uses FUSE to mount archives restart: unless-stopped
docker-compose up -d
-
Access the web interface
- Open http://localhost:8000 in your browser
- Create your first admin account on initial setup
Install Borgitory directly from PyPI:
# Install stable release from PyPI
pip install borgitory
# Start the server
borgitory serve
# Or run with custom settings
borgitory serve --host 0.0.0.0 --port 8000PyPI Installation Requirements:
- Python 3.14 or higher
- BorgBackup installed and available in PATH
- Rclone (optional, for cloud sync features)
- FUSE (optional, for browsing archives)
Windows Requirements:
- WSL2 (Windows Subsystem for Linux) must be installed and configured
- Inside WSL2, you need:
- BorgBackup installed (
sudo apt install borgbackupor similar) - Python 3.14+ installed
- Rclone installed (optional, for cloud sync features)
- BorgBackup installed (
- BorgBackup does not have a native Windows executable, so WSL2 is required for all backup operations
| Variable | Default | Purpose |
|---|---|---|
BORGITORY_SECURE_COOKIES |
auto | true marks the session cookie Secure. Set it when TLS terminates at a proxy; by default the cookie is only Secure when Borgitory itself sees an https request. |
BORGITORY_TRUSTED_ORIGINS |
(empty) | Comma-separated origins (e.g. https://backup.example.com) allowed to make state-changing requests if your proxy rewrites the Host header and your browser does not send Sec-Fetch-Site. Not normally needed. |
Borgitory rejects cross-site POST/PUT/PATCH/DELETE requests (CSRF protection), and throttles repeated failed logins per client IP.
The container exposes an unauthenticated GET /health endpoint for health checks; the image's HEALTHCHECK uses it.
docker-compose.yml runs the production image. To attach a debugger, layer the development override, which builds the dev image target and publishes debugpy on 127.0.0.1:5678 only:
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --buildPython dependencies are pinned with hashes in requirements.txt (runtime) and requirements-dev.txt (development). After changing dependencies in pyproject.toml, regenerate them:
uv pip compile pyproject.toml --universal --generate-hashes --python-version 3.14 -o requirements.txt
uv pip compile pyproject.toml --extra dev --universal --generate-hashes --python-version 3.14 -o requirements-dev.txtBorgitory can back up directly to a repository on a remote borg server, such as BorgBase, a Hetzner Storage Box, or another machine running borg. This keeps an off-site copy that is a separate borg repository rather than an rclone mirror of a local one, so corruption of the local repository does not spread to it. This is not full ransomware protection on its own: a backup that runs after files are encrypted stores the encrypted files, and prune can remove older clean archives. Use append-only mode (below) and a retention policy that keeps older archives.
Remote repositories need an SSH client (ssh) on the machine running borg. The Docker image includes one; for PyPI installs, install it alongside borg (for example sudo apt install openssh-client).
When creating or importing a repository, enter an ssh:// URL as the path:
- BorgBase:
ssh://abcd1234@abcd1234.repo.borgbase.com/./repo - Hetzner Storage Box:
ssh://u123456@u123456.your-storagebox.de:23/./backups/repo(set Remote Borg Path toborg-1.4) - Your own server:
ssh://borg@nas.example.com/./borg/repo(/./means relative to the user's home directory)
Paste the SSH private key into the form and add its public key to the server's authorized_keys. The key is stored encrypted in the database. The server's host key is trusted on first connection and saved in <data dir>/ssh/known_hosts. If the host key later changes deliberately, remove the old entry with ssh-keygen -R host -f <data dir>/ssh/known_hosts for port 22, or ssh-keygen -R "[host]:port" -f <data dir>/ssh/known_hosts for any other port.
For backups that can't be deleted from the client, restrict the key on the server to append-only mode in authorized_keys, for example command="borg serve --append-only --restrict-to-path /home/borg/repo",restrict ssh-ed25519 AAAA.... Borgitory can't enforce this itself, and in append-only mode prune and compact won't free space on the server.
Cloud sync only applies to local repositories and is skipped for remote ones.
