### Install Docs Dependencies and Run Dev Server

Source: https://docs.borgui.com/development

Navigate to the docs directory, install dependencies, and start the local development server for the documentation.

```bash
cd docs
npm ci
npm run dev
```

--------------------------------

### Install Frontend Dependencies and Run Dev Server

Source: https://docs.borgui.com/development

Navigate to the frontend directory, install dependencies using npm, and start the local development server.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Clone and Start Dev Environment

Source: https://docs.borgui.com/development

Clone the repository and execute the dev script to start the backend in Docker and the frontend locally. Ensure Docker, Node.js, and Python are installed.

```bash
git clone https://github.com/karanhudia/borg-ui.git
cd borg-ui
./scripts/dev.sh
```

--------------------------------

### Full Script Example with Parameter Handling

Source: https://docs.borgui.com/script-parameters

This example demonstrates a complete bash script that utilizes parameters for database backup, including setting a default directory and handling required and optional parameters.

```bash
#!/usr/bin/env bash
set -euo pipefail

dump_dir="${DUMP_DIR:-/local/db-dumps}"
mkdir -p "$dump_dir"

mysqldump \
  -h "${DB_HOST}" \
  -P "${DB_PORT:-3306}" \
  -u "${DB_USER}" \
  -p"${DB_PASSWORD}" \
  "${DB_NAME}" > "$dump_dir/${DB_NAME}.sql"
```

--------------------------------

### Repository Path Examples for Borg UI

Source: https://docs.borgui.com/ssh-keys

Examples of how to format repository paths for Borg UI, including standard SSH paths and Hetzner Storage Box specific syntax.

```text
backup@example.com:/backups/laptop
```

```text
ssh://backup@example.com:22/backups/laptop
```

```text
ssh://u123456@u123456.your-storagebox.de:23/./backup-repo
```

--------------------------------

### Add Remote Machine Configuration Example

Source: https://docs.borgui.com/ssh-keys

Example configuration for adding a remote machine, specifying host, port, username, and default path.

```text
Host: backup.example.com
Port: 22
Username: backup
Default path: /backups
```

--------------------------------

### Post-Backup Script: Start Container

Source: https://docs.borgui.com/docker-hooks

This post-backup script starts a specified container if it exists in the list of all containers (running or stopped). It defaults to starting a container named 'postgres' but can be configured via the CONTAINER_NAME environment variable.

```bash
#!/usr/bin/env bash
set -euo pipefail

container="${CONTAINER_NAME:-postgres}"

if docker ps -a --format '{{.Names}}' | grep -qx "$container"; then
  docker start "$container"
fi
```

--------------------------------

### Install Pre-Commit Hooks

Source: https://docs.borgui.com/development

Install pre-commit and pre-push hooks to automate checks before committing and pushing code. Ensure frontend dependencies are installed first.

```bash
pre-commit install --hook-type pre-commit --hook-type pre-push
```

--------------------------------

### Run Documentation Checks

Source: https://docs.borgui.com/contributing

Navigate to the docs directory, install dependencies, and build the documentation. This ensures documentation is up-to-date and correctly formatted.

```bash
cd docs
npm ci
npm run build
```

--------------------------------

### Example .env File for Borg UI Configuration

Source: https://docs.borgui.com/installation

Configure essential environment variables including port, user IDs, storage path, and timezone.

```bash
PORT=8081
PUID=1000
PGID=1000
LOCAL_STORAGE_PATH=/mnt/usb-drive
TZ=America/Chicago
```

--------------------------------

### External Redis URL Examples

Source: https://docs.borgui.com/installation

Examples of different formats for the REDIS_URL environment variable, including authentication and Unix sockets.

```text
redis://redis.example.com:6379/0
redis://:password@redis.example.com:6379/0
rediss://:password@redis.example.com:6379/0
unix:///run/redis/redis.sock?db=0
unix:///run/redis/redis.sock?db=0&password=password
```

--------------------------------

