Skip to main content

​
Overview

This guide walks you through creating your first backup with Borg UI, from setting up a repository to monitoring backup progress in real-time.

​
Prerequisites

Before starting, ensure you have:
  • Borg UI installed and running
  • Access to the web interface (default: http://localhost:8081)
  • Default credentials: admin / admin123
  • A directory to store backups (local or remote)
For production use, change the default password immediately after first login.

​
Step 1: Create a Repository

A repository is where Borg stores your encrypted and deduplicated backup archives.
1

Navigate to Repositories

Click Repositories in the sidebar to access the repository management page.
2

Click Create Repository

Click the Create Repository button to open the repository creation dialog.
3

Configure Repository Settings

Fill in the following fields:
  • Repository Name: A friendly name (e.g., “Home Server Backups”)
  • Path: Where to store the repository
    • Local: /data/backups/my-repo (inside container)
    • Host filesystem: /local/backups/my-repo (maps to host)
  • Encryption: Choose encryption mode
    • repokey: Key stored in repository (recommended)
    • keyfile: Key stored separately (more secure)
    • none: No encryption (not recommended)
  • Passphrase: Required for encrypted repositories
  • Compression: Choose compression algorithm
    • lz4: Fast, moderate compression (recommended)
    • zstd: Balanced speed and compression
    • zlib: Higher compression, slower
    • lzma: Maximum compression, slowest
4

Add Source Directories

Specify which directories to back up:
/local/home/user/documents
/local/home/user/photos
/local/etc
Use /local/ prefix to access directories from your host machine. The container’s / is mapped to /local/ inside the container.
5

Add Exclude Patterns (Optional)

Exclude files you don’t want to back up:
*.log
*.tmp
*~
.cache
node_modules
__pycache__
Exclude patterns support wildcards and follow Borg’s pattern syntax.
6

Create the Repository

Click Create Repository to initialize the Borg repository. This process:
  • Creates the repository directory structure
  • Initializes encryption keys
  • Stores configuration in the database

​
Step 2: Run Your First Backup

Once the repository is created, you can start backing up your data.
1

Navigate to the Repository

From the Repositories page, click on your newly created repository to view its details.
2

Start Manual Backup

Click the Backup Now button to start an immediate backup.The backup job is created with status “pending” and begins executing in the background.
3

Monitor Progress

Borg UI displays real-time progress including:
  • Current file: Path of the file being processed
  • Backup speed: Transfer rate in MB/s
  • Files processed: Number of files backed up
  • Data statistics:
    • Original size: Uncompressed data size
    • Compressed size: After compression
    • Deduplicated size: Actual space used (after deduplication)
  • Progress percentage: Overall completion
  • Estimated time remaining: Based on current speed
Borg’s deduplication means subsequent backups are much faster and use minimal additional space.
4

View Backup Results

When complete, the backup status changes to:
  • Completed: Backup finished successfully
  • Completed with warnings: Minor issues occurred
  • Failed: Backup encountered errors
Click on the backup job to view detailed logs if needed.

​
Understanding Backup Progress

Borg UI parses Borg’s JSON output to provide real-time feedback: 
{
  "original_size": 5368709120,
  "compressed_size": 4294967296,
  "deduplicated_size": 2147483648,
  "nfiles": 12543,
  "current_file": "/local/home/user/documents/report.pdf",
  "progress_percent": 67.5,
  "backup_speed": 45.2,
  "estimated_time_remaining": 180
}

​
Pre/Post Backup Hooks

You can run scripts before and after backups to automate tasks like stopping services or creating database dumps.
Runs before backup starts. Use for:
  • Stopping Docker containers
  • Creating database dumps
  • Flushing caches
#!/bin/bash
# Stop services before backup
docker stop myapp
mysqldump -u root mydb > /local/backups/mysql-dump.sql
If a pre-backup script fails, the backup is cancelled unless “Continue on hook failure” is enabled.

​
Adding Hooks to Repository

  1. Edit your repository settings
  2. Scroll to Backup Hooks section
  3. Enter your script in Pre-Backup Script or Post-Backup Script
  4. Set Hook Timeout (default: 300 seconds)
  5. Enable Continue on hook failure if desired
  6. Save changes
Hooks run inside the Borg UI container. Use /local/ paths to access host files and Docker socket mounting to control containers.

​
Viewing Archives

After your first backup completes, you can browse the archive:
  1. Navigate to the repository details page
  2. Click the Archives tab
  3. See your newly created archive with timestamp
  4. Click Browse to explore files in the archive
  5. Use the file browser to navigate and verify your backup

​
Next Steps

Schedule Backups

Automate backups with cron schedules

Restore Files

Learn how to restore files from archives

Remote Repositories

Set up SSH/SFTP remote backup storage

Backup Scripts

Advanced hook scripts and automation

​
Troubleshooting

​
Backup Fails with Permission Denied

If backing up files outside the container: 
# On host machine, give container access
sudo chown -R 1000:1000 /path/to/backup
Or mount with proper permissions in Docker: 
volumes:
  - /path/to/backup:/local/backup:rw

​
Repository Already Exists

If the path already contains a Borg repository, use Import Repository instead of Create Repository to add it to Borg UI.

​
Slow Initial Backup

First backups are always slower because:
  • All data must be processed and uploaded
  • Compression and encryption add overhead
  • Deduplication builds the initial chunk database
Subsequent backups are much faster due to deduplication.
Use lz4 compression for the best balance of speed and compression. Avoid lzma unless storage space is critical.

Build docs developers (and LLMs) love

Get started for freeTalk to us