Installation Guide

Borg UI runs as a Docker container with support for multiple architectures (amd64, arm64, armv7). Choose your preferred installation method below.

All installation methods use the same Docker image: ainullcode/borg-ui:latestAvailable on Docker Hub

Prerequisites

Docker installed on your system
Basic understanding of Docker volumes and networking
Access to directories you want to back up

Installation Methods

Docker Compose

Recommended - Easy management and configuration

Docker Run

Quick single-command installation

Portainer

Visual Docker management interface

Unraid

NAS-optimized installation

Docker Compose (Recommended)

Docker Compose provides the best experience for managing Borg UI with easy configuration and updates.

Option 1: Basic Setup (No Redis)

Good for occasional use with smaller repositories. Uses in-memory caching.

Create docker-compose.yml

Create a new file called docker-compose.yml:

docker-compose.yml

services:
  borg-ui:
    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
      - /path/to/your/data:/local:rw   # Replace with your directory
    environment:
      - TZ=America/Chicago               # Replace with your timezone
      - PUID=1000                        # Replace with your user ID
      - PGID=1000                        # Replace with your group ID

volumes:
  borg_data:
  borg_cache:

Important replacements:

/path/to/your/data → Directory you want to back up (e.g., /home/john)
America/Chicago → Your timezone (see list)
1000 → Your user/group ID (find with: id -u && id -g)

Start the container

docker compose up -d

Check the logs:

docker compose logs -f

Access the web interface

Open your browser to:

http://localhost:8081

Default credentials:

Username: admin
Password: admin123

You’ll be prompted to change the password on first login.

Option 2: With Redis (Recommended for Production)

Redis provides 600x faster archive browsing for large repositories. Recommended if you browse archives regularly.

Create docker-compose.yml with Redis

docker-compose.yml

services:
  borg-ui:
    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
      - /path/to/your/data:/local:rw   # Replace with your directory
    environment:
      - TZ=America/Chicago               # Replace with your timezone
      - PUID=1000                        # Run: id -u
      - PGID=1000                        # Run: id -g
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - CACHE_TTL_SECONDS=7200           # 2 hours cache
      - CACHE_MAX_SIZE_MB=2048           # 2GB max cache
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - borg_network

  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
    networks:
      - borg_network

networks:
  borg_network:

volumes:
  borg_data:
  borg_cache:

Deploy the stack

docker compose up -d

Verify both containers are running:

docker compose ps

Option 3: External Redis

Use an existing Redis instance on your network or a separate machine.

services:
  borg-ui:
    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
      - /path/to/your/data:/local:rw
    environment:
      - TZ=America/Chicago
      - PUID=1000
      - PGID=1000
      - REDIS_URL=redis://192.168.1.100:6379/0  # External Redis
      # With password:
      # - REDIS_URL=redis://:[email protected]:6379/0

volumes:
  borg_data:
  borg_cache:

Docker Run

Quick single-command installation for simple setups.

Basic Installation

docker run -d \
  --name borg-web-ui \
  --restart unless-stopped \
  -p 8081:8081 \
  -e TZ=America/Chicago \
  -e PUID=1000 \
  -e PGID=1000 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /path/to/your/data:/local:rw \
  ainullcode/borg-ui:latest

Replace /path/to/your/data with the directory you want to back up (e.g., /home/john, /mnt/photos).

With Docker Socket (Optional)

Mount the Docker socket to enable Docker container management in pre/post backup scripts:

docker run -d \
  --name borg-web-ui \
  --restart unless-stopped \
  -p 8081:8081 \
  -e TZ=America/Chicago \
  -e PUID=1000 \
  -e PGID=1000 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /path/to/your/data:/local:rw \
  -v /var/run/docker.sock:/var/run/docker.sock:rw \
  ainullcode/borg-ui:latest

See the Backup Scripts Guide for examples of stopping/starting containers during backups.

Portainer

Portainer provides a visual interface for managing Docker containers.

Navigate to Stacks

In Portainer, go to:

Stacks → Add Stack

Create the stack

Name: borg-ui
Build method: Web editor
Paste one of the Docker Compose configurations above

Customize configuration

Update the following in the compose file:

Replace /path/to/your/data with your backup directory
Set your timezone in TZ variable
Set PUID and PGID to match your user (run id -u && id -g)