### Frontend Development Checks

Source: https://docs.borgui.com/testing

Navigate to the frontend directory and install dependencies. Then, run type checking, linting, formatting checks, tests, and finally the build process.

```bash
cd frontend
npm install
npm run typecheck
npm run lint
npm run format:check
npm run test
npm run build
```

--------------------------------

### Borg UI Path Example

Source: https://docs.borgui.com/usage-guide

Illustrates how a host path is represented within Borg UI after a Docker volume mapping.

```text
/local/borg-backups/laptop
```

--------------------------------

### Manual Public Key Installation on Remote Server

Source: https://docs.borgui.com/ssh-keys

Steps to manually install the Borg UI public SSH key on a remote server. Ensure correct permissions for the .ssh directory and authorized_keys file.

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA... borg-ui" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

--------------------------------

### Add Backup Sources

Source: https://docs.borgui.com/usage-guide

Examples of paths within the container that can be added as backup sources in Borg UI.

```text
/local/Documents
/local/photos
/local/projects
```

--------------------------------

### Start Borg UI with Docker Compose

Source: https://docs.borgui.com/installation

Command to start the Borg UI service in detached mode using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Clone BorgUI Repository and Setup

Source: https://docs.borgui.com/contributing

Clone the BorgUI repository, set up the upstream remote, and run the development script. Ensure you replace YOUR_USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR_USERNAME/borg-ui.git
cd borg-ui
git remote add upstream https://github.com/karanhudia/borg-ui.git
./scripts/dev.sh
```

--------------------------------

### Example Nested Claim Path

Source: https://docs.borgui.com/authentication

Demonstrates how to specify a nested claim for roles or other user attributes using dot notation.

```text
resource_access.borg-ui.role
```

--------------------------------

### Traefik Configuration for Borg UI

Source: https://docs.borgui.com/reverse-proxy

Example Traefik configuration to route traffic to Borg UI. This setup enables TLS termination using Let's Encrypt and specifies the correct port for the Borg UI service.

```yaml
services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    labels:
      - traefik.enable=true
      - traefik.http.routers.borg-ui.rule=Host(`backups.example.com`)
      - traefik.http.routers.borg-ui.entrypoints=websecure
      - traefik.http.routers.borg-ui.tls.certresolver=letsencrypt
      - traefik.http.services.borg-ui.loadbalancer.server.port=8081
```

--------------------------------

### Borg UI API Documentation URL

Source: https://docs.borgui.com/SPECIFICATION

Access interactive API documentation after starting the Borg UI application.

```text
http://localhost:8081/api/docs
```

--------------------------------

### Run Frontend Checks

Source: https://docs.borgui.com/contributing

Navigate to the frontend directory, install dependencies, and run type checking, linting, formatting checks, and tests. This ensures the frontend code adheres to project standards.

```bash
cd frontend
npm install
npm run typecheck
npm run lint
npm run format:check
npm test
```

--------------------------------

### Check Borg Binary Versions

Source: https://docs.borgui.com/development

Verify the installed versions of the Borg command-line tools within the container.

```bash
borg --version
borg2 --version
```

--------------------------------

### Example Host Path Mapping for Borg UI

Source: https://docs.borgui.com/installation

Mount a host path to the container's /local directory for accessing backup sources. Do not include the host prefix in the Borg UI.

```yaml
volumes:
  - /mnt/usb-drive:/local:rw
```

--------------------------------

### JSON Webhook Wrapper Example

Source: https://docs.borgui.com/notifications

An example of the JSON wrapper sent by Borg UI for 'json://' and 'jsons://' targets. The event data is nested within the 'message' field as a JSON string.

```json
{
  "version": "1.0",
  "title": "[SUCCESS] Backup Successful - Daily Backup",
  "message": "{\"event_type\":\"backup_success\",\"repository_name\":\"laptop\",\"archive_name\":\"laptop-2026-05-05\"}",
  "attachments": [],
  "type": "success"
}
```

--------------------------------

### Mount Multiple Host Locations

Source: https://docs.borgui.com/usage-guide

Configuration example for mounting multiple host directories into the container, making them accessible via specified container paths.

```yaml
volumes:
  - /home/user/Documents:/documents:ro
  - /mnt/photos:/photos:ro
  - /mnt/backups:/backups:rw
