# Borgmatic Director UI for professionals

# Borgmatic Director UI - Professional Administration Guide

<p class="callout info">This guide is intended for system administrators and IT professionals who need comprehensive knowledge of the Borgmatic Director UI application, its operating modes, configuration options, and administrative features.</p>

---

## Operating Modes

Borgmatic Director UI supports three operating modes for different deployment scenarios. Understanding these modes is essential for proper deployment planning.

### Mode Comparison Matrix

<table id="bkmrk-feature-standalone-c"><thead><tr><th>Feature</th><th>Standalone</th><th>Client</th><th>Director</th></tr></thead><tbody><tr><td>Manage local backups</td><td>✅</td><td>✅</td><td>✅ (via client proxy)</td></tr><tr><td>Full local web UI</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td>Connect to Director</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td>Manage multiple machines</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td>Approve client connections</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td>Deploy templates to clients</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td>Aggregate monitoring dashboard</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td>Receive remote commands</td><td>❌</td><td>✅</td><td>❌</td></tr></tbody></table>

---

### 1. Standalone Mode (Default)

Standalone mode is the default operating mode. The instance operates independently, managing backups on a single server with no external connections.

#### Use Cases

- Single server deployments
- Home labs and personal servers
- Small businesses with one backup server
- Testing and development environments
- Air-gapped or isolated systems

#### Configuration

No additional configuration required. This is the default state after installation.

```
# Identity configuration file: /app/data/config/identity.json
{
  "mode": "standalone",
  "instance_id": "auto-generated-uuid",
  "instance_name": "My Backup Server"
}
```

#### Available Features

- Full backup job management (create, edit, delete, run)
- Repository management (local, SSH, S3, Rclone)
- Archive browsing and restore
- Schedule management
- SSH key management
- YAML configuration editor
- Real-time backup monitoring
- Notifications (email, webhooks, etc.)

---

### 2. Client Mode

Client mode allows the instance to be remotely managed by a central Director server while retaining full local functionality.

#### Use Cases

- Multiple servers managed by a central IT team
- Distributed infrastructure requiring unified management
- Managed Service Provider (MSP) client deployments
- Branch offices connected to headquarters

#### Configuration Steps

1. Navigate to **Settings → Operating Mode**
2. Click the toggle to switch from Standalone to Client mode
3. Configure connection settings: 
    - **Client Name:** Human-readable identifier (e.g., "Production Web Server")
    - **Identification Phrase:** Secret phrase shown to Director admin for verification
    - **Director URL:** WebSocket URL (e.g., `wss://director.example.com`)
    - **Director Port:** Default is 9000
4. Save and initiate connection
5. Wait for Director admin to approve the connection request

#### Authentication Security

Client authentication uses Ed25519 cryptographic keypairs:

1. **Keypair Generation:** Client generates Ed25519 keypair on first setup
2. **Registration:** Client sends public key + identification phrase to Director
3. **Approval:** Director admin verifies phrase and approves connection
4. **Challenge-Response:** All subsequent connections authenticated via cryptographic challenge

```
Authentication Flow:
1. Client → Director: "Register me" + public key + phrase
2. Director Admin: Reviews request, verifies phrase
3. Director Admin: Clicks Approve (optionally locks IP)
4. Director → Client: Issues signed JWT token
5. Future connections:
   - Director: "Sign this random challenge: XYZ123"
   - Client: Signs with private key
   - Director: Verifies signature with stored public key
   - Connection established ✅
```

#### Connection Status Indicators

<table id="bkmrk-status-indicator-mea"><thead><tr><th>Status</th><th>Indicator</th><th>Meaning</th></tr></thead><tbody><tr><td>Connected</td><td>🟢 Green</td><td>Active connection to Director</td></tr><tr><td>Pending</td><td>🟡 Yellow</td><td>Awaiting Director approval</td></tr><tr><td>Disconnected</td><td>🔴 Red</td><td>No connection (network issue or Director offline)</td></tr><tr><td>Rejected</td><td>⛔ Blocked</td><td>Connection rejected by Director admin</td></tr></tbody></table>

