Installation Guide

Complete installation instructions for all platforms.

Quick Start

The fastest way to get started:

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 /home/yourusername:/local:rw \
  ainullcode/borg-ui:latest

⚠️ Security Note: Replace /home/yourusername with your actual directory path. See the Restrict Filesystem Access section below for details.

Access at http://localhost:8081

Default credentials: admin / admin123

Installation Methods

Create docker-compose.yml:

version: '3.8'

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
      # Mount directories you want to backup (REPLACE with your actual paths)
      - /home/yourusername:/local:rw     # Replace with your directory path
    environment:
      - TZ=America/Chicago  # Set your timezone
      - PUID=1000
      - PGID=1000

volumes:
  borg_data:
  borg_cache:

⚠️ Security Note: Replace /home/yourusername with your actual directory path. See the Restrict Filesystem Access section below for more information.

Start the container:

docker compose up -d

Portainer

  1. Go to Stacks > Add Stack
  2. Name your stack: borg-ui
  3. Paste the docker-compose configuration above
  4. Click Deploy the stack
  5. Access at http://your-server-ip:8081

Unraid

  1. Install Compose Manager plugin
  2. Go to Docker > Compose > Add New Stack
  3. Name: borg-ui
  4. Paste 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  # Customize to specific shares if needed
    environment:
      - TZ=America/Chicago  # Set your timezone
      - PUID=99
      - PGID=100

Note: /mnt/user provides access to all Unraid shares. For better security, mount specific shares only (e.g., /mnt/user/documents:/local:rw).

  1. Click Compose Up

Option 2: Unraid Web UI

  1. Go to Docker tab > Add Container
  2. Configure:
    • Name: borg-web-ui
    • Repository: ainullcode/borg-ui:latest
    • Network Type: Bridge

Port Mappings:

  • Container Port 8081 → Host Port 8081

Volume Mappings: | Container Path | Host Path | Access | |—————-|———–|——–| | /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:

  • TZ: America/Chicago (your timezone)
  • PUID: 99
  • PGID: 100
  1. Click Apply

Post-Installation

First Login

  1. Access http://localhost:8081 (or your server IP)
  2. Login with default credentials:
    • Username: admin
    • Password: admin123
  3. You’ll be prompted to change your password

Verify Installation

Check that the container is running:

docker ps | grep borg-web-ui
docker logs borg-web-ui

You should see:

INFO: Application startup complete
INFO: Uvicorn running on http://0.0.0.0:8081

Customization

Set your local timezone for correct archive timestamps and scheduling:

environment:
  - TZ=America/Chicago  # Set your timezone
  - PUID=1000
  - PGID=1000

Common timezones:

  • US East Coast: America/New_York
  • US Central: America/Chicago
  • US West Coast: America/Los_Angeles
  • UK: Europe/London
  • Central Europe: Europe/Paris
  • India: Asia/Kolkata
  • Japan: Asia/Tokyo
  • Australia (Sydney): Australia/Sydney

Full timezone list →

Why set timezone? Docker containers default to UTC. Without setting TZ, your archive names and timestamps will show UTC time instead of your local time, which can be confusing.

Change Port

To use a different port:

environment:
  - PORT=8082
ports:
  - "8082:8082"

Restrict Filesystem Access

⚠️ Important Security Consideration

For production use, mount only the specific directories you need to backup instead of broad filesystem access:

volumes:
  # ✅ Recommended: Mount specific directories
  - /home/yourusername:/local:rw         # Replace with your path
  - /mnt/data:/local/data:rw             # Additional directories as needed
  - /opt/myapp:/local/myapp:ro           # Read-only if only backing up

  # ❌ NOT Recommended: Full filesystem access
  # - /:/local:rw  # Security risk - avoid in production

Common Patterns:

Personal Computer:

- /home/john:/local:rw           # Home directory
- /home/john/documents:/local:rw # Or just documents

Server:

- /var/www:/local/www:ro         # Website files (read-only)
- /var/lib/postgresql:/local/db:rw  # Database directory
- /opt/apps:/local/apps:rw       # Application data

Multiple Users:

- /home/user1:/local/user1:rw
- /home/user2:/local/user2:rw
- /mnt/shared:/local/shared:rw

Best Practices:

  • Mount only directories that need backup
  • Use :ro (read-only) for backup-only directories where you won’t restore files
  • For multiple directories, add multiple volume mounts
  • Never mount root (/) unless absolutely necessary for system-level backups

See Configuration Guide for more examples and details.

Set User/Group IDs

Match your host user to avoid permission issues:

# Find your IDs
id -u && id -g

# Set in docker-compose.yml
environment:
  - PUID=1000  # Your user ID
  - PGID=1000  # Your group ID

Updating

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

  1. Go to Stacks
  2. Select borg-ui
  3. Click Pull and redeploy

Advanced Configuration

Docker Container Management (Optional)

If you need to stop/start Docker containers during backups (e.g., for database consistency), you can mount the Docker socket:

⚠️ Security Warning: Mounting /var/run/docker.sock gives the container access to your Docker daemon (equivalent to root access). Only enable if you need this functionality.

Enable Docker Socket Access

Edit your docker-compose.yml and add the docker.sock volume:

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
      - /home/yourusername:/local:rw  # Replace with your path
      # Add this line for Docker container management:
      - /var/run/docker.sock:/var/run/docker.sock:rw
    environment:
      - TZ=America/Chicago
      - PUID=1000
      - PGID=1000

Restart the container:

docker compose down
docker compose up -d

Usage

Once enabled, you can use pre/post backup scripts in your repository configuration to control containers:

Pre-backup script example:

#!/bin/bash
# Install Docker CLI if not present
if ! command -v docker &> /dev/null; then
    curl -fsSL https://get.docker.com | sh
fi

# Stop database container
docker stop postgres-db

Post-backup script example:

#!/bin/bash
# Restart database container
docker start postgres-db

See the Docker Container Hooks Guide for detailed examples, security considerations, and best practices.

Troubleshooting

Container Won’t Start

Check logs:

docker logs borg-web-ui

Port Already in Use

Change the port:

ports:
  - "8082:8081"

Permission Denied Errors

Match your host user ID:

environment:
  - PUID=1000
  - PGID=1000

Find your IDs: id -u && id -g

Cannot Access Web Interface

Check firewall rules:

# Linux
sudo ufw allow 8081

# Check container is running
docker ps | grep borg-web-ui

Wrong Timestamps in Archives

If archive timestamps show UTC instead of your local time:

environment:
  - TZ=Asia/Kolkata  # Add your timezone

Then restart:

docker compose down && docker compose up -d

Verify:

docker exec borg-web-ui date

Uninstallation

Remove Container 

docker compose down
# or
docker stop borg-web-ui && docker rm borg-web-ui

Remove Data (Optional) 

# WARNING: This deletes all application data
docker volume rm borg_data borg_cache

Next Steps

Back to top

Copyright © 2024 Karan Hudia. Distributed under the GPL-3.0 License.