environment:
  - LOCAL_MOUNT_POINTS=/documents,/photos,/backups
```

--------------------------------

### Docker Compose: Borg UI with Redis

Source: https://docs.borgui.com/installation

This is the recommended setup for normal deployments, utilizing Redis for faster archive browsing and persistent cache across restarts.

```yaml
services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    ports:
      - "${PORT:-8081}:${PORT:-8081}"
    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /etc/localtime:/etc/localtime:ro
      - ${LOCAL_STORAGE_PATH:-/home/youruser}:/local:rw
    environment:
      - PORT=${PORT:-8081}
      - PUID=${PUID:-1001}
      - PGID=${PGID:-1001}
      - TZ=${TZ:-UTC}
      - LOCAL_MOUNT_POINTS=${LOCAL_MOUNT_POINTS:-/local}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_DB=0
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    container_name: borg-redis
    restart: unless-stopped
    command: >
      redis-server
      --maxmemory 2gb
      --maxmemory-policy allkeys-lru
      --save ""
      --appendonly no
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  borg_data:
  borg_cache:

```

--------------------------------

### Restore Destination Path

Source: https://docs.borgui.com/usage-guide

Example of a destination path within the container for restoring files using Borg UI.

```text
/local/restore-test
```

--------------------------------

### External Redis Configuration with URL

Source: https://docs.borgui.com/cache

Demonstrates how to configure an external Redis instance using the REDIS_URL environment variable. This example shows a basic connection to a Redis server on a specific host and port.

```yaml
environment:
  - REDIS_URL=redis://redis.example.com:6379/0
```

--------------------------------

### Map Host Paths to BorgUI Local Mounts

Source: https://docs.borgui.com/configuration

Example of mounting host directories into the container and configuring the LOCAL_MOUNT_POINTS environment variable to make them accessible within Borg UI.

```yaml
volumes:
  - /mnt/photos:/photos:ro
  - /mnt/backups:/backups:rw
environment:
  - LOCAL_MOUNT_POINTS=/photos,/backups
```

--------------------------------

### Import SSH Key from Mounted Host Path

Source: https://docs.borgui.com/ssh-keys

Example of an SSH key path to use within Borg UI when the host's SSH directory has been mounted into the container.

```text
/host-ssh/id_ed25519
```

--------------------------------

### Map Host Path to Container Path

Source: https://docs.borgui.com/usage-guide

Example of mapping a host directory to a container directory using Docker. Borg UI operates on container paths.

```yaml
- /mnt/usb-drive:/local:rw
```

--------------------------------

### Run Borg UI with Docker

Source: https://docs.borgui.com/

This command starts the Borg UI Docker container. It maps the UI port, configures Redis, and mounts volumes for data, cache, and local access. Access the UI at http://localhost:8081 with default credentials admin/admin123.

```bash
docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -e REDIS_HOST=disabled \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/youruser:/local:rw \
  ainullcode/borg-ui:latest