#### Client Mode Features

- All Standalone features remain available
- Receives template deployments from Director
- Reports status and backup results to Director
- Can be monitored remotely via Director dashboard
- Automatic reconnection with exponential backoff

---

### 3. Director Mode

Director mode transforms the instance into a central management hub that can monitor and control multiple Client instances.

#### Use Cases

- Enterprise IT managing multiple servers
- Managed Service Providers (MSPs)
- DevOps teams managing infrastructure fleets
- Organizations requiring centralized backup oversight

#### Configuration Steps

1. Navigate to **Settings → Operating Mode**
2. Click "Switch to Director Mode"
3. Type "switch" to confirm (this is a significant change)
4. Configure Director settings: 
    - **Listen Port:** WebSocket port for client connections (default: 9000)
    - **SSL/TLS:** Enable for production (recommended)
    - **Auto-Approve:** Automatically approve new clients (not recommended)
5. Restart the server if prompted

<p class="callout warning">**Note:** Switching to Director mode enables HTTPS and may require server restart. Switching back to Standalone clears all client data.</p>

#### Network Requirements

```
┌─────────────────┐     WSS (port 9000)      ┌──────────────────┐
│   Client 1      │ ─────────────────────────>│                  │
│   (behind NAT)  │  outbound connection      │     Director     │
└─────────────────┘                           │                  │
                                              │  Public IP or    │
┌─────────────────┐     WSS (port 9000)       │  Domain name     │
│   Client 2      │ ─────────────────────────>│                  │
│   (firewall)    │  outbound connection      │  Port 9000 open  │
└─────────────────┘                           └──────────────────┘
```

- Director needs a public IP or domain name
- Director port 9000 (or configured port) must be accessible
- Clients initiate outbound connections (NAT-friendly)
- No port forwarding required on client machines
- Can use CloudFlare Tunnel or reverse proxy if Director is also behind NAT

#### Client Management Dashboard

The Director dashboard provides:

- **Connected Clients:** Real-time list of online clients with status
- **Pending Approvals:** New clients awaiting approval
- **Offline Clients:** Previously connected clients that are currently unreachable
- **Aggregate Statistics:** Total backups, repositories, success/failure rates

#### Client Approval Workflow

1. New client connects and appears in "Pending Approvals"
2. Admin reviews: 
    - Client name
    - Identification phrase (verify this matches expected)
    - IP address
    - Public key fingerprint
3. Admin decides: 
    - **Approve:** Client can connect and be managed
    - **Approve + Lock IP:** Only allow connections from current IP
    - **Reject:** Deny connection permanently

#### Managing Remote Clients

When in Director mode, a client selector appears in the navigation:

- Select a client to view/manage that client's backups, repositories, etc.
- All pages (Backups, Repositories, Archives, etc.) show data from selected client
- Actions performed affect the selected client
- "View All Clients" returns to the aggregate dashboard

#### Template Deployment

Directors can create and deploy templates to multiple clients:

- **Backup Templates:** Pre-configured backup job definitions
- **Schedule Templates:** Standardized backup schedules
- **Repository Templates:** Common repository configurations

Deployment options:

- Deploy to selected clients
- Deploy to client groups
- Deployed items are created as **inactive** for security (must be activated locally)

---

### Mode Switching Reference

<table id="bkmrk-from-to-data-impact-"><thead><tr><th>From</th><th>To</th><th>Data Impact</th><th>Action Required</th></tr></thead><tbody><tr><td>Standalone</td><td>Client</td><td>None (non-destructive)</td><td>Toggle switch + configure Director URL</td></tr><tr><td>Client</td><td>Standalone</td><td>None (non-destructive)</td><td>Toggle switch</td></tr><tr><td>Standalone/Client</td><td>Director</td><td>Enables HTTPS, adds Director features</td><td>Type "switch" to confirm + restart</td></tr><tr><td>Director</td><td>Standalone</td><td>Clears all client connection data</td><td>Type "switch" to confirm</td></tr></tbody></table>

