Installation Guide

Borgitory can be installed in multiple ways depending on your preferences and environment. Docker is the recommended installation method as it provides the easiest setup with all dependencies included. This guide covers all installation methods and their requirements.

Prerequisites

Before installing Borgitory, ensure you have the following prerequisites:

System Requirements

Operating System: Linux, macOS, or Windows
Python: 3.11 or higher (for PyPI installation)
Docker: Docker with Docker Compose (for containerized deployment)

Note

Windows Users: For full functionality including archive browsing, Docker installation is strongly recommended as FUSE (required for archive browsing) is not available on Windows.

Alternatively, you can use WSL2 (Windows Subsystem for Linux) to run Borgitory natively. See the Windows WSL Setup Guide guide for complete WSL2 setup instructions.

Installation Methods

Method 1: Docker Installation (Recommended)

Docker is the recommended way to run Borgitory as it provides an isolated environment with all dependencies pre-configured:

Using Docker Directly

# Pull and run the Docker image
docker run -d \
  -p 8000:8000 \
  -v ./data:/app/data \
  -v /path/to/backup/sources:/mnt/backup/sources:ro \
  -v /path/to/borg/repos:/mnt/repos \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --name borgitory \
  mlapaglia/borgitory:latest

Using Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'
services:
  borgitory:
    image: mlapaglia/borgitory:latest
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
      - /path/to/backup/sources:/mnt/backup/sources:ro
      - /path/to/borg/repos:/mnt/repos
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse
    restart: unless-stopped

Then start the container:

docker-compose up -d

Docker Installation Benefits:

All dependencies (BorgBackup, Rclone, FUSE) pre-installed
Isolated environment with consistent behavior
Easy updates and rollbacks
No system-level dependency conflicts

Method 2: PyPI Installation

For users who prefer a native Python installation:

# Install stable release from PyPI
pip install borgitory

# Start the server
borgitory serve

# Or run with custom settings
borgitory serve --host 0.0.0.0 --port 8000

PyPI Installation Requirements:

Python 3.11 or higher
BorgBackup installed and available in PATH
Rclone (optional, for cloud sync features)
FUSE (Linux/macOS only, for archive browsing)

Note

PyPI installation requires manual setup of BorgBackup and Rclone dependencies. For easier setup, consider using the Docker installation method.

Warning

Windows Limitation: FUSE (Filesystem in Userspace) is not available on Windows, which means archive browsing functionality will not work with PyPI installation on Windows. The Docker installation includes a Linux environment where FUSE works properly, making it the recommended approach for Windows users who need archive browsing.

Method 3: Development Installation

For development or contributing to Borgitory:

# Clone the repository
git clone https://github.com/mlapaglia/Borgitory.git
cd Borgitory

# Create virtual environment
python -m venv .env_borg

# Activate virtual environment
# On Windows:
.env_borg\Scripts\activate
# On macOS/Linux:
source .env_borg/bin/activate

# Install in development mode
pip install -e .[dev]

# Run development server
python run.py

Docker Configuration

Volume Mapping Strategy

All volumes must be mounted under /mnt/ to be visible in the application:

volumes:
  - ./data:/app/data                              # Persistent application data (required)
  - /path/to/backup/sources:/mnt/backup/sources:ro # Source directories (read-only)
  - /path/to/borg/repos:/mnt/repos                # Repository storage (read-write)
  - /additional/source:/mnt/additional:ro         # Additional sources as needed
  - /another/repo/location:/mnt/alt-repos         # Additional repositories as needed

Volume Guidelines:

Mount as many volumes as necessary for all backup sources and repository locations
Source directories can be mounted read-only (:ro) for safety
Repository directories need read-write access for Borg operations
Each volume can be mapped to any convenient path under /mnt/ inside the container
Supports distributed setups where repositories and sources are in different locations

Required Docker Parameters

For full functionality, the following Docker parameters are required:

--cap-add SYS_ADMIN: Required for FUSE filesystem mounting to enable the archive browser feature
--device /dev/fuse: Provides access to the FUSE device for archive filesystem mounting

FUSE Requirements:

Enables the interactive archive browser feature
Allows real-time exploration of backup archives without extraction
Supports direct file downloads from mounted archive filesystems
Without FUSE support, archive browsing will be disabled

Installing Dependencies

BorgBackup Installation

Ubuntu/Debian:

sudo apt update
sudo apt install borgbackup

CentOS/RHEL/Fedora:

sudo dnf install borgbackup

macOS:

brew install borgbackup

Windows:

Download from the BorgBackup releases page

Note

For Windows users who want full functionality including FUSE-based archive browsing, we recommend using WSL2. See Windows WSL Setup Guide for a complete setup guide.

Rclone Installation (Optional)

For cloud synchronization features:

Linux:

curl https://rclone.org/install.sh | sudo bash

macOS:

brew install rclone

Windows:

Download from the Rclone downloads page

First-Time Setup

After installation, access the web interface:

Open http://localhost:8000 in your browser
Create your first admin account on the initial setup page
Configure your first repository in the dashboard

The application will create a local SQLite database and generate encryption keys automatically.

Configuration Options

Environment Variables

Borgitory can be configured using environment variables:

BORGITORY_HOST: Server host address (default: 0.0.0.0)
BORGITORY_PORT: Server port (default: 8000)
BORGITORY_DATA_DIR: Data directory path (default: ./data)
BORGITORY_DEBUG: Enable debug mode (default: false)

Command Line Options

When using the PyPI installation:

borgitory serve --help

Options:
  --host TEXT      Host to bind to [default: 0.0.0.0]
  --port INTEGER   Port to bind to [default: 8000]
  --reload         Enable auto-reload for development
  --log-level TEXT Log level [default: info]
  --help           Show this message and exit

Verification

To verify your installation is working correctly:

Check the web interface: Navigate to http://localhost:8000
Verify BorgBackup: The dashboard will show if BorgBackup is available
Test repository creation: Try adding a test repository
Check logs: Monitor the application logs for any errors

Docker verification:

# Check container status
docker-compose ps

# View logs
docker-compose logs -f borgitory

PyPI verification:

# Check if borgitory command is available
borgitory --help

# Verify BorgBackup is available
borg --version

Troubleshooting Installation

Common Issues

Python Version Issues

Ensure you’re using Python 3.11 or higher:

python --version

BorgBackup Not Found

Verify BorgBackup is installed and in PATH:

borg --version
which borg

Docker Permission Issues

Ensure your user has permission to run Docker commands:

sudo usermod -aG docker $USER
# Log out and back in

FUSE Mount Issues

On some systems, you may need to install FUSE utilities:

# Ubuntu/Debian
sudo apt install fuse3

# CentOS/RHEL/Fedora
sudo dnf install fuse3

For more troubleshooting information, see the Troubleshooting Guide guide.

Next Steps

After successful installation:

Read the Features Overview overview to understand Borgitory’s capabilities
Follow the Usage Guide guide for step-by-step instructions
Explore How-To Guides guides for specific tasks
Configure Adding New Cloud Providers for cloud synchronization