Borg Backup Server
A self-hosted web application for centrally managing BorgBackup across multiple endpoints (Linux, Mac and Windows). A lightweight agent polls the server for tasks over HTTPS, backs up over SSH to the server, and reports progress back. No inbound connections to endpoints from the server — this works behind firewalls and NAT from where the server is providing easy provisioning. Includes a setup wizard for simple installation or a Docker image to start up in 30 seconds.
**View Demo **
The developer has made a system for provisioning Demos at no cost here: Borg Backup Server
Features
- Agent-based architecture — endpoints check-in with the server for tasks, the server doesn't need ssh access to the agent
- SSH with append-only security — agents can only backup or restore, can't delete or prune
- FULL Encryption - Software keeps everything encrypted at rest for enhanced security
- Setup wizard — browser-based installer configures database, admin account, and storage quicky
- Real-time progress — live progress bars during backups with detailed logging
- File-level restore — catalog data is saved in ClickHouse DB for fast search and file-tree without having to lock the borg repo
- Download archives — extract and download files as .tar.gz directly from the browser
- Database plugins — MySQL and PostgreSQL pre-dumps with automatic restore back into the database as a copy or replacement
- Flexible scheduling — hourly to monthly intervals, multiple plans per client, manual trigger
- Backup templates — pre-configured and customizeable directory sets for common server roles
- Retention policies — per-plan prune settings (hourly/daily/weekly/monthly/yearly)
- S3 offsite sync — mirror repositories to S3-compatible storage (AWS, Wasabi, Backblaze B2) for enahnced compliance
- Remote Storage Repos — wizards to backup to BorgBase, Hetzen and rsync.net (or any SSH provider that provides borg)
- Repo Management - Perform hard unlocks, repair, re-catalog, and other repo specific features
- Nightly Backup Reports - get an email every day with backup stats
- Multi-user — custom role-based access with various roles
- Two-factor authentication — TOTP-based 2FA with recovery codes, hooks into your 2FA of choice
- Queue management — concurrent job limits, cancel/retry, progress tracking
- Encrypted passphrases — repository passwords encrypted at rest (AES-256-GCM)
- Apprise alerts — custom push notifications to over 100 different notification services (Slack, Pushover, etc)
- Extensive Dashboard — backup charts, server stats, active jobs, see everything at a glance
- Server self-backup — daily automated backup of BBS itself with optional S3 sync offsite with restore scripts
- Automatic Self-Upgrade - one-click upgrade of the software plus all the agents. Also manage borg versions of client machines
Quick Start
Both installation paths are documented step by step on the Wiki — start there rather than piecing it together:
- Bare Metal / VM installation — a fresh Ubuntu server (22.04, 24.04, and 26.04 LTS are supported) and one installer command; the guide covers prerequisites, SSL, the setup wizard, and what the installer changes.
- Docker installation — pre-built images on Docker Hub for every release; the guide covers compose configuration, storage, reverse proxy setup, and updates.
Unraid: a Community Applications template is included at unraid/borgbackupserver.xml — add it via Docker → Add Container → Template (or your CA templates repo). It maps the web/SSH ports and the /var/bbs data path, and defaults APP_URL/SSH_PORT to the host.
📱 BBS Manager is here
BBS Manager is now available on the Apple App Store — manage your Borg Backup Server from your phone, with native push notifications for failed backups, server status, and more. It's an optional companion app; see the announcement for details and how to connect it under Settings → Push Service. Update to the latest release for the best experience with the app.
Documentation
All documentation lives on the GitHub Wiki:
Monitoring (Prometheus)
GET /metrics serves the exposition format, alongside the JSON at /api/v1/metrics.
Turn it on in Settings → API → Monitoring, where you choose which addresses may
read it and whether each range must also present a token. Create the token there too,
with type Monitoring (read-only) — it opens the monitoring endpoints and nothing
else, so it is safe to leave in a scrape configuration.
scrape_configs:
- job_name: bbs
scrape_interval: 60s
static_configs:
- targets: ['bbs.example.com']
authorization:
# A file, not the token inline: scrape configs end up in Git.
credentials_file: /etc/prometheus/bbs.token
Four alerts cover most of what goes wrong. Each one fires whether BBS is healthy or
not, which is the point of evaluating them outside BBS:
# Each plan carries its own threshold — the one BBS itself uses, client
# profile included — so a two-hourly plan and a laptop backed up on Mondays
# do not need the same number.
- alert: BackupOverdue
expr: |
(time() - bbs_plan_last_success_timestamp_seconds)
> on (instance, client, plan, repo) bbs_plan_overdue_seconds
- alert: BackupNeverRan
expr: bbs_plan_enabled == 1 unless bbs_plan_last_success_timestamp_seconds
- alert: BackupNotClean # 1 failed, 2 completed with warnings (e.g. a plugin failed)
expr: bbs_plan_last_run_status > 0
- alert: OffsiteCopyOverdue
expr: time() - bbs_repo_last_sync_timestamp_seconds > 86400
- alert: SchedulerStopped
expr: time() - bbs_scheduler_last_run_timestamp_seconds > 300
- alert: BorgUnusable # agent reporting in, borg not runnable
expr: bbs_client_info{borg_version=""} == 1
- alert: QueueNotDraining
expr: bbs_queue_oldest_seconds > 3600
A value that is not known is omitted rather than zeroed, so a plan that has never
succeeded has no bbs_plan_last_success_timestamp_seconds series at all — alert on
absent() for those. Rendered snapshots are cached (30s by default) because the
queries behind them read the whole job history.
Architecture
- HTTPS for control plane (task polling, progress, status)
- SSH for data plane (borg backup/restore via
borg serve)
- Append-only — agents cannot delete existing archives; pruning runs server-side
Tech Stack
| Layer | Technology |
|---|
| Backend | PHP 8.1+ (no framework) |
| Database | MySQL 8.0 |
| Frontend | Bootstrap 5, Chart.js |
| Agent | Python 3 (stdlib only) |
| Backup engine | BorgBackup |
| Offsite sync | rclone |
License
MIT License
Support
This project was the love of years of refined work and production use within a small web hosting company. Consider making a small monthly or one-time donation to help keep the project going.