---

## Dashboard

The Dashboard provides an at-a-glance overview of backup system health and recent activity.

### Dashboard Widgets

#### System Status

- **Backup Tools Health:** Shows installed status and versions of Borg 1.x, Borg 2.x, Borgmatic, and Rclone
- **Last Health Check:** Timestamp of most recent tool verification

#### Backup Statistics

- Total backup jobs configured
- Active vs. inactive backups
- Last 24-hour success/failure count
- Currently running backups

#### Recent Activity

- List of recent backup runs with status
- Click to view detailed logs
- Filter by status (success, failed, running)

#### Repository Overview

- Total repositories configured
- Storage usage (if available)
- Repository health status

---

## Backup Jobs

Backup Jobs define what data to back up, where to store it, and when to run.

### Creating a Backup Job

#### Basic Settings

<table id="bkmrk-field-description-re"><thead><tr><th>Field</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>Name</td><td>Human-readable identifier for the backup</td><td>Yes</td></tr><tr><td>Description</td><td>Optional notes about the backup purpose</td><td>No</td></tr><tr><td>Repository</td><td>Target repository for storing backups</td><td>Yes</td></tr><tr><td>Borg Version</td><td>Use Borg 1.x or Borg 2.x (must match repository)</td><td>Yes</td></tr><tr><td>Active</td><td>Enable/disable the backup job</td><td>Yes</td></tr></tbody></table>

#### Source Configuration

<table id="bkmrk-field-description-ex"><thead><tr><th>Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Source Directories</td><td>Paths to back up</td><td>`/host/home`, `/host/var/www`</td></tr><tr><td>Exclude Patterns</td><td>Glob patterns to exclude</td><td>`*.tmp`, `**/node_modules/**`</td></tr><tr><td>Exclude If Present</td><td>Skip directories containing these files</td><td>`.nobackup`, `CACHEDIR.TAG`</td></tr></tbody></table>

#### Advanced Options

<table id="bkmrk-option-description-d"><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>Compression</td><td>Compression algorithm and level</td><td>`zstd,3`</td></tr><tr><td>One File System</td><td>Don't cross filesystem boundaries</td><td>Enabled</td></tr><tr><td>Read Special</td><td>Read special files (devices, FIFOs)</td><td>Disabled</td></tr><tr><td>Numeric Owner</td><td>Store numeric user/group IDs</td><td>Disabled</td></tr><tr><td>No Atime</td><td>Don't store access time</td><td>Enabled</td></tr></tbody></table>

#### Retention Policy

Configure how many archives to keep:

<table id="bkmrk-setting-description-"><thead><tr><th>Setting</th><th>Description</th><th>Recommended</th></tr></thead><tbody><tr><td>Keep Hourly</td><td>Number of hourly archives</td><td>24</td></tr><tr><td>Keep Daily</td><td>Number of daily archives</td><td>7</td></tr><tr><td>Keep Weekly</td><td>Number of weekly archives</td><td>4</td></tr><tr><td>Keep Monthly</td><td>Number of monthly archives</td><td>6</td></tr><tr><td>Keep Yearly</td><td>Number of yearly archives</td><td>2</td></tr></tbody></table>

#### Hooks

Execute commands before/after backups:

<table id="bkmrk-hook-when-executed-u"><thead><tr><th>Hook</th><th>When Executed</th><th>Use Case</th></tr></thead><tbody><tr><td>Before Backup</td><td>Before archive creation starts</td><td>Database dumps, stop services</td></tr><tr><td>After Backup</td><td>After successful backup</td><td>Cleanup temp files, start services</td></tr><tr><td>On Error</td><td>When backup fails</td><td>Send alerts, cleanup</td></tr></tbody></table>

### Running Backups

- **Manual Run:** Click the "Run" button on any backup job
- **Scheduled Run:** Automatically triggered by configured schedule
- **Stop Running:** Click "Stop" to abort a running backup

