diarmuidk/docker-borg-client repository overview

⁠Docker Borg Client

A minimal, generic Docker container for running BorgBackup⁠ (source⁠) backups to any remote SSH-accessible Borg repository. Designed for TrueNAS but works anywhere Docker runs.

Built on Borg 1.4.4 (pinned to the Alpine borgbackup package; see Dockerfile⁠).

⁠Overview

Why Docker Borg Client?

If you're running a home server, NAS, or any system with important data, you need reliable, automated backups. This container solves my backup problem of TrueNAS to a remote Borg:

• Set it and forget it - Configure once, runs forever. Automated backups on your schedule with smart retention policies that keep recent backups while pruning old ones.
• Production Upstream technology - Built on BorgBackup⁠, used by thousands for petabytes of data. Provides deduplication, compression, and encryption that can reduce backup sizes by 95%+.
• Cost-effective - Works with any SSH-accessible storage: a Raspberry Pi at a friend's house, cloud hosting provider, or any VPS. No vendor lock-in.
• TrueNAS optimized - Built for the TrueNAS ecosystem - but in theory should run on an docker enginer.
• Data Safety First - Built, tested, and refined on real production data. Features automatic integrity checking, checkpoint-based resumption for interrupted backups, and comprehensive restore verification tools. Your backups are only as good as your ability to restore them.
• Security by Design - Client-side encryption before data leaves your server. Even if your backup destination is compromised, your data remains encrypted and safe. Zero-knowledge architecture means only you have the keys.

Perfect for:

• Home lab enthusiasts backing up Docker volumes, databases, and configuration
• TrueNAS users wanting automated off-site backups of their datasets
• Small businesses needing GDPR-compliant encrypted backups
• Anyone who learned the hard way that RAID is not a backup

⁠Table of Contents

• Overview⁠
• Features⁠
• Quick Start⁠
  • Prerequisites⁠
  • TrueNAS SCALE Setup⁠
  • Docker Compose Setup⁠
• Configuration Reference⁠
  • Environment Variables⁠
  • Job History Variables⁠
  • Backup Time Window and Rate Limiting⁠
  • Repository Integrity Verification⁠
  • Restore Drill Variables⁠
  • Volume Mounts⁠
• Recovery⁠
  • Recovery Quick Reference⁠
  • Restoring Files⁠
  • Browsing an Archive (FUSE Mount)⁠
  • Restore Drills: Proving Recoverability⁠
  • Startup Preflight⁠
• Manual Operations⁠
• Docker Compose Example⁠
• Additional Guides⁠
• Cron Schedule Examples⁠
• Job History⁠
• Monitoring⁠
• Troubleshooting⁠
• Security Best Practices⁠
• Disaster Recovery⁠
• Contributing⁠
• Licence⁠
• Acknowledgements⁠

⁠Features

• 🔒 Secure: Client-side encryption with SSH key authentication
• 🐧 Minimal: Alpine Linux + Borg + SSH client only
• 🔧 Generic: Works with any Borg-over-SSH target (Hetzner, rsync.net, self-hosted)
• 📅 Automated: Configurable cron-based scheduled backups
• ♻️ Smart retention: Automatic pruning with configurable policies
• 🚑 Proven recovery: Scheduled restore drills⁠ that actually restore files and compare them to the source
• 🛡️ Fail-safes: Startup recovery-readiness checks⁠, refusal to restore over live data, drills that never break a running backup's lock
• 🏗️ Multi-arch: Supports amd64 and arm64

⁠Quick Start

⁠Prerequisites

1. A remote Borg repository accessible via SSH (see Provider Guides⁠)
2. SSH key pair for authentication
3. Docker and Docker Compose installed (or TrueNAS SCALE)

⁠TrueNAS SCALE Setup

TrueNAS SCALE users can deploy this container using the Custom App feature:

1. Prepare SSH Keys:

   • Create a directory for your SSH keys:

     mkdir -p /mnt/pool/borg-backup/ssh
     ssh-keygen -t ed25519 -f /mnt/pool/borg-backup/ssh/key -N ""
     chmod 700 /mnt/pool/borg-backup/ssh
     chmod 600 /mnt/pool/borg-backup/ssh/key
     

     Copy
   • Add the public key to your remote backup server:

     cat /mnt/pool/borg-backup/ssh/key.pub
     

     Copy

