Skip to content
mlapagliaPublic

About

Web UI for managing BorgBackup repositories with scheduling, monitoring, and cloud sync

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

194 stars

Watchers

1 watching

Forks

Latest commit

 

History

173 Commits

Folders and files

Repository files navigation

Borgitory

OpenSSF Baseline codecov build sponsors docker pulls pypi downloads Read the Docs

borgbackup version rclone version fuse3 version

borgitory logo

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.

Quick Start

Prerequisites

  • Docker Installation (Recommended): Docker with Docker Compose for containerized deployment
  • PyPI Installation: Python 3.14+ for direct installation from PyPI

Installation

Option 1: Docker Installation (Recommended)

  1. 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:latest

    Or 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
  2. Access the web interface

image

Option 2: PyPI Installation

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 8000

PyPI 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 borgbackup or similar)
    • Python 3.14+ installed
    • Rclone installed (optional, for cloud sync features)
  • BorgBackup does not have a native Windows executable, so WSL2 is required for all backup operations

Running behind a reverse proxy (HTTPS)

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.

Development with Docker

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

Python 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.txt

Remote Repositories (SSH)

Borgitory 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 to borg-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.

About

Web UI for managing BorgBackup repositories with scheduling, monitoring, and cloud sync

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

194 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages