Docker Compose Deployment

Overview

Docker Compose is the recommended deployment method for Borg UI. It provides:

Automatic Redis setup for 600x faster archive browsing
Persistent volumes for data and cache
Health checks and automatic restarts
Easy configuration via .env file
Service dependencies and networking

Quick Start

Create docker-compose.yml

Create a docker-compose.yml file:

services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    privileged: true  # Required only for remote-to-remote backups via SSHFS

    ports:
      - "${PORT:-8081}:${PORT:-8081}"

    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /etc/localtime:/etc/localtime:ro
      - /home/yourusername:/local:rw  # Replace with your directory

    environment:
      - PORT=${PORT:-8081}
      - ENVIRONMENT=${ENVIRONMENT:-production}
      - PUID=${PUID:-1001}
      - PGID=${PGID:-1001}
      - TZ=${TZ:-}
      - LOCAL_MOUNT_POINTS=${LOCAL_MOUNT_POINTS:-/local}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_DB=0
      - CACHE_TTL_SECONDS=7200
      - CACHE_MAX_SIZE_MB=2048

    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://localhost:$${PORT:-8081}/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

    networks:
      - borg_network

    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

    ports:
      - "${REDIS_PORT:-6379}:6379"

    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s

    networks:
      - borg_network

networks:
  borg_network:
    driver: bridge

volumes:
  borg_data:
    driver: local
  borg_cache:
    driver: local

Replace /home/yourusername with the actual directory you want to backup.

Create .env file (optional)

Create a .env file in the same directory to customize settings:

# Port configuration
PORT=8081

# Environment mode
ENVIRONMENT=production

# User/Group IDs (run: id -u && id -g)
PUID=1001
PGID=1001

# Timezone
TZ=America/New_York

# Redis port
REDIS_PORT=6379

Start the services

docker-compose up -d

Verify it's running

docker-compose ps

Access the web interface at http://localhost:8081Default credentials: admin / admin123

Configuration

Volume Mounts

Application Data

- borg_data:/data

Stores all persistent application data:

SQLite database
SSH keys and Borg encryption keys
Configuration files
Logs
Auto-generated SECRET_KEY

Borg Cache

- borg_cache:/home/borg/.cache/borg

Improves backup performance by caching repository metadata.

Host Filesystem

volumes:
  - /home/username:/local:rw
environment:
  - LOCAL_MOUNT_POINTS=/local

Mounting the entire root filesystem (/) should only be used for development/testing. In production, mount only the directories you need to backup.

Docker Socket (Optional)

- /var/run/docker.sock:/var/run/docker.sock:rw

Required only for stopping/starting Docker containers during backups via pre/post backup scripts.

Environment Variables

Core Settings

environment:
  - PORT=8081
  - ENVIRONMENT=production
  - LOG_LEVEL=INFO

User/Group IDs

- PUID=1001  # Run: id -u
- PGID=1001  # Run: id -g

Set these to match your host user for proper file permissions.

Timezone

- TZ=America/New_York

Ensures correct timestamps in backup archives and logs.

Security

- INITIAL_ADMIN_PASSWORD=MySecurePassword123!
- SECRET_KEY=your-custom-secret-key-here

If SECRET_KEY is not set, it will be auto-generated and persisted to /data/.secret_key.

Redis Cache

- REDIS_HOST=redis
- REDIS_PORT=6379
- REDIS_DB=0
- CACHE_TTL_SECONDS=7200    # 2 hours
- CACHE_MAX_SIZE_MB=2048    # 2GB

Provides 600x faster archive browsing for large repositories.

Borg Timeouts

For large repositories with long cache build times:

- BORG_INFO_TIMEOUT=7200     # 2 hours for initial cache build
- BORG_LIST_TIMEOUT=600      # 10 minutes
- BORG_INIT_TIMEOUT=300      # 5 minutes
- BORG_EXTRACT_TIMEOUT=3600  # 1 hour
- SCRIPT_TIMEOUT=120         # 2 minutes

Disable Authentication

- DISABLE_AUTHENTICATION=true

Only use this in secure, private networks. Not recommended for production.

Privileged Mode

privileged: true

Privileged mode is required only for remote-to-remote backups via SSHFS. If you only use local or direct SSH backups, you can remove this line.

This allows mounting remote SSH locations as local filesystems using SSHFS.

Redis Configuration

The included Redis service is configured for optimal caching:

command: >
  redis-server
  --maxmemory 2gb
  --maxmemory-policy allkeys-lru
  --save ""
  --appendonly no