2. Deploy Custom App:

   • Navigate to Apps → Discover Apps → Custom App
   • Click Install on Custom App
   • Configure the following:

   Application Name: borg-backup

   Image Configuration:

   • Image Repository: diarmuidk/docker-borg-client
   • Image Tag: latest
   • Image Pull Policy: Always

   Container User and Group (under Advanced Settings):

   • User ID: 0

   • Group ID: 0

   Note: This container runs as root (UID/GID 0:0) to ensure reliable access to all backup paths. Backup containers require broad filesystem access by design. Privileged mode is not required.

   Environment Variables (Required - add all of these):

   BORG_REPO=ssh://[email protected]:22/~/backups
   BORG_PASSPHRASE=your-strong-passphrase-here
   BACKUP_PATHS=/data/dataset1:/data/dataset2
   CRON_SCHEDULE=0 2 * * 0
   PRUNE_KEEP_DAILY=7
   PRUNE_KEEP_WEEKLY=4
   PRUNE_KEEP_MONTHLY=6
   AUTO_INIT=true
   

   Copy

   Note: Set timezone using TrueNAS's built-in Timezone dropdown (under Advanced Settings), not as an environment variable.

   Optional - Time Window Configuration (for large initial backups):

   BACKUP_WINDOW_START=01:00
   BACKUP_WINDOW_END=07:00
   BACKUP_RATE_LIMIT_IN_WINDOW=-1
   BACKUP_RATE_LIMIT_OUT_WINDOW=0
   

   Copy

   This configuration runs backups only during 1am-7am at full speed, perfect for large initial backups on limited connections.

   Storage:

   • Add Host Path Volume for SSH keys:

     • Host Path: /mnt/pool/borg-backup/ssh
     • Mount Path: /ssh
     • Read Only: ✅ Enable

   • Add Host Path Volume for each dataset to backup:

     • Host Path: /mnt/pool/your-dataset
     • Mount Path: /data/dataset1
     • Read Only: ✅ Enable

   • Add ixVolume for Borg cache:

     • Mount Path: /borg/cache

   • Add ixVolume for Borg config:

     • Mount Path: /borg/config

   Restart Policy: Unless Stopped

3. Initialize Repository:

   Option A - Automatic (Recommended):

   • Add AUTO_INIT=true to environment variables
   • Start the app - repository will be automatically initialized on first run
   • Check logs to see initialization message and backup the credentials
   • Navigate to Apps → Installed → borg-backup → Shell
   • Run: cat /borg/config/repo-key.txt and save to password manager

   Option B - Manual:

   • After deployment, access the container shell via TrueNAS web UI
   • Navigate to Apps → Installed → borg-backup → Shell
   • Run: /scripts/init.sh
   • Backup your passphrase and the repository key to password manager

4. Monitor Backups:

   • View logs: Apps → Installed → borg-backup → Logs
   • Backups will run automatically according to your cron schedule

⁠TrueNAS-Specific Notes

Timezone Configuration:

• Do NOT add TZ as a manual environment variable in TrueNAS Custom Apps
• TrueNAS automatically manages timezone - look for a Timezone dropdown in the app configuration
• Adding TZ manually will cause deployment errors: Environment variable [TZ] is already defined

SSH Key Permissions:

• Private key must be 600 (read/write for owner only)
• SSH directory must be 700 (read/write/execute for owner only)
• If permissions are incorrect, SSH authentication will silently fail

Testing SSH Connection:

Before deploying, verify SSH key authentication works:

ssh -i /mnt/pool/borg-backup/ssh/key -p <port> [email protected]

If prompted for password, SSH key is not configured correctly on remote server.

⁠Docker Compose Setup

