Environment Variables

Complete reference for all Borg UI environment variables

Environment Variables

Borg UI supports configuration through environment variables. Most settings have sensible defaults and can be configured through the web interface.

Application Settings

PORT · integer · default: "8081"

Port for the web UI to listen on.

PORT=8081

ENVIRONMENT · string · default: "production"

Environment mode. Valid values: production, development.

In development mode:

• Debug mode is automatically enabled
• Log level defaults to DEBUG

ENVIRONMENT=production

TZ · string · default: "host timezone"

Timezone configuration for correct timestamps in archive names and logs.

Common timezones:

• America/New_York
• America/Chicago
• America/Los_Angeles
• Europe/London
• Europe/Paris
• Asia/Kolkata
• Asia/Tokyo

See the full timezone list.

TZ=America/Chicago

APP_VERSION · string · default: "auto-generated"

Application version identifier. Auto-generated in CI/CD. Set manually for local development.

APP_VERSION=local-dev

Reverse Proxy Configuration

BASE_PATH · string · default: "/"

Base path for running behind a reverse proxy in a subfolder.

Requirements:

• Must start with / (e.g., /borg not borg)
• No trailing slash (e.g., /borg not /borg/)
• Requires rebuild: docker-compose up -d --build

Example Nginx configuration:

location /borg/ {
    proxy_pass http://localhost:8081/;
}

BASE_PATH=/borg

User/Group ID Configuration

PUID · integer · default: "1001"

User ID for the container process. Set this to match your host user’s UID for proper file permissions.

Find your UID: id -u

Common values:

• Linux: 1000
• macOS: 501 (varies, run id -u)
• Default: 1001

PUID=1000

PGID · integer · default: "1001"

Group ID for the container process. Set this to match your host user’s GID for proper file permissions.

Find your GID: id -g

Common values:

• Linux: 1000
• macOS: 20 (varies, run id -g)
• Default: 1001

PGID=1000

Security Settings

SECRET_KEY · string · default: "auto-generated"

Secret key for session management and encryption. Auto-generated on first run and persisted to /data/.secret_key.

Do not change this after initial setup unless you want to invalidate all sessions and re-encrypt SSH keys.

SECRET_KEY=your-custom-secret-key-here

LOG_LEVEL · string · default: "INFO"

Application logging level. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.

LOG_LEVEL=INFO

DISABLE_AUTHENTICATION · boolean · default: "false"

Disable built-in authentication and trust reverse proxy headers.

Only use this when Borg UI is behind a reverse proxy that handles authentication (e.g., Authelia, Authentik).

DISABLE_AUTHENTICATION=true

PROXY_AUTH_HEADER · string · default: "X-Forwarded-User"

HTTP header containing the authenticated username from the reverse proxy.

Only used when DISABLE_AUTHENTICATION=true.

PROXY_AUTH_HEADER=X-Forwarded-User

INITIAL_ADMIN_PASSWORD · string · default: "none"

Set the initial admin password on first run. If not provided, a random password is generated and displayed in logs.

INITIAL_ADMIN_PASSWORD=your-secure-password

Host Filesystem Mount

LOCAL_STORAGE_PATH · string · default: "/"

Host filesystem path to mount inside the container at /local.

Default: Entire host filesystem (/) is mounted to /local in the container.

Examples:

# macOS - Only mount user directories
LOCAL_STORAGE_PATH=/Users

# Linux - Only mount home directories
LOCAL_STORAGE_PATH=/home

# Custom - Only mount specific backup directory
LOCAL_STORAGE_PATH=/mnt/backups

Creating repositories:

• macOS: /local/Users/username/backups/my-repo
• Linux: /local/home/username/backups/my-repo
• Custom: /local/path/to/your/backup/location

LOCAL_MOUNT_POINTS · string · default: "/local"

Comma-separated list of container paths where host directories are mounted.

Used for file browser detection and highlighting.

# Default
LOCAL_MOUNT_POINTS=/local

# Multiple mount points
LOCAL_MOUNT_POINTS=/local,/mylocalserver,/data

Borg Operation Timeouts

Increase these timeouts for very large repositories (e.g., 830TB repositories with 166-minute cache build times).

BORG_INFO_TIMEOUT · integer · default: "600"

Timeout in seconds for borg info operations (repository verification, stats).

Default: 10 minutes (600 seconds)

# Very large repository
BORG_INFO_TIMEOUT=7200  # 2 hours

BORG_LIST_TIMEOUT · integer · default: "600"

Timeout in seconds for borg list operations (listing archives and files).