maxmemory: Limits Redis memory usage to 2GB
allkeys-lru: Evicts least recently used keys when memory limit is reached
save "": Disables persistence (cache data doesn’t need to survive restarts)
appendonly no: Disables append-only file for better performance

Using External Redis

To use an external Redis instance:

environment:
  - REDIS_URL=redis://192.168.1.100:6379/0

Or remove the REDIS_URL and set individual parameters:

environment:
  - REDIS_HOST=192.168.1.100
  - REDIS_PORT=6379
  - REDIS_DB=0

Then remove the redis service from your docker-compose.yml.

Management Commands

Start services

docker-compose up -d

Stop services

docker-compose down

View logs

docker-compose logs -f

Restart services

docker-compose restart

Check service status

docker-compose ps

Update to latest version

Pull latest images

docker-compose pull

Recreate containers

docker-compose up -d

Remove old images

docker image prune

Rebuild from source

If using the build context instead of pre-built images:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
      args:
        - APP_VERSION=${APP_VERSION:-local-dev}

Then rebuild:

docker-compose up -d --build

Access container shell

docker-compose exec app bash

View resource usage

docker-compose stats

Production Example

Complete production-ready configuration:

docker-compose.yml

services:
  app:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped

    ports:
      - "8081:8081"

    volumes:
      - borg_data:/data
      - borg_cache:/home/borg/.cache/borg
      - /etc/localtime:/etc/localtime:ro
      - /home/user:/home:rw
      - /var/www:/www:ro
      - /mnt/backups:/backups:rw

    environment:
      - PORT=8081
      - ENVIRONMENT=production
      - PUID=1001
      - PGID=1001
      - TZ=America/New_York
      - LOCAL_MOUNT_POINTS=/home,/www,/backups
      - INITIAL_ADMIN_PASSWORD=ChangeThisSecurePassword123!
      - LOG_LEVEL=INFO
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_DB=0
      - CACHE_TTL_SECONDS=7200
      - CACHE_MAX_SIZE_MB=2048
      - BORG_INFO_TIMEOUT=7200
      - BORG_LIST_TIMEOUT=600

    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://localhost:8081/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

    networks:
      - borg_network

    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
      start_period: 10s

    networks:
      - borg_network

networks:
  borg_network:
    driver: bridge

volumes:
  borg_data:
    driver: local
  borg_cache:
    driver: local

.env

PORT=8081
ENVIRONMENT=production
PUID=1001
PGID=1001
TZ=America/New_York

Troubleshooting

Services not starting

Check logs for errors:

docker-compose logs app

Redis connection issues

Verify Redis is healthy:

docker-compose ps redis
docker-compose logs redis

Test Redis connection:

docker-compose exec redis redis-cli ping

Permission issues

Check PUID/PGID match your host user:
```
id -u && id -g
```
Update .env file with correct values

Recreate containers:

docker-compose down
docker-compose up -d

Port conflicts

If port 8081 is already in use, change it in .env:

PORT=8082

Then restart:

docker-compose down
docker-compose up -d

Health check failures

Increase start_period for slower systems:

healthcheck:
  start_period: 60s  # Increase from 40s

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Overview

​Quick Start

​Configuration

​Volume Mounts

​Application Data

​Borg Cache

​Host Filesystem

​Docker Socket (Optional)

​Environment Variables

​Core Settings

​User/Group IDs

​Timezone

​Security

​Redis Cache

​Borg Timeouts

​Disable Authentication

​Privileged Mode

​Redis Configuration

​Using External Redis

​Management Commands

​Start services

​Stop services

​View logs

​Restart services

​Check service status

​Update to latest version

​Rebuild from source

​Access container shell

​View resource usage

​Production Example

​Troubleshooting

​Services not starting

​Redis connection issues

​Permission issues

​Port conflicts

​Health check failures

​Next Steps

Reverse Proxy

Unraid

Build docs developers (and LLMs) love

Overview

Quick Start

Configuration

Volume Mounts

Application Data

Borg Cache

Host Filesystem

Docker Socket (Optional)

Environment Variables

Core Settings

User/Group IDs

Timezone

Security

Redis Cache

Borg Timeouts

Disable Authentication

Privileged Mode

Redis Configuration

Using External Redis

Management Commands

Start services

Stop services

View logs

Restart services

Check service status

Update to latest version

Rebuild from source

Access container shell

View resource usage

Production Example

Troubleshooting

Services not starting

Redis connection issues

Permission issues

Port conflicts

Health check failures

Next Steps