```

--------------------------------

### Run Smoke Tests

Source: https://docs.borgui.com/testing

Ensure a Borg UI instance is running. Use `docker compose up -d --build` to start the services, then execute the core smoke tests using the provided Python script.

```bash
docker compose up -d --build
python3 tests/smoke/run_core_smoke.py --url http://localhost:8081
```

--------------------------------

### Using API Token for Authorization

Source: https://docs.borgui.com/script-parameters

Parameters with suffixes like _PASSWORD, _TOKEN, or _SECRET are treated as password fields. This example shows how to use an API token for authorization.

```bash
curl -H "Authorization: Bearer ${API_TOKEN}" "${ENDPOINT_URL}"
```

--------------------------------

### Apprise Notification Service URLs

Source: https://docs.borgui.com/notifications

Examples of Apprise URLs for various notification services. Ensure the correct URL format for each service.

```text
mailto://user:app_password@gmail.com?smtp=smtp.gmail.com&mode=starttls
```

```text
slack://TokenA/TokenB/TokenC/
```

```text
discord://webhook_id/webhook_token
```

```text
tgram://bot_token/chat_id
```

```text
ntfy://topic_name
```

```text
jsons://example.com/webhooks/borg-ui
```

--------------------------------

### Access Borg UI Web Interface

Source: https://docs.borgui.com/installation

The default URL to access the Borg UI web interface after starting the service.

```text
http://localhost:8081
```

--------------------------------

### Restrict Remote Access with Command in authorized_keys

Source: https://docs.borgui.com/ssh-keys

Example of restricting a public key in `authorized_keys` to only allow the 'borg serve' command with a specific path. This enhances security for backup-only users.

```text
command="borg serve --restrict-to-path /backups",restrict ssh-ed25519 AAAA... borg-ui
```

--------------------------------

### Get Host User ID and Group ID

Source: https://docs.borgui.com/installation

Find the PUID and PGID for the host user that owns restored files and backup repositories. Use these values in your .env file.

```bash
id -u
id -g
```

--------------------------------

### Fallback for Reserved Variables

Source: https://docs.borgui.com/script-parameters

When a script must work in different environments, use parameter expansion to fall back to alternative variables. This example prioritizes remote host variables and falls back to source host variables.

```bash
remote_host="${BORG_UI_REMOTE_HOST:-${BORG_UI_SOURCE_HOST:-}}"
remote_port="${BORG_UI_REMOTE_PORT:-${BORG_UI_SOURCE_PORT:-22}}"
remote_user="${BORG_UI_REMOTE_USERNAME:-${BORG_UI_SOURCE_USERNAME:-}}"
```

--------------------------------

### Build Frontend for Production

Source: https://docs.borgui.com/development

Generate a production-ready build of the frontend application.

```bash
npm run build
```

--------------------------------

### Unraid Recommended Defaults

Source: https://docs.borgui.com/installation

Set PUID, PGID, and TZ for the user and timezone. PUID and PGID should match the host user that owns restored files.

```text
PUID=99
PGID=100
TZ=<your timezone>
```

--------------------------------

### Docker Compose: Borg UI without Redis

Source: https://docs.borgui.com/installation

Use this configuration for simple installations or when an in-memory cache is sufficient. The archive browsing cache will be lost on restart.

```yaml
services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    ports:
      - "${PORT:-8081}:${PORT:-8081}"
    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /etc/localtime:/etc/localtime:ro
      - ${LOCAL_STORAGE_PATH:-/home/youruser}:/local:rw
    environment:
      - PORT=${PORT:-8081}
      - PUID=${PUID:-1001}
      - PGID=${PGID:-1001}
      - TZ=${TZ:-UTC}
      - LOCAL_MOUNT_POINTS=${LOCAL_MOUNT_POINTS:-/local}
      - REDIS_HOST=disabled

volumes:
  borg_data:
  borg_cache:

```

--------------------------------

### Parsing JSON Webhook Payload in Python

Source: https://docs.borgui.com/notifications

Example Python code to parse the 'message' field from a JSON webhook payload. This allows extraction of specific event details.

```python
import json

def handle_webhook(payload):
    event = json.loads(payload["message"])
    print(event["event_type"])
    print(event.get("repository_name"))