Default: 10 minutes (600 seconds)

BORG_LIST_TIMEOUT=600

BORG_INIT_TIMEOUT · integer · default: "300"

Timeout in seconds for borg init operations (new repository creation).

Default: 5 minutes (300 seconds)

BORG_INIT_TIMEOUT=300

BORG_EXTRACT_TIMEOUT · integer · default: "3600"

Timeout in seconds for borg extract operations (file restoration).

Default: 1 hour (3600 seconds)

BORG_EXTRACT_TIMEOUT=3600

BORG_MOUNT_TIMEOUT · integer · default: "120"

Timeout in seconds for borg mount operations (archive browsing via FUSE).

Default: 2 minutes (120 seconds)

BORG_MOUNT_TIMEOUT=120

SCRIPT_TIMEOUT · integer · default: "120"

Timeout in seconds for pre/post backup scripts.

Default: 2 minutes (120 seconds)

SCRIPT_TIMEOUT=120

SOURCE_SIZE_TIMEOUT · integer · default: "3600"

Timeout in seconds for du-based source size calculation (large datasets).

Default: 1 hour (3600 seconds)

SOURCE_SIZE_TIMEOUT=3600

Redis Cache Configuration

Redis cache provides 600x faster archive browsing. Configure via Settings → Cache tab in the UI (recommended) or use environment variables for initial defaults.

See the Cache Configuration page for detailed setup instructions.

REDIS_URL · string · default: "none"

External Redis connection URL. Takes precedence over REDIS_HOST/REDIS_PORT.

Formats:

• TCP: redis://hostname:port/db
• TCP with password: redis://:password@hostname:port/db
• TLS: rediss://hostname:port/db
• Unix socket: unix:///run/redis.sock?db=0

Examples:

# Remote Redis
REDIS_URL=redis://192.168.1.100:6379/0

# With password
REDIS_URL=redis://:[e-mail]:6379/0

# TLS connection
REDIS_URL=rediss://secure-redis.example.com:6380/0

REDIS_HOST · string · default: "redis"

Redis server hostname. Used if REDIS_URL is not set.

REDIS_HOST=redis

REDIS_PORT · integer · default: "6379"

Redis server port. Used if REDIS_URL is not set.

REDIS_PORT=6379

REDIS_DB · integer · default: "0"

Redis database number (0-15). Used if REDIS_URL is not set.

REDIS_DB=0

REDIS_PASSWORD · string · default: "none"

Redis server password. Used if REDIS_URL is not set.

REDIS_PASSWORD=your-redis-password

CACHE_TTL_SECONDS · integer · default: "7200"

Cache time-to-live in seconds. Archive data is cached for this duration.

Default: 2 hours (7200 seconds)

CACHE_TTL_SECONDS=7200

CACHE_MAX_SIZE_MB · integer · default: "2048"

Maximum cache size in megabytes (used by in-memory fallback cache).

Default: 2GB (2048 MB)

CACHE_MAX_SIZE_MB=2048

Data Directory

DATA_DIR · string · default: "/data"

Main data directory for all persistent data (database, SSH keys, logs, configs).

Do not change this unless you have a specific reason. The Docker volume mount should map to /data in the container.

DATA_DIR=/data

DATABASE_URL · string · default: "sqlite:////data/borg.db"

Database connection URL. Auto-derived from DATA_DIR.

DATABASE_URL=sqlite:////data/borg.db

Complete Example

.env

# Application Settings
PORT=8081
ENVIRONMENT=production
TZ=America/Chicago

# User/Group ID (match your host user)
PUID=1000
PGID=1000

# Host Filesystem Mount
LOCAL_STORAGE_PATH=/home

# Redis Cache (optional - for 600x faster browsing)
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
CACHE_TTL_SECONDS=7200
CACHE_MAX_SIZE_MB=2048

# Borg Timeouts (increase for large repositories)
BORG_INFO_TIMEOUT=600
BORG_LIST_TIMEOUT=600

# Logging
LOG_LEVEL=INFO

Repository Types

Local (Mounted): Store repositories on host filesystem via /local mount (recommended)

Local (Container): Store within container (limited to container storage)

SSH: Access remote repositories via SSH (for remote servers)

Recommended Setup

1. Set LOCAL_STORAGE_PATH to your desired host directory (e.g., /Users or /home)
2. Set PUID and PGID to match your host user: id -u && id -g
3. Configure timezone with TZ
4. Restart container: docker-compose down && docker-compose up -d
5. Create “local” repositories at /local/... in the UI
6. Your backups are stored on the host and survive container rebuilds