Docker Compose Deployment

Deploy Borg UI with Docker Compose (recommended method)

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

1. 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.

2. 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
   
3. Start the services

   docker-compose up -d
   
4. Verify it's running

   docker-compose ps
   

   Access the web interface at http://localhost:8081

   Default 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

Single directory

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

volumes:
  - /home/username:/home:rw
  - /var/www:/www:ro
  - /mnt/data:/data:rw
environment:
  - LOCAL_MOUNT_POINTS=/home,/www,/data

volumes:
  - /:/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

All services

docker-compose logs -f

docker-compose logs -f app
docker-compose logs -f redis

docker-compose logs --tail=100 app

Restart services

docker-compose restart

Check service status

docker-compose ps

Update to latest version

1. Pull latest images

   docker-compose pull
   
2. Recreate containers

   docker-compose up -d
   
3. 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

1. Check PUID/PGID match your host user:

   id -u && id -g
   

2. Update .env file with correct values

3. 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

Next Steps

Reverse Proxy

Run behind Nginx or Traefik with SSL

Unraid

Deploy on Unraid with Community Applications