### Backup Status

<table id="bkmrk-status-indicator-mea-1"><thead><tr><th>Status</th><th>Indicator</th><th>Meaning</th></tr></thead><tbody><tr><td>Idle</td><td>⚪ Gray</td><td>Not currently running</td></tr><tr><td>Running</td><td>🔵 Blue (spinner)</td><td>Backup in progress</td></tr><tr><td>Success</td><td>🟢 Green</td><td>Last run completed successfully</td></tr><tr><td>Failed</td><td>🔴 Red</td><td>Last run failed</td></tr><tr><td>Inactive</td><td>⚫ Disabled</td><td>Backup job is disabled</td></tr></tbody></table>

---

## Repositories

Repositories are the storage destinations for backup archives.

### Repository Types

#### Local Repository

- **Path format:** `/path/to/repository`
- **Use case:** Local disk, mounted NAS, attached storage
- **Performance:** Fastest backup/restore speeds
- **Configuration:** Just specify the path

#### SSH/SFTP Repository

- **Path format:** `ssh://user@hostname:port/path`
- **Use case:** Remote backup servers, dedicated storage boxes
- **Authentication:** SSH key (recommended) or password
- **Configuration:**
    - Host, port, username
    - SSH key selection or password
    - Remote path (browse with file explorer)

#### S3/Cloud Storage (Rclone)

- **Providers:** Amazon S3, Backblaze B2, Wasabi, MinIO, Google Cloud, etc.
- **Storage Modes:**
    - **Local + Cloud Sync:** Fast local backups, automatic cloud sync
    - **Native Cloud (Borg 2.x):** Direct S3 writes, no Rclone needed
- **Configuration:**
    - Select Rclone remote (pre-configured in Rclone)
    - Specify bucket/path
    - Choose storage mode

### Creating a Repository

1. Navigate to **Repositories → Create Repository**
2. Select repository type (Local, SSH, S3/Rclone)
3. Configure type-specific settings
4. Set Borg version (1.x or 2.x)
5. Enter encryption passphrase
6. Click **Create** to initialize the repository

<p class="callout warning">**Critical:** Save your repository passphrase securely! Without it, your backups cannot be accessed or restored.</p>

### Repository Actions

<table id="bkmrk-action-description-w"><thead><tr><th>Action</th><th>Description</th><th>When to Use</th></tr></thead><tbody><tr><td>Check</td><td>Verify repository integrity</td><td>Periodically or after errors</td></tr><tr><td>Compact (Borg 2.x)</td><td>Reclaim space from deleted archives</td><td>After pruning many archives</td></tr><tr><td>Update Passphrase</td><td>Change stored passphrase</td><td>If passphrase was entered incorrectly</td></tr><tr><td>Delete</td><td>Remove repository from UI</td><td>Optionally delete data on disk</td></tr></tbody></table>

---

## Archives (View/Restore)

Archives are point-in-time snapshots stored in repositories.

### Archive Browser

The Archive Browser provides file-system navigation of backup contents:

- **Directory Navigation:** Click folders to explore
- **Breadcrumb Trail:** Navigate back to parent directories
- **Search/Filter:** Filter files by name
- **File Preview:** View text file contents directly
- **Selection:** Check items for restore/download

### Restore Options

<table id="bkmrk-option-description-b"><thead><tr><th>Option</th><th>Description</th><th>Best For</th></tr></thead><tbody><tr><td>Restore to New Location</td><td>Extract to a specified folder</td><td>Safest - review before replacing</td></tr><tr><td>Download</td><td>Download to your browser (ZIP for folders)</td><td>Small files, quick access</td></tr><tr><td>Restore to Original Location</td><td>Put files back where they were</td><td>Full disaster recovery</td></tr></tbody></table>

### Restore History

Each archive tracks its last restore operation:

- Destination path or "Downloaded"
- Timestamp of restore
- Persisted across sessions