```

--------------------------------

### Format Backend Code with Ruff

Source: https://docs.borgui.com/development

Use Ruff to format the backend Python code according to project standards. Run from the repository root.

```bash
ruff format --check app tests
```

--------------------------------

### Run Frontend Type Checking and Linting

Source: https://docs.borgui.com/development

Execute commands to check frontend code for type errors and style issues.

```bash
npm run typecheck
npm run lint
npm run format:check
```

--------------------------------

### Safer Pattern: Database Dump

Source: https://docs.borgui.com/docker-hooks

This script demonstrates a safer approach for backing up databases by executing a dump command within the container and saving the output to a file. This avoids stopping the live container.

```bash
#!/usr/bin/env bash
set -euo pipefail

mkdir -p /local/db-dumps
docker exec postgres pg_dumpall -U postgres > /local/db-dumps/postgres.sql
```

--------------------------------

### Run Production-Style Local Build

Source: https://docs.borgui.com/development

Use Docker Compose to build and run the application in a production-like environment. The default app URL is http://localhost:8081.

```bash
docker compose up -d --build
```

--------------------------------

### Check Backend Code with Ruff

Source: https://docs.borgui.com/development

Use Ruff to check the backend Python code for style and potential errors. Run from the repository root.

```bash
ruff check app tests
```

--------------------------------

### External Redis Configuration with Unix Socket and Password

Source: https://docs.borgui.com/cache

Demonstrates connecting to an external Redis instance using a Unix domain socket and password authentication via the REDIS_URL environment variable. The socket path must be mounted into the Borg UI container.

```yaml
environment:
  - REDIS_URL=unix:///run/redis/redis.sock?db=0&password=password
```

--------------------------------

### Correct Variable Quoting in Shell Scripts

Source: https://docs.borgui.com/script-parameters

Always quote variables when using them in shell commands to prevent unexpected behavior and security vulnerabilities. This example shows correct quoting for a database name.

```bash
"${DB_NAME}"
```

--------------------------------

### Prometheus Scrape Configuration with Custom Header Token

Source: https://docs.borgui.com/METRICS

Alternative Prometheus configuration to scrape metrics using a custom HTTP header for token authentication. This method is useful if your Prometheus setup requires specific header handling.

```yaml
scrape_configs:
  - job_name: borg-ui
    metrics_path: /metrics
    static_configs:
      - targets:
          - borg-web-ui:8081
    http_headers:
      X-Borg-Metrics-Token:
        values:
          - <your-generated-token>
```

--------------------------------

### Set Initial Admin Password

Source: https://docs.borgui.com/authentication

Set a stronger initial password for the first admin user in new deployments using an environment variable.

```yaml
environment:
  - INITIAL_ADMIN_PASSWORD=change-this-password
```

--------------------------------

### Disable Startup License Sync

Source: https://docs.borgui.com/licensing

Set this environment variable to 'false' to disable the startup license sync. This prevents automatic refreshing of plan upgrades and full-access activation if activation sync is disabled.

```bash
ENABLE_STARTUP_LICENSE_SYNC=false
```

--------------------------------

### Docker Compose: Borg UI with External Redis

Source: https://docs.borgui.com/installation

Configure Borg UI to connect to an existing Redis instance. Ensure the Redis URL is correctly formatted and accessible.

```yaml
services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    ports:
      - "${PORT:-8081}:${PORT:-8081}"
    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /etc/localtime:/etc/localtime:ro
      - ${LOCAL_STORAGE_PATH:-/home/youruser}:/local:rw
    environment:
      - PORT=${PORT:-8081}
      - PUID=${PUID:-1001}
      - PGID=${PGID:-1001}
      - TZ=${TZ:-UTC}
      - LOCAL_MOUNT_POINTS=${LOCAL_MOUNT_POINTS:-/local}
      - REDIS_URL=redis://redis.example.com:6379/0
      - REDIS_HOST=disabled

volumes:
  borg_data:
  borg_cache:

```

--------------------------------

### Inspect Mounted Archives from Container

Source: https://docs.borgui.com/mounting

Use `docker exec` to list the contents of the mounts directory or a specific mounted archive from within the Borg UI container. Replace `borg-web-ui` with your container's name if it differs.

```bash
docker exec -it borg-web-ui ls /data/mounts
docker exec -it borg-web-ui ls /data/mounts/my-backup
```

--------------------------------

### Run Backend Tests with Pytest

Source: https://docs.borgui.com/development

Execute the backend test suite using Pytest. Run from the repository root.

```bash
pytest
```

--------------------------------

### Handling Optional Script Parameters with Defaults

Source: https://docs.borgui.com/script-parameters

Treat parameters as optional by providing a default value using the :- syntax. If a default is present, Borg UI considers the parameter optional.

```bash
BACKUP_DIR="${BACKUP_DIR:-/tmp/borg-ui-dumps}"
```

--------------------------------

### Run Backend Checks

Source: https://docs.borgui.com/contributing

Execute linting and formatting checks for the backend application and tests using Ruff, and run Pytest for backend tests. This ensures backend code quality and correctness.

```bash
ruff check app tests
ruff format --check app tests
pytest
```

--------------------------------

### Unraid Common Path Mapping

Source: https://docs.borgui.com/installation

Map host paths to container paths for data, cache, and local storage. Use container paths within Borg UI.

```text
/mnt/user/appdata/borg-ui -> /data
/mnt/user/appdata/borg-ui/cache -> /home/borg/.cache/borg
/mnt/user/backups -> /local
```

--------------------------------

### External Redis Configuration with TLS

Source: https://docs.borgui.com/cache

Shows how to connect to an external Redis instance using TLS for secure communication, specified via the REDIS_URL environment variable.

```yaml
environment:
  - REDIS_URL=rediss://:password@redis.example.com:6379/0
```

--------------------------------

### Borg UI Docker Image

Source: https://docs.borgui.com/SPECIFICATION

The Docker image published for users to run the Borg UI application.

```bash
ainullcode/borg-ui:latest
```

--------------------------------

### Configure OIDC Public Base URL

Source: https://docs.borgui.com/authentication

If Borg UI is behind a proxy and constructs the wrong callback URL, set the PUBLIC_BASE_URL environment variable to the correct public origin.

```yaml
environment:
  - PUBLIC_BASE_URL=https://backups.example.com
```

--------------------------------

### Run Core Smoke Tests

Source: https://docs.borgui.com/development

Execute smoke tests against a running application to verify critical production flows. Specify the application URL.

```bash
python3 tests/smoke/run_core_smoke.py --url http://localhost:8081
```

--------------------------------

### Restore Path on Host

Source: https://docs.borgui.com/usage-guide

Shows where restored files will appear on the host system if the container path is mapped to a specific host directory.

```text
/mnt/usb-drive/restore-test
```

--------------------------------

### Update Borg UI with Docker Compose

Source: https://docs.borgui.com/security

Pull the latest Docker image and restart the containers to update Borg UI. Ensure backups of `/data` and Borg repositories are made before major upgrades.

```bash
docker compose pull
docker compose up -d
```

--------------------------------

### Configure Borg UI for Archive Mounting

Source: https://docs.borgui.com/mounting

Add these configurations to your Borg UI service definition to enable FUSE support for archive mounting. This includes granting SYS_ADMIN capability, mapping the /dev/fuse device, and disabling AppArmor confinement for FUSE.

```yaml
cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse
security_opt:
  - apparmor:unconfined
environment:
  - BORG_FUSE_IMPL=pyfuse3
