Running Borgitory with Docker

Running Borgitory Locally with Docker

This tutorial will walk you through setting up Borgitory on your local machine using Docker. This is perfect for testing, development, or running a personal backup server.

Prerequisites

• Docker installed on your system
• Basic familiarity with command line/terminal
• At least 1GB of available disk space

Quick Start

1. Create a Project Directory

mkdir borgitory-local
cd borgitory-local

2. Create Required Directories

# Create data directory for persistent storage
mkdir data

# Create directories for backup sources and repositories
mkdir backup-sources
mkdir borg-repos

Your directory structure should look like:

borgitory-local/
├── data/
├── backup-sources/
└── borg-repos/

3. Run with Docker

Option A: Docker Run (Simple)

docker run -d \
  --name borgitory \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/backup-sources:/backup/sources \
  -v $(pwd)/borg-repos:/repos \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --restart unless-stopped \
  mlapaglia/borgitory:latest

Option B: Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'
services:
  borgitory:
    image: mlapaglia/borgitory:latest
    container_name: borgitory
    ports:
      - "8000:8000"
    volumes:
      # Persistent application data
      - ./data:/app/data
      # Source directories to backup (add your own paths here)
      - ./backup-sources:/backup/sources
      # Repository storage location
      - ./borg-repos:/repos
      # Add additional source paths as needed:
      # - /home/user/documents:/backup/documents:ro
      # - /home/user/photos:/backup/photos:ro
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    restart: unless-stopped

Then start the service:

docker compose up -d

4. Access the Application

Open your web browser and navigate to:

http://localhost:8000

You should see the Borgitory login screen.

Initial Setup

Create First User Account

1. On first visit, you'll see a registration form
2. Create your admin username and password (minimum 6 characters)
3. Click "Create Account"
4. You'll be redirected to the login screen
5. Log in with your new credentials

Add Sample Data (Optional)

To test the application, you can add some sample files to backup:

# Create some test files in the backup-sources directory
echo "This is a test file" > backup-sources/test.txt
mkdir backup-sources/documents
echo "Sample document content" > backup-sources/documents/sample.doc

Configuration Examples

Adding Your Real Data

To backup your actual data, modify the Docker volumes to include your real directories:

Docker Run Example:

docker run -d \
  --name borgitory \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v /home/user/documents:/backup/documents:ro \
  -v /home/user/photos:/backup/photos:ro \
  -v /var/backups:/repos \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --restart unless-stopped \
  mlapaglia/borgitory:latest

Docker Compose Example:

volumes:
  - ./data:/app/data
  - /home/user/documents:/backup/documents:ro
  - /home/user/photos:/backup/photos:ro
  - /home/user/music:/backup/music:ro
  - /var/backups/borg-repos:/repos

Volume Mounting Tips

• Source directories: Mount as read-only (:ro) for safety
• Repository directories: Need read-write access (no :ro suffix)
• Use absolute paths: For directories outside your current folder
• Multiple sources: Add as many volume mounts as needed

Important Docker Parameters

Required for Archive Browsing

--cap-add SYS_ADMIN
--device /dev/fuse

These parameters enable FUSE filesystem mounting, which allows:

• Interactive archive browsing through the web interface
• Direct file downloads from archives
• Real-time directory exploration without extraction

Note: Without these parameters, Borgitory will still work but archive browsing will be disabled.

Port Configuration

• Default port: 8000:8000
• Custom port: Use -p 3000:8000 to access on port 3000
• Host binding: Use -p 127.0.0.1:8000:8000 to bind only to localhost

Managing the Container

View Logs

# Docker run
docker logs borgitory

# Docker Compose
docker compose logs -f

Stop the Application

# Docker run
docker stop borgitory

# Docker Compose
docker compose down

Update to Latest Version

# Docker run
docker pull mlapaglia/borgitory:latest
docker stop borgitory
docker rm borgitory
# Then run the docker run command again

# Docker Compose
docker compose pull
docker compose up -d

Access Container Shell (Debugging)

docker exec -it borgitory /bin/bash

Troubleshooting

Port Already in Use

If port 8000 is already in use:

# Check what's using the port
netstat -tlnp | grep :8000

# Use a different port
docker run -p 8080:8000 ...

FUSE Not Available

If you get FUSE-related errors:

# Check if FUSE is installed
ls -la /dev/fuse

# On Ubuntu/Debian
sudo apt-get install fuse

# On CentOS/RHEL
sudo yum install fuse

Permission Issues

If you encounter permission errors:

# Fix ownership of data directory
sudo chown -R $USER:$USER ./data

# Check Docker permissions
docker ps  # Should work without sudo

Container Won't Start

Check the logs for specific error messages:

docker logs borgitory

Common issues:

• Port conflicts
• Volume mount permission issues
• Missing FUSE capabilities

Next Steps

Once Borgitory is running locally:

1. Create your first repository through the web interface
2. Set up backup sources using the mounted volumes
3. Configure automated schedules for regular backups
4. Test archive browsing to explore backup contents
5. Set up cleanup policies to manage archive retention

For production deployments, consider:

• Using external volumes for repository storage
• Setting up SSL/TLS termination with a reverse proxy
• Configuring cloud sync for offsite backups
• Setting up push notifications for job alerts

Security Considerations

When running locally:

• Borgitory binds to all interfaces (0.0.0.0:8000)
• Consider using firewall rules to restrict access
• For development only, not recommended for public internet exposure
• All sensitive data (passphrases, API keys) are encrypted at rest

For production use, deploy behind a reverse proxy with SSL/TLS termination.