### Archive Actions

<table id="bkmrk-action-description-b"><thead><tr><th>Action</th><th>Description</th></tr></thead><tbody><tr><td>Browse</td><td>Open archive in file browser</td></tr><tr><td>Info</td><td>View archive metadata (size, file count, etc.)</td></tr><tr><td>Delete</td><td>Permanently remove archive from repository</td></tr></tbody></table>

---

## Schedules

Schedules automate backup execution at specified intervals.

### Schedule Configuration

<table id="bkmrk-field-description-ex-1"><thead><tr><th>Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Schedule Type</td><td>Preset or custom cron</td><td>Daily, Weekly, Custom</td></tr><tr><td>Time</td><td>When to run</td><td>02:00</td></tr><tr><td>Day (weekly)</td><td>Day of week for weekly schedules</td><td>Sunday</td></tr><tr><td>Cron Expression</td><td>Custom cron for advanced scheduling</td><td>`0 */6 * * *`</td></tr><tr><td>Timezone</td><td>Timezone for schedule evaluation</td><td>Europe/Berlin</td></tr></tbody></table>

### Cron Expression Reference

```
# Format: minute hour day-of-month month day-of-week
#         0-59   0-23 1-31         1-12  0-6 (0=Sunday)

0 2 * * *      # Daily at 2:00 AM
0 */6 * * *    # Every 6 hours
0 3 * * 0      # Weekly on Sunday at 3:00 AM
0 4 1 * *      # Monthly on the 1st at 4:00 AM
*/30 * * * *   # Every 30 minutes
```

### Common Schedule Patterns

<table id="bkmrk-pattern-cron-use-cas"><thead><tr><th>Pattern</th><th>Cron</th><th>Use Case</th></tr></thead><tbody><tr><td>Daily at 2 AM</td><td>`0 2 * * *`</td><td>Standard daily backup</td></tr><tr><td>Every 6 hours</td><td>`0 */6 * * *`</td><td>Frequently changing data</td></tr><tr><td>Weekdays at 6 PM</td><td>`0 18 * * 1-5`</td><td>End of business day</td></tr><tr><td>Sunday at 3 AM</td><td>`0 3 * * 0`</td><td>Weekly full backup</td></tr></tbody></table>

---

## SSH Key Management

SSH keys enable secure, passwordless authentication to remote servers.

### Key Operations

#### Import Existing Key

1. Click **Import SSH Key**
2. Provide a name for the key
3. Paste the private key content, OR
4. Click **Select from Server** to browse server filesystem, OR
5. Click **Upload Key File** to upload from your computer
6. If key is encrypted, enter the passphrase
7. Click **Create**

#### Generate New Key

1. Click **Generate SSH Key**
2. Provide a name
3. Select key type (Ed25519 recommended, RSA for compatibility)
4. Click **Generate**
5. Copy the public key to remote server's `~/.ssh/authorized_keys`

#### Test Connection

1. Click the test icon on a key
2. Enter remote host, username, and port
3. Click **Test Connection**
4. Verify connection succeeds and Borg is detected

### Supported Key Types

<table id="bkmrk-type-format-header-r"><thead><tr><th>Type</th><th>Format Header</th><th>Recommendation</th></tr></thead><tbody><tr><td>OpenSSH</td><td>`-----BEGIN OPENSSH PRIVATE KEY-----`</td><td>✅ Recommended (modern)</td></tr><tr><td>RSA PEM</td><td>`-----BEGIN RSA PRIVATE KEY-----`</td><td>✅ Good (legacy compatible)</td></tr><tr><td>EC PEM</td><td>`-----BEGIN EC PRIVATE KEY-----`</td><td>✅ Good</td></tr><tr><td>PKCS#8</td><td>`-----BEGIN PRIVATE KEY-----`</td><td>✅ Good</td></tr></tbody></table>

### Key Security

- Private keys are stored encrypted in the database
- Passphrase-protected keys are supported
- Temporary key files are created with mode 0600
- Temporary files are cleaned up immediately after use

