Skip to main content

​
Quick Start

The simplest way to get started with Borg UI is using Docker. This method is ideal for testing or simple deployments. 
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
Access the web interface at http://localhost:8081Default credentials: admin / admin123

​
Port Configuration

By default, Borg UI runs on port 8081. You can change this using the PORT environment variable: 
docker run -d \
  --name borg-web-ui \
  -p 3000:3000 \
  -e PORT=3000 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/yourusername:/local:rw \
  ainullcode/borg-ui:latest

​
Volume Mounts Explained

​
Application Data

-v borg_data:/data
Stores all persistent application data:
  • SQLite database (borg.db)
  • SSH keys
  • Borg encryption keys
  • Application logs
  • Configuration files
  • Auto-generated SECRET_KEY

​
Borg Cache

-v borg_cache:/home/borg/.cache/borg
Improves backup performance by caching repository metadata. This significantly speeds up backup operations on subsequent runs.

​
Host Filesystem Access

-v /home/yourusername:/local:rw
Replace /home/yourusername with the actual directory you want to backup on your host system.
This mount gives Borg UI access to files on your host machine. The host directory is mounted at /local inside the container. Production examples: 
docker run -d \
  --name borg-web-ui \
  -p 8081:8081 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /home/username:/local:rw \
  ainullcode/borg-ui:latest
When using custom mount paths (not /local), set the LOCAL_MOUNT_POINTS environment variable to help the UI detect available directories:
-e LOCAL_MOUNT_POINTS=/home,/www,/data

​
Timezone Synchronization

-v /etc/localtime:/etc/localtime:ro
Syncs the container timezone with your host system. This ensures correct timestamps in backup archives and logs. Alternatively, set the timezone via environment variable: 
-e TZ=America/New_York

​
Docker Socket (Optional)

-v /var/run/docker.sock:/var/run/docker.sock:rw
Required only if you want to stop/start Docker containers during backups using pre/post backup scripts.

​
Environment Variables

​
Core Settings

VariableDefaultDescription
PORT8081Web interface port
ENVIRONMENTproductionApplication environment mode
LOG_LEVELINFOLogging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

​
User/Group IDs

-e PUID=1001 \
-e PGID=1001
Set these to match your host user’s UID/GID for proper file permissions. Find yours with: 
id -u && id -g

​
Timezone

-e TZ=America/New_York
Common timezones:
  • America/New_York
  • America/Chicago
  • America/Los_Angeles
  • Europe/London
  • Europe/Paris
  • Asia/Kolkata
  • Asia/Tokyo

​
Security

-e SECRET_KEY=your-custom-secret-key
-e INITIAL_ADMIN_PASSWORD=your-secure-password
If not set, SECRET_KEY is auto-generated and persisted to /data/.secret_key. For production deployments, it’s recommended to set a custom secret key.

​
Borg Timeouts

For large repositories with long cache build times: 
-e BORG_INFO_TIMEOUT=600 \
-e BORG_LIST_TIMEOUT=600 \
-e BORG_INIT_TIMEOUT=300 \
-e BORG_EXTRACT_TIMEOUT=3600 \
-e SCRIPT_TIMEOUT=120
VariableDefaultDescription
BORG_INFO_TIMEOUT600borg info operations (10 min)
BORG_LIST_TIMEOUT600borg list operations (10 min)
BORG_INIT_TIMEOUT300borg init operations (5 min)
BORG_EXTRACT_TIMEOUT3600borg extract operations (1 hour)
SCRIPT_TIMEOUT120Pre/post backup scripts (2 min)

​
Disable Authentication

-e DISABLE_AUTHENTICATION=true
Only use this in secure, private networks. Not recommended for production.

​
Complete Example

Production deployment with all recommended settings: 
docker run -d \
  --name borg-web-ui \
  --restart unless-stopped \
  -p 8081:8081 \
  -v borg_data:/data \
  -v borg_cache:/home/borg/.cache/borg \
  -v /etc/localtime:/etc/localtime:ro \
  -v /home/username:/local:rw \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  -e TZ=America/New_York \
  -e INITIAL_ADMIN_PASSWORD=MySecurePassword123! \
  ainullcode/borg-ui:latest

​
Multi-Architecture Support

Borg UI supports the following architectures:
  • amd64 (x86_64)
  • arm64 (aarch64)
  • armv7 (32-bit ARM)
Docker automatically pulls the correct image for your platform.

​
Updating

To update to the latest version:
1

Pull the latest image

docker pull ainullcode/borg-ui:latest
2

Stop and remove the old container

docker stop borg-web-ui
docker rm borg-web-ui
3

Start with the new image

Run your original docker run command again. All data is preserved in the volumes.

​
Managing the Container

​
View logs

docker logs borg-web-ui

​
Follow logs in real-time

docker logs -f borg-web-ui

​
Stop the container

docker stop borg-web-ui

​
Start the container

docker start borg-web-ui

​
Restart the container

docker restart borg-web-ui

​
Access container shell

docker exec -it borg-web-ui bash

​
Troubleshooting

​
Permission Issues

If you encounter permission errors accessing host files:
  1. Check your PUID/PGID match your host user: 
    id -u && id -g
  2. Verify volume mount permissions: 
    ls -la /home/yourusername
  3. Restart container with correct PUID/PGID: 
    docker stop borg-web-ui
docker rm borg-web-ui
# Run docker run command with correct -e PUID and -e PGID

​
Port Already in Use

If port 8081 is already in use: 
# Use a different host port
docker run -d \
  --name borg-web-ui \
  -p 8082:8081 \
  # ... rest of command
Or change both host and container ports: 
docker run -d \
  --name borg-web-ui \
  -p 3000:3000 \
  -e PORT=3000 \
  # ... rest of command

​
Next Steps

Docker Compose

Recommended method for production deployments

Reverse Proxy

Run behind Nginx or Traefik

Build docs developers (and LLMs) love

Get started for freeTalk to us