Repository Management

Overview

Borg UI provides comprehensive repository management with support for multiple storage backends, encryption modes, and compression algorithms. Create new repositories or import existing ones with a streamlined workflow.

Storage Backends

Local Storage
SSH
SFTP

Store repositories directly on the filesystem where Borg UI is running.Path Examples:

/data/backups/my-repo - Container storage
/local/home/user/backups - Host filesystem via Docker mount

Paths starting with /local/ access your host filesystem through Docker volume mounts. Paths without this prefix are stored inside the container.

Connect to remote servers via SSH for off-site backups.Requirements:

SSH connection configured in Settings
SSH key authentication recommended
Borg installed on remote server

Example SSH URL:

ssh://[email protected]:22/backups/my-repo

Some restricted SSH servers (like Hetzner Storage Box) don’t support diagnostic commands but Borg operations work normally.

Encryption Modes

Borg UI supports all Borg encryption modes:

Choose Encryption Mode

Select from available encryption modes based on your security requirements:

Mode	Description	Key Storage
repokey	Encryption key stored in repository	Repository config
keyfile	Encryption key stored separately	`~/.config/borg/keys/`
repokey-blake2	Repokey with BLAKE2 hash	Repository config
keyfile-blake2	Keyfile with BLAKE2 hash	`~/.config/borg/keys/`
none	No encryption (not recommended)	N/A

repokey modes are convenient for single-user setups. keyfile modes allow sharing keys across multiple machines.

Set Passphrase

For encrypted repositories, provide a strong passphrase:

# From repositories.py:468-473
if repo_data.encryption in ["repokey", "keyfile", "repokey-blake2", "keyfile-blake2"]:
    if not repo_data.passphrase or repo_data.passphrase.strip() == "":
        raise HTTPException(
            status_code=400,
            detail=f"Passphrase is required for encryption mode '{repo_data.encryption}'"
        )

Store your passphrase securely! Lost passphrases cannot be recovered and will make your backups inaccessible.

Manage Keyfiles (Optional)

For keyfile-based encryption, Borg UI automatically manages keys:

Upload Keyfile: Import existing keyfiles via API endpoint
Download Keyfile: Export keys for backup or sharing
Automatic Storage: Keys stored in ~/.config/borg/keys/

# Keyfile naming convention from repositories.py:51-66
# /local/Users/foo/backups/repo → local_Users_foo_backups_repo
# ssh://user@host:22/backups → user_host_22_backups

Compression Algorithms

Choose compression based on your performance vs. storage requirements:

lz4 (Default)

Fast compression with minimal CPU overhead

Compression ratio: ~2:1 to 3:1
Speed: Very fast (300+ MB/s)
Best for: General use, modern hardware
CPU usage: Low

# Default compression from repositories.py:306
compression: str = "lz4"

zstd

Balanced compression with good ratio

Compression ratio: ~3:1 to 5:1
Speed: Fast (100-200 MB/s)
Best for: Balance of speed and storage
CPU usage: Medium
Supports compression levels (1-22)

zlib

Good compression ratio, slower speed

Compression ratio: ~3:1 to 6:1
Speed: Moderate (50-100 MB/s)
Best for: Storage-constrained environments
CPU usage: Medium-High
Supports compression levels (1-9)

lzma

Maximum compression ratio

Compression ratio: ~5:1 to 10:1
Speed: Slow (20-50 MB/s)
Best for: Archival storage, rarely accessed data
CPU usage: High
Supports compression levels (0-9)

auto

Borg auto-detectionBorg automatically selects compression based on file type:

Already compressed files: No compression
Compressible files: lz4 compression

obfuscate

Data obfuscation without compression

Makes data patterns less obvious
No compression benefit
Same size as original data

Creating a Repository

Navigate to Repositories

Click Repositories in the sidebar, then Create Repository.

Configure Basic Settings

Fill in repository details:

interface RepositoryCreate {
  name: string;                    // Display name
  path: string;                    // Storage path
  encryption: string;              // Encryption mode
  compression: string;             // Compression algorithm
  passphrase?: string;             // Required for encrypted repos
  source_directories: string[];    // Directories to backup
  exclude_patterns?: string[];     // File patterns to exclude
}

Set Source Directories

Specify which directories to backup:

{
  "source_directories": [
    "/local/home/user/documents",
    "/local/var/www",
    "/local/etc/nginx"
  ]
}

Source directories are required for repositories in full mode. Observability-only repositories don’t need source directories.

Configure Exclusions (Optional)

Use exclude patterns to skip files:

{
  "exclude_patterns": [
    "*.log",
    "*.tmp",
    "node_modules",
    "__pycache__",
    ".git"
  ]
}

Advanced Options

Configure optional settings:

Remote Path: Custom borg binary path (e.g., /usr/local/bin/borg)
Custom Flags: Additional borg create flags
Bypass Lock: Read-only access for observe-only mode
Pre/Post Scripts: Hooks to run before/after backups

Importing Existing Repositories

Import repositories created outside Borg UI:

# From repositories.py:704-950
@router.post("/import")
async def import_repository(
    repo_data: RepositoryImport,
    current_user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    """Import an existing Borg repository"""

Verify Repository

Borg UI validates the repository using borg info:

# Verification from repositories.py:831-838
verify_result = await verify_existing_repository(
    repo_path,
    repo_data.passphrase,
    ssh_key_id_for_verify,
    repo_data.remote_path,
    repo_data.bypass_lock
)

Import Keyfile (If Needed)

For keyfile encryption, upload your existing keyfile:

# Keyfile handling from repositories.py:819-828
if repo_data.keyfile_content:
    keyfile_dir = os.path.expanduser("~/.config/borg/keys")
    os.makedirs(keyfile_dir, exist_ok=True)
    keyfile_name = _borg_keyfile_name(repo_path)
    keyfile_path = os.path.join(keyfile_dir, keyfile_name)
    with open(keyfile_path, 'w') as f:
        f.write(repo_data.keyfile_content)
    os.chmod(keyfile_path, 0o600)

Update Statistics

Archive count and size are automatically updated:

# From repositories.py:913-920
try:
    await update_repository_stats(repository, db)
except Exception as e:
    logger.warning("Failed to update repository stats after import",
                  repository=repository.name,
                  error=str(e))

Repository Modes

Full Mode
Observe Mode

Complete backup and observability

Create new backups
Browse and restore archives
Schedule automated backups
Full repository management

# From repositories.py:318
mode: str = "full"  # full: backups + observability

Read-only observability

Browse existing archives
Restore files from backups
View repository statistics
Cannot create new backups

# From repositories.py:319
bypass_lock: bool = False  # Use --bypass-lock for read-only access

Observe mode is perfect for repositories managed by external systems where you only need restore capabilities.

SSH Path Prefix

For remote storage with non-standard paths (e.g., Synology NAS):

# From repositories.py:529-541
ssh_path_prefix = connection_details.get("ssh_path_prefix")
if ssh_path_prefix:
    ssh_path_prefix = ssh_path_prefix.strip()
    if ssh_path_prefix and not ssh_path_prefix.startswith("/"):
        ssh_path_prefix = f"/{ssh_path_prefix}"
    repo_path_for_ssh = f"{ssh_path_prefix}/{repo_path.lstrip('/')}"
    logger.info("Applying SSH path prefix",
               original_path=repo_path,
               prefix=ssh_path_prefix,
               final_path=repo_path_for_ssh)

Example Use Case:

Synology NAS with /volume1 prefix
Custom chroot environments
Restricted SSH shells

Repository Statistics

Borg UI automatically tracks repository metrics:

# From repositories.py:165-283
async def update_repository_stats(repository: Repository, db: Session) -> bool:
    """Update archive count and repository size stats by querying Borg"""
    
    # Get archive list and count
    list_result = await borg.list_archives(
        repository.path,
        remote_path=repository.remote_path,
        passphrase=repository.passphrase,
        bypass_lock=use_bypass_lock
    )
    
    # Update repository size from borg info
    info_data = json.loads(stdout.decode())
    cache = info_data.get("cache", {}).get("stats", {})
    unique_csize = cache.get("unique_csize", 0)

Tracked Metrics:

Archive count
Total repository size
Last backup timestamp
Compression effectiveness
Deduplication ratio

Lock Configuration

Borg UI configures repository locks to prevent conflicts:

# From repositories.py:94-119
def setup_borg_env(base_env=None, passphrase=None, ssh_opts=None):
    """Setup Borg environment variables with lock and timeout configuration"""
    
    # Configure lock behavior to prevent timeout issues
    env["BORG_LOCK_WAIT"] = "180"  # Wait up to 3 minutes for locks
    env["BORG_HOSTNAME_IS_UNIQUE"] = "yes"  # Mark hostname as unique
    env["BORG_RELOCATED_REPO_ACCESS_IS_OK"] = "yes"  # Allow relocated repos

Best Practices

Encryption: Always use encryption for sensitive data
Passphrases: Use strong, unique passphrases (20+ characters)
Keyfile Backup: Store keyfile backups in a secure location
Test Restores: Regularly verify backups are recoverable
Remote Backups: Use SSH for off-site disaster recovery
Compression: Start with lz4, adjust based on storage needs

API Reference

Create Repository

POST /api/repositories/

Request Body:

{
  "name": "Production Backups",
  "path": "/local/backups/prod",
  "encryption": "repokey-blake2",
  "compression": "zstd",
  "passphrase": "your-secure-passphrase",
  "source_directories": ["/local/var/www", "/local/etc"],
  "exclude_patterns": ["*.log", "*.tmp"],
  "mode": "full"
}

Import Repository

POST /api/repositories/import

Request Body:

{
  "name": "Imported Repo",
  "path": "/local/backups/existing",
  "passphrase": "existing-passphrase",
  "compression": "lz4",
  "mode": "observe",
  "bypass_lock": true
}

Upload Keyfile

POST /api/repositories/{repo_id}/keyfile

Multipart Form Data:

keyfile: <binary file>

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

Repository Management

Overview

Storage Backends

Encryption Modes

Compression Algorithms

Creating a Repository

Importing Existing Repositories

Repository Modes

SSH Path Prefix

Repository Statistics

Lock Configuration

Best Practices

API Reference

Create Repository

Import Repository

Upload Keyfile

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Overview

​Storage Backends

​Encryption Modes

​Compression Algorithms

​Creating a Repository

​Importing Existing Repositories

​Repository Modes

​SSH Path Prefix

​Repository Statistics

​Lock Configuration

Best Practices

​API Reference

​Create Repository

​Import Repository

​Upload Keyfile

Build docs developers (and LLMs) love

Overview

Storage Backends

Encryption Modes

Compression Algorithms

Creating a Repository

Importing Existing Repositories

Repository Modes

SSH Path Prefix

Repository Statistics

Lock Configuration

API Reference

Create Repository

Import Repository

Upload Keyfile