Skip to main content

​
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 -uCommon 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 -gCommon 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://:[email protected]: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)
  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

Build docs developers (and LLMs) love

Get started for freeTalk to us