Deploy the stack

Click Deploy the stack at the bottomMonitor deployment in the logs viewer.

Access Borg UI

Navigate to:

http://your-server-ip:8081

Unraid

Unraid users have two installation options: Docker Compose Manager (recommended) or the traditional web UI method.

Option 1: Docker Compose Manager (Recommended)

Install Compose Manager plugin

Go to Apps tab
Search for “Compose Manager”
Install the plugin

Create a new stack

Navigate to Docker → Compose
Click Add New Stack
Name: borg-ui

Add the compose configuration

services:
  borg-ui:
    image: ainullcode/borg-ui:latest
    container_name: borg-web-ui
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - /mnt/user/appdata/borg-ui:/data
      - /mnt/user/appdata/borg-ui/cache:/home/borg/.cache/borg
      - /mnt/user:/local:rw  # Backup entire user share
      # Or mount specific shares:
      # - /mnt/user/documents:/local/documents:rw
      # - /mnt/user/photos:/local/photos:rw
    environment:
      - TZ=America/Chicago   # Your timezone
      - PUID=99              # Unraid default
      - PGID=100             # Unraid default
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - borg_network

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

networks:
  borg_network:

Unraid defaults:

PUID=99 and PGID=100 are standard for Unraid
/mnt/user provides access to all user shares
Appdata is stored in /mnt/user/appdata/borg-ui

Deploy the stack

Click Compose Up to start the stackAccess at: http://tower-ip:8081

Option 2: Unraid Web UI (Traditional)

Add container

Navigate to Docker tab → Add Container

Basic settings

Setting	Value
Name	`borg-web-ui`
Repository	`ainullcode/borg-ui:latest`
Network Type	`Bridge`

Port mappings

Container Port	Host Port
`8081`	`8081`

Volume mappings

Container Path	Host Path	Mode
`/data`	`/mnt/user/appdata/borg-ui`	Read/Write
`/home/borg/.cache/borg`	`/mnt/user/appdata/borg-ui/cache`	Read/Write
`/local`	`/mnt/user`	Read/Write

Environment variables

Variable	Value
`TZ`	`America/Chicago`
`PUID`	`99`
`PGID`	`100`

Apply and start

Click Apply to create and start the container

For Redis support with the traditional web UI method, you’ll need to create a separate Redis container and link them via Docker networks.

Advanced Configuration

Mount Multiple Directories

You can mount as many directories as needed:

volumes:
  # Recommended: Nest everything under /local
  - /home/john:/local/home:rw
  - /var/www:/local/www:ro          # Read-only
  - /mnt/photos:/local/photos:rw

  # Alternative: Use custom paths
  - /home/john:/home:rw
  - /mnt/disk1:/disk1:rw
  - /mnt/disk2:/disk2:rw

If you use custom container paths (not /local), set the LOCAL_MOUNT_POINTS environment variable:

environment:
  - LOCAL_MOUNT_POINTS=/home,/disk1,/disk2

Environment Variables

Common environment variables:

Variable	Default	Description
`PORT`	`8081`	Web interface port
`TZ`	Host timezone	Timezone for timestamps
`PUID`	`1001`	User ID for file permissions
`PGID`	`1001`	Group ID for file permissions
`REDIS_HOST`	-	Redis hostname for caching
`REDIS_PORT`	`6379`	Redis port
`REDIS_URL`	-	Full Redis URL (alternative to HOST/PORT)
`CACHE_TTL_SECONDS`	`7200`	Cache expiration (2 hours)
`CACHE_MAX_SIZE_MB`	`2048`	Max cache size (2GB)
`LOG_LEVEL`	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`LOCAL_MOUNT_POINTS`	`/local`	Comma-separated container mount paths

See the Environment Variables Guide for a complete list of environment variables and advanced settings.

Privileged Mode (Optional)

Privileged mode is only required for remote-to-remote backups using SSHFS mounting.

services:
  borg-ui:
    image: ainullcode/borg-ui:latest
    privileged: true  # Only for SSHFS remote mounts
    # ... rest of config

Only enable privileged mode if you need SSHFS mounting for backing up remote servers. For local and direct SSH backups, privileged mode is not required.

Timeouts for Large Repositories

For very large repositories, increase operation timeouts:

environment:
  - BORG_INFO_TIMEOUT=7200       # 2 hours for initial cache build
  - BORG_LIST_TIMEOUT=600        # 10 minutes for archive listing
  - BORG_EXTRACT_TIMEOUT=3600    # 1 hour for file extraction

Post-Installation

Access the web interface

Navigate to http://localhost:8081 (or your server’s IP)Default credentials:

Username: admin
Password: admin123

Change default password

You’ll be prompted to change the password on first login for security.

Create your first repository

Follow the Quick Start Guide to create your first backup.

Updating Borg UI

Docker Compose

docker compose pull
docker compose up -d

Docker Run

docker pull ainullcode/borg-ui:latest
docker stop borg-web-ui
docker rm borg-web-ui
# Run the docker run command again

Portainer

Go to Stacks
Select borg-ui
Click Pull and redeploy

Unraid

Go to Docker tab
Find borg-web-ui
Click Update icon

Your data, configurations, and backups are stored in Docker volumes and persist across updates.

Troubleshooting

Container won't start

Check the logs:

docker logs borg-web-ui

Common issues:

Port conflict: Change -p 8082:8081 to use different port
Volume permissions: Ensure mounted directories exist and are readable
Invalid environment variables: Check syntax in compose file

Permission errors when accessing files

Set correct PUID/PGID:

On your host, run:
```
id -u && id -g
```

Update environment:

environment:
  - PUID=1000  # Your user ID
  - PGID=1000  # Your group ID

Recreate container:

docker compose down && docker compose up -d

Can't access web interface

Check container is running:
```
docker ps | grep borg-web-ui
```
Check firewall:
```
sudo ufw allow 8081
```
Verify port mapping:
```
docker port borg-web-ui
```
Check logs for errors:
```
docker logs borg-web-ui
```

Redis connection failed

Check Redis is running:
```
docker ps | grep redis
```
Test Redis connection:
```
docker exec borg-redis redis-cli ping
```
Should return PONG
Verify network connectivity:
```
docker exec borg-web-ui ping redis
```

Check Redis health:

docker inspect borg-redis | grep Health -A 10

Wrong timestamps in archives

Set your timezone:

environment:
  - TZ=America/Chicago  # Replace with your timezone

Find your timezone: List of timezonesThen restart:

docker compose down && docker compose up -d

Uninstalling

Remove container only

docker compose down

Your data and backups remain in Docker volumes.

Remove everything (including backups)

This will delete all data including your backup repositories!

docker compose down -v
docker volume rm borg_data borg_cache

Next Steps

Quick Start

Create your first backup in minutes

Usage Guide

Learn all features and workflows

Configuration

Customize advanced settings

Notifications

Set up backup alerts

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Installation Guide

​Prerequisites

​Installation Methods

Docker Compose

Docker Run

Portainer

Unraid

​Docker Compose (Recommended)

​Option 1: Basic Setup (No Redis)

​Option 2: With Redis (Recommended for Production)

​Option 3: External Redis

​Docker Run

​Basic Installation

​With Docker Socket (Optional)

​Portainer

​Unraid

​Option 1: Docker Compose Manager (Recommended)

​Option 2: Unraid Web UI (Traditional)

​Advanced Configuration

​Mount Multiple Directories

​Environment Variables

​Privileged Mode (Optional)

​Timeouts for Large Repositories

​Post-Installation

​Updating Borg UI

​Docker Compose

​Docker Run

​Portainer

​Unraid

​Troubleshooting

​Uninstalling

​Remove container only

​Remove everything (including backups)

​Next Steps

Quick Start

Usage Guide

Configuration

Notifications

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Installation Methods

Docker Compose (Recommended)

Option 1: Basic Setup (No Redis)

Option 2: With Redis (Recommended for Production)

Option 3: External Redis

Docker Run

Basic Installation

With Docker Socket (Optional)

Portainer

Unraid

Option 1: Docker Compose Manager (Recommended)

Option 2: Unraid Web UI (Traditional)

Advanced Configuration

Mount Multiple Directories

Environment Variables

Privileged Mode (Optional)

Timeouts for Large Repositories

Post-Installation

Updating Borg UI

Docker Compose

Docker Run

Portainer

Unraid

Troubleshooting

Uninstalling

Remove container only

Remove everything (including backups)

Next Steps