---

## YAML Editor

The YAML Editor provides direct access to Borgmatic configuration files.

### Features

- **Syntax Highlighting:** YAML-aware editor with color coding
- **Validation:** Real-time syntax and schema validation
- **Backup/Restore:** Automatic backups of config changes
- **File Browser:** View all configuration files in `/etc/borgmatic.d/`

### Use Cases

- Advanced configuration not exposed in UI
- Bulk editing of multiple options
- Importing existing Borgmatic configs
- Troubleshooting configuration issues

<p class="callout warning">**Caution:** Manual YAML edits may conflict with UI-managed settings. Use the UI for standard configurations.</p>

---

## Logs

The Logs page provides access to backup execution logs and system events.

### Log Types

<table id="bkmrk-log-type-content-loc"><thead><tr><th>Log Type</th><th>Content</th><th>Location</th></tr></thead><tbody><tr><td>Backup Logs</td><td>Individual backup execution output</td><td>Per-backup log files</td></tr><tr><td>Borgmatic Logs</td><td>Borgmatic wrapper output</td><td>System logs</td></tr><tr><td>Application Logs</td><td>Borgmatic UI application events</td><td>Container stdout/stderr</td></tr></tbody></table>

### Log Features

- **Real-time Streaming:** Watch backup progress live
- **Search:** Find specific entries
- **Filter by Level:** Info, Warning, Error
- **Download:** Export logs for analysis

---

## Settings

### General Settings

<table id="bkmrk-setting-description--1"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td>Instance Name</td><td>Display name for this server</td></tr><tr><td>Theme</td><td>Light or dark mode</td></tr><tr><td>Timezone</td><td>Default timezone for schedules</td></tr></tbody></table>

### Operating Mode