1. Generate SSH keys (if you don't have them):

   mkdir -p ssh
   ssh-keygen -t ed25519 -f ssh/key -N ""
   

   Copy

2. Add the public key to your backup server:

   cat ssh/key.pub
   # Copy this and add it to ~/.ssh/authorized_keys on your backup server
   

   Copy

3. Configure environment:

   cp .env.example .env
   # Edit .env with your settings
   

   Copy

4. Initialize the Borg repository (one-time):

   docker compose run --rm borg-backup /scripts/init.sh
   

   Copy

5. Start the backup container:

   docker compose up -d
   

   Copy

⁠Configuration Reference

⁠Environment Variables

⁠Restore Drill Variables (Optional)

⁠Job History Variables (Optional)

Every job records its outcome to a persistent file, so a failure survives log rotation, a redeploy and an app restart.

Recorded events: backup.success, backup.failure, prune.success, prune.failure, verify.success, verify.failure, restore.success, restore.failure, container.startup, container.shutdown

See Job History⁠.

⁠Backup Time Window and Rate Limiting (Optional)

Rate Limit Values:

• -1 = Unlimited bandwidth (burst speeds)
• 0 = Terminate backup outside window, auto-resume from checkpoint (only valid for BACKUP_RATE_LIMIT_OUT_WINDOW)
• Positive number = Bandwidth limit in Mbps (e.g., 40 = 40 Mbps)

Use Cases:

1. Large initial backup on limited connection (e.g., 1.5TB on 40 Mbps):

   BACKUP_WINDOW_START=01:00
   BACKUP_WINDOW_END=07:00
   BACKUP_RATE_LIMIT_IN_WINDOW=-1    # Unlimited overnight
   BACKUP_RATE_LIMIT_OUT_WINDOW=0    # Terminated and resumed via checkpoint
   

   Copy
   • Backup runs at full speed during 1am-7am window
   • Automatically terminated at 7am (checkpoint polling in final 30 min)
   • Resumes next night from last checkpoint
   • Completes 1.5TB in 3-4 nights with minimal rework

2. Continuous backup with daytime throttle:

   BACKUP_WINDOW_START=22:00
   BACKUP_WINDOW_END=08:00
   BACKUP_RATE_LIMIT_IN_WINDOW=-1    # Unlimited overnight
   BACKUP_RATE_LIMIT_OUT_WINDOW=5    # 5 Mbps trickle during day
   

   Copy

3. Daytime backup with bandwidth limit:

   BACKUP_WINDOW_START=09:00
   BACKUP_WINDOW_END=17:00
   BACKUP_RATE_LIMIT_IN_WINDOW=20    # 20 Mbps during business hours
   BACKUP_RATE_LIMIT_OUT_WINDOW=0    # Terminated outside business hours
   

   Copy

How It Works:

• Borg (1.1+) automatically creates checkpoints every 30 minutes during backup
• When backup window ends with BACKUP_RATE_LIMIT_OUT_WINDOW=0:
  • Monitor polls for new checkpoints in final 30 minutes of window
  • If new checkpoint detected → backup terminated immediately (minimizes wasted work)
  • If window ends → backup terminated at deadline (hard stop)
  • Zero out-of-window bandwidth usage (never exceeds window)
• Next backup run automatically resumes from last checkpoint
• Container restarts automatically break stale locks and resume from checkpoint
• No manual intervention required

Requirements:

• Borg 1.1 or later (for checkpoint support within files)

⁠Repository Integrity Verification (Optional)

Scheduled borg check verification ensures your backup repository remains healthy and detects corruption early. When enabled, two verification jobs are configured automatically:

• Repository check (weekly) - Fast verification of repository structure
• Archives check (monthly) - Deeper verification of archive metadata integrity

Verification Levels:

Example Configuration:

VERIFY_ENABLED=true
VERIFY_REPO_CRON_SCHEDULE=0 6 * * 0      # Weekly Sunday 6am
VERIFY_ARCHIVES_CRON_SCHEDULE=0 6 1 * *  # Monthly 1st at 6am

Leave room after your backup. A check needs the repository lock, and a running backup holds it, so a check that fires while the backup is still going waits VERIFY_LOCK_WAIT seconds and then skips. With a nightly backup at 01:00 that takes two hours, a check at 03:00 skips every week; 06:00 leaves headroom for the backup to grow.

Behaviour Notes:

• A check never interrupts a running backup. It waits up to VERIFY_LOCK_WAIT seconds (300 by default) for the repository lock, then skips with a verify.skipped entry in the job history and runs on the next schedule. It does not break the lock
• A skipped check is reported on every container start by the startup preflight, so a check that keeps skipping does not go unnoticed
• Verification is read-only and does not respect backup windows (no bandwidth impact)
• full level reads all repository data and is very slow on large repos - use for manual spot-checks only
• No double-runs: If the archives day falls on a repo day (e.g., 1st is a Sunday), only the archives check runs - the repository check is automatically skipped

Manual Verification:

# Quick repository check
docker compose run --rm borg-backup /scripts/verify.sh

# Archives check
docker compose run --rm -e VERIFY_LEVEL=archives borg-backup /scripts/verify.sh

# Full data verification (slow - use for spot checks)
docker compose run --rm -e VERIFY_LEVEL=full borg-backup /scripts/verify.sh

⁠Volume Mounts

⁠Recovery

This container treats recovery as a first-class operation: the same scripts that take backups can list, inspect, verify and restore them, and can prove on a schedule that restoring still works.

⁠Recovery Quick Reference

Every command below runs inside the container. On TrueNAS use Apps → Installed → borg-backup → Shell; with Compose use docker compose exec borg-backup <command> (or run --rm on a stopped stack).

Any archive name may be given as latest, which resolves to the newest archive (Borg 1.x has no ::latest pseudo-archive, so the container resolves it for you).

⁠Restoring Files

Restores never write to your source data. Extract into a dedicated directory and move files back yourself once you have checked them.

# Everything, into a restore volume
docker compose run --rm -v /mnt/pool/borg-restore:/restore borg-backup \
  /scripts/restore.sh extract latest /restore

# Just the paths you need - far quicker on a large repository
docker compose run --rm -v /mnt/pool/borg-restore:/restore borg-backup \
  /scripts/restore.sh extract latest /restore data/documents/tax-2025.pdf

Paths inside an archive are stored without a leading slash: a source path of /data/documents appears in the archive as data/documents. Use /scripts/restore.sh files latest <pattern> to find the exact path.

Built-in fail-safes. extract refuses to run if the destination is / or sits inside any configured BACKUP_PATHS, because Borg would recreate the original tree there and overwrite the very data you are recovering. It also warns when the destination is not empty.

⁠Browsing an Archive (FUSE Mount)

Mounting is the cheapest way to pick a few files out of a multi-terabyte archive: Borg fetches only the data you actually read.

Mounting needs kernel FUSE access, which Docker does not grant by default:

services:
  borg-backup:
    devices:
      - "/dev/fuse"
    cap_add:
      - "SYS_ADMIN"
    security_opt:
      - "apparmor=unconfined"

docker run --rm -it --device /dev/fuse --cap-add SYS_ADMIN \
  --security-opt apparmor=unconfined \
  -e BORG_REPO=... -e BORG_PASSPHRASE=... \
  -v ./ssh:/ssh:ro diarmuidk/docker-borg-client \
  /scripts/restore.sh mount latest /mnt/backup

Without those options restore.sh mount exits with instructions rather than a bare FUSE mount failed. If you cannot grant them, use extract instead - it needs no special privileges.

⁠Restore Drills: Proving Recoverability

borg check verifies that the repository is structurally sound. It does not verify that you can get your files back. A restore drill does:

1. Resolves the archive to drill (newest by default).
2. Picks a sample of real files from it, rotating the selection by day so successive drills cover different data.
3. Restores them to a temporary directory.
4. Compares each restored file against the live source byte-for-byte (SHA-256) when the source still exists.
5. Reports a summary and writes a restore.success / restore.failure entry to the job history⁠.

RESTORE_DRILL_ENABLED=true
RESTORE_DRILL_CRON_SCHEDULE=0 4 1 1,4,7,10 *   # Quarterly, 1st at 04:00
RESTORE_DRILL_SAMPLE_COUNT=3

Run one on demand at any time:

docker compose exec borg-backup /scripts/restore.sh drill

Pin the drill to the files t