Quick Start Guide

Get from zero to your first backup in under 5 minutes using Docker.

Pull and Run Borg UI

Run the following command to start Borg UI with Docker:

docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/yourusername:/local:rw \
  ainullcode/borg-ui:latest

Replace /home/yourusername with the directory you want to back up. This mounts your host directory to /local inside the container.

What this does:

Maps port 8081 for web access
Creates borg_data volume for application data (database, SSH keys, logs)
Creates borg_cache volume for Borg’s repository cache (improves performance)
Mounts your data directory to /local in the container

Access the Web Interface

Open your browser and navigate to:

http://localhost:8081

Default Login Credentials:

Username: admin
Password: admin123

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

Create Your First Repository

A repository is where Borg stores your backups. Let’s create one:

Click “Repositories” in the sidebar
Click “Create Repository” button
Fill in the repository details:

Repository Name: my-first-backup
Repository Path: /local/backups/borg-repo
Repository Type: Local
Encryption: repokey
Passphrase: [secure-password]

Save your passphrase securely! If you lose it, your backups are unrecoverable. Borg uses strong encryption with no backdoors.

Click “Create” - the repository will be initialized

Configure Source Directories

Now tell Borg what to back up:

In the repository details page, find “Source Directories”
Click “Add Source”
Enter the path to back up: /local/Documents (or any directory you mounted)
Optionally add exclude patterns:
- *.tmp
- node_modules
- .git

The /local prefix corresponds to your mounted volume. If you mounted /home/yourusername:/local, then /local/Documents backs up /home/yourusername/Documents on your host.

Run Your First Backup

Time to create your first backup!

Click the “Backup Now” button in the repository details
Optionally add a custom archive name or let it auto-generate
Watch the real-time progress:
- Current file being processed
- Backup speed (MB/s)
- Data statistics (original size, compressed, deduplicated)
- Estimated time remaining

Your first backup is complete! 🎉

What’s Next?

Schedule Automatic Backups

Set up automated backups using the visual cron builder

Browse & Restore Files

Browse your backup archives and restore individual files

Configure Notifications

Get alerts via Email, Slack, Discord, and 100+ other services

SSH Remote Backups

Back up to remote servers via SSH/SFTP

Pro Tips

Use Docker Compose for better management

Instead of docker run, use Docker Compose for easier management:Create a docker-compose.yml file:

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
    environment:
      - TZ=America/Chicago
      - PUID=1000
      - PGID=1000

volumes:
  borg_data:
  borg_cache:

Then run:

docker compose up -d

See the Installation Guide for more options including Redis caching.

Add Redis for 600x faster archive browsing

For large repositories with thousands of files, Redis caching dramatically speeds up archive browsing.Update your docker-compose.yml to include Redis:

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
    environment:
      - TZ=America/Chicago
      - PUID=1000
      - PGID=1000
      - 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:

volumes:
  borg_data:
  borg_cache:

Learn more in the Cache Configuration guide.

Set correct file permissions with PUID/PGID

If you encounter permission errors when accessing mounted directories, set the correct user/group IDs:

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

Add these as environment variables:

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

Restart the container:

docker compose down && docker compose up -d

The container will automatically adjust file permissions to match your host user.

Mount multiple directories

You can mount as many directories as needed:

volumes:
  - borg_data:/data
  - borg_cache:/home/borg/.cache/borg
  - /home/yourusername:/local/home:rw
  - /var/www:/local/www:ro
  - /mnt/photos:/local/photos:rw

Then create backups from:

/local/home/Documents
/local/www/html
/local/photos/2024

The /local prefix is just a convention. You can use any container path, but remember to set LOCAL_MOUNT_POINTS environment variable to match:

environment:
  - LOCAL_MOUNT_POINTS=/local,/data,/custom

Common First-Time Questions

Where are my backups actually stored?

Your backups are stored in the repository path you specified during setup. In our quick start example, that’s /local/backups/borg-repo inside the container.Since /local is mapped to /home/yourusername on your host, the actual location on your host is:

/home/yourusername/backups/borg-repo

This is where Borg creates its deduplicated backup repository with all your archives.

Can I back up to an external drive?

Absolutely! Just mount your external drive and point the repository there:

docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/yourusername:/local:rw \
  -v /mnt/external-drive:/backup:rw \
  ainullcode/borg-ui:latest

Then create a repository at /backup/borg-repo.

How do I restore files?

Go to Repositories → Select your repository
Click on Archives tab
Select the archive (backup snapshot) you want to browse
Navigate through the file tree
Select files/folders and click “Restore”
Choose the destination path

The UI provides a file browser with 600x faster performance when using Redis caching.

What's the difference between encryption types?

Borg UI supports two encryption modes:repokey (Recommended)

Encryption key is stored in the repository
Easier to work with on multiple machines
Key is backed up with repository
Protected by your passphrase

keyfile

Encryption key is stored separately on your local machine
More secure (key not in repository)
You must manage the keyfile yourself
Required on each machine accessing the repository

Both modes use strong encryption (AES-256). Choose repokey for simplicity, keyfile for maximum security.

Can I access the container from other devices?

Yes! Just replace localhost with your server’s IP address:

http://192.168.1.100:8081

If you can’t access it, check your firewall:

sudo ufw allow 8081

For production use, consider setting up a reverse proxy with HTTPS. See the Reverse Proxy Guide for details.

Troubleshooting

Container won't start

Check the container logs:

docker logs borg-web-ui

Common issues:

Port 8081 already in use → Change to different port: -p 8082:8081
Volume permission errors → Set PUID/PGID to match your user

Can't access mounted directories

Verify the mount path exists on your host
Check container can see the mount:
```
docker exec borg-web-ui ls /local
```
Set correct PUID/PGID:
```
id -u && id -g
```
Add to environment: PUID=1000 and PGID=1000

Backup is very slow

First backup is always slower due to:

Full data read and chunking
Building repository cache
Calculating deduplication

Subsequent backups are much faster due to deduplication.To speed up:

Use fast compression like lz4 instead of zlib or lzma
Exclude unnecessary files (node_modules, .git, caches)
Ensure good disk I/O on both source and repository

Next Steps

Now that you have Borg UI running:

Set up automated backups - Use the visual cron builder
Configure notifications - Get alerts when backups succeed or fail
Enable Redis caching - Speed up archive browsing by 600x
Set up SSH backups - Back up to remote servers
Read security best practices - Keep your backups secure

Have questions? Join our Discord community for help!

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

Quick Start

Quick Start Guide

What’s Next?

Schedule Automatic Backups

Browse & Restore Files

Configure Notifications

SSH Remote Backups

Pro Tips

Common First-Time Questions

Troubleshooting

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Quick Start Guide

​What’s Next?

Schedule Automatic Backups

Browse & Restore Files

Configure Notifications

SSH Remote Backups

​Pro Tips

​Common First-Time Questions

​Troubleshooting

​Next Steps

Build docs developers (and LLMs) love

Quick Start Guide

What’s Next?

Pro Tips

Common First-Time Questions

Troubleshooting

Next Steps