See the [Operating Modes](#operating-modes) section above.

### Notifications

Configure alerts for backup events:

<table id="bkmrk-provider-configurati"><thead><tr><th>Provider</th><th>Configuration</th></tr></thead><tbody><tr><td>Email (SMTP)</td><td>SMTP server, credentials, recipients</td></tr><tr><td>Webhook</td><td>URL to POST events to</td></tr><tr><td>Slack</td><td>Webhook URL</td></tr><tr><td>Discord</td><td>Webhook URL</td></tr><tr><td>Gotify</td><td>Server URL and token</td></tr><tr><td>Ntfy</td><td>Topic and server URL</td></tr></tbody></table>

### Security Settings

<table id="bkmrk-setting-description--2"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td>Change Password</td><td>Update admin password</td></tr><tr><td>Session Timeout</td><td>Auto-logout after inactivity</td></tr><tr><td>API Tokens</td><td>Generate tokens for API access</td></tr></tbody></table>

### Factory Reset

Completely reset the instance:

- Removes all configurations
- Clears all credentials
- Optionally regenerates secret key
- Requires typing "RESET" to confirm

<p class="callout warning">**Warning:** Factory reset is irreversible. Backup your data first!</p>

---

## Environment Variables

Configure the application via environment variables:

<table id="bkmrk-variable-default-des"><thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>`NODE_ENV`</td><td>production</td><td>Environment mode (production/development)</td></tr><tr><td>`PORT`</td><td>3000</td><td>HTTP server port</td></tr><tr><td>`JWT_SECRET`</td><td>(auto-generated)</td><td>Secret for JWT token signing</td></tr><tr><td>`ADMIN_USERNAME`</td><td>admin</td><td>Default admin username</td></tr><tr><td>`ADMIN_PASSWORD`</td><td>admin</td><td>Default admin password</td></tr><tr><td>`DATA_DIR`</td><td>/app/data</td><td>Persistent data directory</td></tr><tr><td>`TZ`</td><td>UTC</td><td>Container timezone</td></tr><tr><td>`DIRECTOR_PORT`</td><td>9000</td><td>WebSocket port (Director mode)</td></tr><tr><td>`RESTORE_ALLOWED_ROOTS`</td><td>/host,/tmp,/data</td><td>Allowed restore destination paths</td></tr><tr><td>`DEBUG_REPOSITORIES`</td><td>false</td><td>Enable verbose repository logging</td></tr></tbody></table>

---

## Docker Deployment

### Basic Docker Compose

```
version: '3.8'

services:
  borgmatic-ui:
    image: borgmatic-ui:latest
    container_name: borgmatic-ui
    restart: unless-stopped
    ports:
      - "8080:3000"      # Web UI
      - "9000:9000"      # Director WebSocket (if using Director mode)
    volumes:
      - ./data:/app/data                    # Persistent data
      - ./borgmatic.d:/etc/borgmatic.d      # Borgmatic configs
      - /:/host:ro                          # Host filesystem access
      - ./borg-cache:/root/.cache/borg      # Borg cache
    environment:
      - ADMIN_PASSWORD=change-me-please
      - TZ=Europe/Berlin
```

### Volume Mounts Explained

<table id="bkmrk-mount-purpose-requir"><thead><tr><th>Mount</th><th>Purpose</th><th>Required</th></tr></thead><tbody><tr><td>`/app/data`</td><td>Application data, credentials, SSH keys</td><td>Yes</td></tr><tr><td>`/etc/borgmatic.d`</td><td>Generated Borgmatic YAML configs</td><td>Yes</td></tr><tr><td>`/:/host`</td><td>Access to host filesystem for backups</td><td>Yes (for local backups)</td></tr><tr><td>`/root/.cache/borg`</td><td>Borg cache (improves backup speed)</td><td>Recommended</td></tr></tbody></table>

---

## Troubleshooting

### Common Issues

<table id="bkmrk-problem-cause-soluti"><thead><tr><th>Problem</th><th>Cause</th><th>Solution</th></tr></thead><tbody><tr><td>"Cannot connect to server"</td><td>Backend not running or port blocked</td><td>Check container logs, verify port mapping</td></tr><tr><td>"Authentication failed" (SSH)</td><td>Wrong key or not in authorized\_keys</td><td>Verify public key on remote server</td></tr><tr><td>"Passphrase wrong"</td><td>Incorrect repository passphrase</td><td>Update passphrase in repository settings</td></tr><tr><td>"Repository locked"</td><td>Previous backup didn't finish</td><td>Wait or use "Break Lock" action</td></tr><tr><td>Backup stuck at 0%</td><td>Network issue or SSH timeout</td><td>Check connectivity, test SSH connection</td></tr><tr><td>Director: Client not connecting</td><td>Firewall, wrong URL, or DNS issue</td><td>Verify port 9000 accessible, check client logs</td></tr></tbody></table>

### Debug Mode

```
# Enable verbose logging
docker run -e DEBUG_REPOSITORIES=true ...

# View container logs
docker logs -f borgmatic-ui

# Check real-time backup output
# (visible in the UI during backup execution)
```

---

## API Access

Borgmatic Director UI provides a REST API for automation and integration.

### Authentication

```
# Login to get JWT token
POST /api/auth/login
Content-Type: application/json
{
  "username": "admin",
  "password": "your-password"
}

# Use token in subsequent requests
Authorization: Bearer <token>
```

### Key Endpoints

```
# Backups
GET  /api/backups              # List all backup jobs
POST /api/backups/:id/run      # Trigger backup
POST /api/backups/:id/stop     # Stop running backup

# Repositories  
GET  /api/repositories         # List repositories
POST /api/repositories/:id/check  # Check integrity

# Archives
GET  /api/archives/:repo       # List archives
GET  /api/archives/:repo/:archive/browse  # Browse contents

# Health
GET  /api/dashboard/health     # System health
GET  /api/dashboard/tools-health  # Tool versions
```

---

<p class="callout success">**Need more help?** Check the container logs (`docker logs borgmatic-ui`) for detailed error messages. Most issues are related to SSH connectivity, passphrases, or file permissions.</p>