```

--------------------------------

### Nginx Configuration for Sub-Path Deployment

Source: https://docs.borgui.com/reverse-proxy

Configure Nginx to serve Borg UI from a sub-path, stripping the prefix before forwarding. This is crucial for correct routing and OIDC callback handling.

```nginx
location /borg-ui/ {
    proxy_pass http://127.0.0.1:8081/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_buffering off;
}
```

--------------------------------

### Default Borg UI Credentials

Source: https://docs.borgui.com/usage-guide

Use these default credentials for the initial login to Borg UI. It is recommended to change the password immediately after logging in.

```text
admin / admin123
```

--------------------------------

### Create a New Feature Branch

Source: https://docs.borgui.com/contributing

Create a new branch for your changes using a clear prefix like 'fix/', 'feat/', 'docs/', 'test/', or 'refactor/'.

```bash
git checkout -b fix/short-description
```

--------------------------------

### Caddy Configuration for Root Domain

Source: https://docs.borgui.com/reverse-proxy

A simple Caddy configuration to proxy requests to Borg UI running on localhost:8081. Caddy automatically handles TLS for the specified domain.

```caddy
backups.example.com {
    reverse_proxy 127.0.0.1:8081
}
```

--------------------------------

### Docker Compose: External Redis Instance

Source: https://docs.borgui.com/installation

A minimal Docker Compose file to run a standalone Redis instance, useful when setting up an external Redis for Borg UI.

```yaml
services:
  redis:
    image: redis:7-alpine
    container_name: borg-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: >
      redis-server
      --maxmemory 2gb
      --maxmemory-policy allkeys-lru
      --save ""
      --appendonly no
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

```

--------------------------------

### External Redis Configuration with Unix Socket

Source: https://docs.borgui.com/cache

Configures connection to an external Redis instance using a Unix domain socket via the REDIS_URL environment variable. Ensure the socket path is correctly mounted into the Borg UI container.

```yaml
environment:
  - REDIS_URL=unix:///run/redis/redis.sock?db=0
```

--------------------------------

### Define Docker Volumes for BorgUI

Source: https://docs.borgui.com/configuration

Configure Docker volumes to persist Borg UI application state, cache, and local host data. Ensure '/local' container path matches LOCAL_MOUNT_POINTS if used.

```yaml
volumes:
  - borg_data:/data
  - borg_cache:/home/borg/.cache/borg
  - /host/path:/local:rw
```

--------------------------------

### Enable Docker Socket Access

Source: https://docs.borgui.com/docker-hooks

Mount the Docker socket into the Borg UI container to grant it control over the host's Docker daemon. This provides host-level access and should be treated with caution.

```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:rw
```

--------------------------------

### Nginx Configuration for Root Domain

Source: https://docs.borgui.com/reverse-proxy

Use this Nginx configuration to serve Borg UI from the root domain with TLS and HTTP/2. Ensure proxy headers are correctly set for host, IP, and protocol forwarding.

```nginx
server {
    listen 443 ssl http2;
    server_name backups.example.com;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
    }
}
```

--------------------------------

### Restore Borg Repository Using Borg CLI

Source: https://docs.borgui.com/disaster-recovery

Use this command-line method to restore a Borg repository if the Borg UI is unavailable. Ensure you have the repository path, archive name, and necessary credentials (passphrase or SSH key).

```bash
export BORG_PASSPHRASE='your-repository-passphrase'
borg list /path/to/repository
mkdir -p /tmp/borg-restore
cd /tmp/borg-restore
borg extract /path/to/repository::ARCHIVE_NAME path/in/archive
```

--------------------------------

### Enable No-Auth Mode for Development

Source: https://docs.borgui.com/authentication

Use this mode for local development only. Do not use it on a networked deployment as it bypasses all authentication.

```yaml
environment:
  - ALLOW_INSECURE_NO_AUTH=true
```

--------------------------------

### Docker Run Command to Mount SSH Key

Source: https://docs.borgui.com/ssh-keys

Command to run the Borg UI Docker container, mounting the host's SSH directory read-only. This is necessary for importing existing SSH keys from the host filesystem.

```bash
docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -e REDIS_HOST=disabled \
  -v borg_data:/data \
  -v ~/.ssh:/host-ssh:ro \
  ainullcode/borg-ui:latest
```

--------------------------------

### External Redis Configuration with Password

Source: https://docs.borgui.com/cache

Configures an external Redis instance with authentication using the REDIS_URL environment variable, including a password.

```yaml
environment:
  - REDIS_URL=redis://:password@redis.example.com:6379/0
```