Windows WSL Setup Guide

This guide provides step-by-step instructions for setting up Borgitory on a fresh Windows installation using WSL2 (Windows Subsystem for Linux).

Prerequisites

Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
Administrator access to your Windows machine
Internet connection

Step 1: Enable WSL2

Refer to the Microsoft documentation for more details: https://learn.microsoft.com/en-us/windows/wsl/install

# Enable WSL feature
wsl --install

Step 2: Install Ubuntu Linux Distribution

Install Ubuntu

# List available distributions
wsl --list --online

# Install Ubuntu (replace with your preferred version)
wsl --install -d Ubuntu-22.04

Initial Ubuntu Setup

Launch Ubuntu from Start Menu
Create a new user account when prompted
Set a password for your user account

Step 3: Update Ubuntu and Install Dependencies

Update Package Lists

sudo apt update && sudo apt upgrade -y

Install Python 3.11+

# Install Python 3.11 and pip
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.11 python3.11-pip python3.11-venv -y

# Set Python 3.11 as default (optional)
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Install BorgBackup

# Install BorgBackup
sudo apt install borgbackup -y

# Verify installation
borg --version

Install Rclone (Optional - for cloud sync)

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

# Verify installation
rclone version

Install FUSE Support (Optional - for archive browsing)

# Install FUSE3 development libraries
sudo apt install fuse3 libfuse3-dev -y

# Install Python FUSE bindings
python3.11 -m pip install pyfuse3

Step 4: Install Borgitory

Install Borgitory via pip

# Install Borgitory
python3.11 -m pip install borgitory

# Verify installation
borgitory --help

Create Directory Structure

# Create directories for Borgitory data
mkdir -p ~/borgitory/{data,repos,sources}

# Set appropriate permissions
chmod 755 ~/borgitory/{data,repos,sources}

Step 5: Configure Windows-WSL Integration

Access Windows Files from WSL

Windows drives are automatically mounted under /mnt/:

C: drive → /mnt/c/
D: drive → /mnt/d/

Create Symbolic Links for Easy Access

# Link to common Windows directories
ln -s /mnt/c/Users/$USER/Documents ~/Documents-Windows
ln -s /mnt/c/Users/$USER/Desktop ~/Desktop-Windows

# Example: Link backup sources
ln -s /mnt/c/Users/$USER/Documents ~/borgitory/sources/documents

Step 6: Start Borgitory

Run Borgitory Server

# Start Borgitory with default settings
borgitory serve

# Or with custom host/port
borgitory serve --host 0.0.0.0 --port 8000

Access Web Interface

Open your web browser
Navigate to http://localhost:8000
Create your first admin account on initial setup

Step 7: Optional Configurations

Create Windows Shortcut

Create a batch file to easily start Borgitory:

Create start-borgitory.bat on your Windows desktop:

@echo off
wsl -d Ubuntu-22.04 -e bash -c "cd ~ && borgitory serve --host 0.0.0.0 --port 8000"

Double-click the batch file to start Borgitory

Auto-start WSL on Windows Boot (Optional)

Open Task Scheduler
Create Basic Task
Set trigger to “When the computer starts”
Set action to start program: wsl.exe
Add arguments: -d Ubuntu-22.04

Troubleshooting

Common Issues

WSL2 not starting: Ensure virtualization is enabled in BIOS
Permission denied errors: Check file permissions and ownership
Network issues: WSL2 uses NAT networking by default
FUSE mount failures: Ensure FUSE is properly installed and user has permissions

Useful Commands

# Check WSL version
wsl --list --verbose

# Restart WSL
wsl --shutdown
wsl

# Check if services are running
systemctl status fuse3  # if using systemd

Getting Help

WSL Documentation
BorgBackup Documentation
Rclone Documentation
Troubleshooting Guide - Borgitory troubleshooting guide

Security Considerations

File Permissions: Be careful with file permissions between Windows and WSL
Network Access: Consider firewall rules if accessing from other machines
Backup Encryption: Always use encrypted BorgBackup repositories
WSL Security: Keep WSL and Ubuntu updated regularly

Note

This setup allows you to run Borgitory on Windows by leveraging WSL2 for Linux compatibility. All backup operations will run within the WSL2 environment while providing a web interface accessible from Windows.

Tip

For production use, consider the Docker Deployment Guide which provides better isolation and easier management, even on Windows systems with WSL2.