Borg Web UI

A modern web interface for Borg Backup. Zero-configuration deployment - just run and go.

Documentation | Docker Hub

---

Note

This project uses Claude Code as a development assistant. I'm a full-stack developer with 10+ years of experience, and I personally review all AI-generated code before merging. Architecture decisions, security practices, and testing are human-driven. Claude Code is acknowledged as a co-author in git commits. All code is open source for community review - your backups deserve scrutiny, and I encourage it.

---

Screenshots

---

Features

• Backup Management - Create, schedule, and monitor backups with live progress tracking
• Archive Browser - Browse and restore files from any backup archive
• Repository Management - Support for local, SSH, and SFTP repositories with multiple compression options
• Scheduling - Visual cron job builder with execution history
• Pre/Post Backup Hooks - Run custom scripts before/after backups (e.g., stop Docker containers, database dumps)
• Notifications - Get alerts for backup failures and completions via 100+ services (Email, Slack, Discord, Telegram, Pushover, etc.)
• SSH Key Management - Generate, import, and deploy SSH keys for remote repositories
• Real-time Monitoring - Live backup progress, system metrics, and health checks
• Multi-platform - Supports amd64, arm64, and armv7 architectures

---

Quick Start

Docker Compose (Recommended)

Create docker-compose.yml:

version: '3.8'

services:
  borg-ui:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      # Mount directories you want to backup (REPLACE with your actual paths)
      - /home/yourusername:/local:rw           # Replace with your directory path
      # - /mnt/data:/local/data:rw             # Additional directories as needed
    environment:
      - TZ=America/Chicago  # Set your timezone
      - PUID=1000
      - PGID=1000

volumes:
  borg_data:
  borg_cache:

⚠️ Security Note: Replace /home/yourusername with your actual directory path. Only mount directories you want to backup. See the Configuration Guide for more examples and security best practices.

Start the container:

docker compose up -d

Access at http://localhost:8081

Default credentials: admin / admin123 (you'll be prompted to change on first login)

Docker Run

docker volume create borg_data
docker volume create borg_cache

docker run -d \
  --name borg-web-ui \
  --restart unless-stopped \
  -p 8081:8081 \
  -e TZ=America/Chicago \
  -e PUID=1000 \
  -e PGID=1000 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/yourusername:/local:rw \
  ainullcode/borg-ui:latest

Notes:

• Replace /home/yourusername with your actual directory path (e.g., /home/john, /Users/sarah, /mnt/data)
• Replace 1000 with your user/group ID. Find yours with id -u && id -g
• Add more -v flags for additional directories you want to backup
• See Configuration Guide for security best practices

---

Documentation

Full Documentation - Complete guides and tutorials

• Installation Guide - Detailed installation for all platforms
• Configuration Guide - Environment variables and setup options
• Docker Container Hooks - Stop/start Docker containers during backups
• Notifications Setup - Configure alerts via email, Slack, Discord, and more
• SSH Keys Guide - Setting up SSH for remote backups
• Security Guide - Best practices and security recommendations
• API Documentation - Interactive API docs (after installation)

---

Configuration

Auto-Configured on First Run

• SECRET_KEY - Randomly generated and persisted
• Database - SQLite at /data/borg.db (includes encrypted SSH keys)
• SSH Keys - Stored encrypted in database, deployed to /home/borg/.ssh at runtime

Optional Environment Variables

Variable	Description	Default
PORT	Application port	8081
TZ	Timezone (e.g., America/Chicago, Europe/London, Asia/Kolkata)	Host timezone
PUID	User ID for file permissions	1001
PGID	Group ID for file permissions	1001
LOG_LEVEL	Logging level	INFO

---

Data Persistence

Two volumes are used for persistent data:

• borg_data - Application data, database, SSH keys, logs
• borg_cache - Borg repository caches for better performance

Volume Mounts for Backup Sources

⚠️ Important Security Consideration:

The container needs access to directories you want to backup. Instead of mounting your entire filesystem (/:/local:rw), mount only specific directories you need:

volumes:
  # ✅ Recommended: Mount specific directories
  - /home/yourusername:/local:rw       # Replace with your path
  - /mnt/data:/local/data:rw           # Additional directories

  # ❌ NOT Recommended: Full filesystem access
  # - /:/local:rw  # Security risk - avoid unless absolutely necessary

Best Practices:

• Mount only directories that contain data to backup
• Use read-only (:ro) for backup-only directories if you don't need to restore to them
• For multiple directories, add multiple volume mounts instead of mounting root
• See the Configuration Guide for detailed examples

---

Support

• Documentation: Full Documentation
• Bug Reports: GitHub Issues
• Discussions: GitHub Discussions

---

Development

For developers who want to contribute:

git clone https://github.com/karanhudia/borg-ui.git
cd borg-ui
docker compose up -d --build

See CONTRIBUTING.md for guidelines.

---

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

---

Built with Borg Backup, FastAPI, React, and Material-UI

Made by Karan Hudia