Skip to content

Latest commit

 

History

History
447 lines (308 loc) · 9.83 KB

install-windows.md

File metadata and controls

447 lines (308 loc) · 9.83 KB

Windows Installation Guide

Complete installation guide for Torrent VPN Stack on Windows 10/11.

Prerequisites

Required Software

  1. Docker Desktop for Windows

  2. Windows Subsystem for Linux (WSL 2) - Recommended

  3. Git for Windows (if not using WSL)

  4. PowerShell 5.1+ (included in Windows 10/11)

    • For backup automation scripts

System Requirements

  • OS: Windows 10 version 2004+ or Windows 11
  • RAM: 8 GB minimum, 16 GB recommended
  • Disk: 20 GB free space minimum
  • CPU: 64-bit processor with virtualization support (Intel VT-x or AMD-V)

Installation Methods

Method 1: Using WSL 2 (Recommended)

WSL 2 provides the best Linux compatibility and performance.

1. Install and Configure WSL

# Install WSL with Ubuntu (default distribution)
wsl --install

# Restart your computer when prompted

# After restart, set up Ubuntu username/password
# Then update packages
wsl -e sudo apt update && sudo apt upgrade -y

2. Install Docker Desktop

  1. Download and install Docker Desktop
  2. During installation, ensure "Use WSL 2 instead of Hyper-V" is checked
  3. After installation, open Docker Desktop settings:
    • General → Enable "Use the WSL 2 based engine"
    • Resources → WSL Integration → Enable your Ubuntu distribution

3. Clone Repository (in WSL)

# Open WSL terminal
wsl

# Clone repository
cd ~
git clone https://github.com/ddmoney420/torrent-vpn-stack.git
cd torrent-vpn-stack

4. Run Setup Wizard

# Make scripts executable
chmod +x scripts/*.sh

# Run interactive setup
./scripts/setup.sh

Follow the prompts to configure your VPN provider and preferences.

5. Start the Stack

# Basic stack (VPN + qBittorrent)
docker compose up -d

# With port forwarding (ProtonVPN Plus, PIA)
docker compose --profile port-forwarding up -d

# With monitoring
docker compose --profile monitoring up -d

# All features
docker compose --profile port-forwarding --profile monitoring up -d

6. Verify VPN Connection

./scripts/verify-vpn.sh

Method 2: Using Git Bash (Without WSL)

If you prefer not to use WSL, you can run scripts via Git Bash.

1. Install Prerequisites

  1. Install Docker Desktop (Hyper-V backend)
  2. Install Git for Windows

2. Clone Repository

# Open Git Bash
cd ~
git clone https://github.com/ddmoney420/torrent-vpn-stack.git
cd torrent-vpn-stack

3. Run Setup

./scripts/setup.sh

4. Start Stack (Git Bash)

docker compose up -d

Note: Some scripts may have limited functionality in Git Bash compared to WSL.

Backup Automation (Windows-Specific)

Automated Backups with Task Scheduler

The Windows version uses Task Scheduler for automated backups.

Setup Automated Backups

Option 1: Using WSL (Recommended)

# Run in PowerShell as Administrator
cd $HOME\torrent-vpn-stack
.\scripts\setup-backup-automation.ps1 -Shell WSL

Option 2: Using Git Bash

# Run in PowerShell as Administrator
cd $HOME\torrent-vpn-stack
.\scripts\setup-backup-automation.ps1 -Shell GitBash

Customize Backup Schedule

# Backup at 2 AM instead of 3 AM
.\scripts\setup-backup-automation.ps1 -BackupHour 2

# Keep backups for 14 days
.\scripts\setup-backup-automation.ps1 -RetentionDays 14

# Custom backup location
.\scripts\setup-backup-automation.ps1 -BackupDir "D:\Backups\torrent-vpn-stack"

Manage Scheduled Task

# View task status
Get-ScheduledTask -TaskName "TorrentVPNStackBackup"

# Run backup manually
Start-ScheduledTask -TaskName "TorrentVPNStackBackup"

# Disable backups
.\scripts\remove-backup-automation.ps1

Manual Backups

# In WSL or Git Bash
./scripts/backup.sh

Accessing Services

From Windows Host

All services are accessible from Windows at localhost:

Network Configuration

Windows users may need to allow Docker through the Windows Firewall:

  1. Open Windows Defender Firewall → Advanced Settings
  2. Inbound Rules → New Rule
  3. Allow port 8080 (qBittorrent)
  4. Repeat for other services if needed

File Paths

WSL File System

  • WSL Ubuntu files (from Windows): \\wsl$\Ubuntu\home\<username>\torrent-vpn-stack
  • Windows C: drive (from WSL): /mnt/c/
  • Downloads: Configure in .env using WSL paths (/home/<username>/Downloads/torrents)

Windows Paths

If using Git Bash without WSL:

  • Project: C:\Users\<username>\torrent-vpn-stack
  • Downloads: C:\Users\<username>\Downloads\torrents

Troubleshooting

Docker Desktop Not Starting

Error: "Docker Desktop starting..."

Solutions:

  1. Enable WSL 2:

    wsl --set-default-version 2

  2. Enable virtualization in BIOS:

    • Restart → Enter BIOS (usually F2, Del, or F12)
    • Enable Intel VT-x or AMD-V

  3. Enable Hyper-V (if not using WSL 2):

    # Run as Administrator
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

WSL "File not found" Errors

Error: $'\r': command not found or similar

Solution: Convert line endings to Unix format:

# In WSL
sudo apt install dos2unix
dos2unix scripts/*.sh

Permission Denied Errors

Error: Permission denied when running scripts

Solution: Make scripts executable:

chmod +x scripts/*.sh

VPN Connection Fails

Error: Gluetun container constantly restarting

Solutions:

  1. Check VPN credentials in .env
  2. Verify VPN provider configuration (see Provider Comparison)
  3. Check Gluetun logs: 
    docker logs gluetun

Cannot Access qBittorrent WebUI

Error: localhost:8080 not accessible

Solutions:

  1. Verify container is running:

    docker ps

  2. Check LOCAL_SUBNET in .env matches your network:

    # From WSL
ip addr show eth0 | grep inet

  3. Restart Docker containers:

    docker compose down
docker compose up -d

  4. "Unauthorized" error instead of login page:

    # Stop qBittorrent
docker compose stop qbittorrent

# Disable host header validation
docker run --rm -v torrent-vpn-stack_qbittorrent-config:/config alpine sh -c "echo 'WebUI\HostHeaderValidation=false' >> /config/qBittorrent/qBittorrent.conf"

# Restart
docker compose start qbittorrent

Downloads Path Error

Error: Volume mount fails or "path not found"

Solution: Use Windows-style paths in .env:

# Use forward slashes, not backslashes:
DOWNLOADS_PATH=C:/Users/yourusername/Downloads/torrents

# NOT this:
DOWNLOADS_PATH=C:\Users\yourusername\Downloads\torrents

Also ensure the drive is shared in Docker Desktop:

  • Settings → Resources → File Sharing
  • Add C:\Users\yourusername\Downloads if not listed

Port Forwarding Not Working

Error: No forwarded port assigned

Solutions:

  1. Verify your VPN provider supports port forwarding:

    • ✅ ProtonVPN Plus, PIA
    • ❌ Mullvad (discontinued July 2023), NordVPN, Surfshark, ExpressVPN

  2. Enable port forwarding profile:

    docker compose --profile port-forwarding up -d

  3. For ProtonVPN, ensure VPN_PORT_FORWARDING_PROVIDER=protonvpn in .env

Performance Tuning

Docker Desktop Resource Allocation

  1. Open Docker Desktop → Settings → Resources
  2. Recommended settings:
    • CPUs: 4 cores (minimum 2)
    • Memory: 4 GB (minimum 2 GB)
    • Disk: 20 GB+

WSL 2 Performance

Create/edit %USERPROFILE%\.wslconfig:

[wsl2]
memory=4GB
processors=4
swap=2GB
localhostForwarding=true

Restart WSL:

wsl --shutdown

See Performance Tuning Guide for more optimizations.

Uninstallation

Remove Stack

# Stop and remove containers
docker compose down

# Remove volumes (WARNING: deletes all data)
docker volume rm torrent-vpn-stack_gluetun-config torrent-vpn-stack_qbittorrent-config

Remove Scheduled Backup Task

# Run in PowerShell as Administrator
.\scripts\remove-backup-automation.ps1

Uninstall Docker Desktop

  1. Uninstall via Settings → Apps → Docker Desktop
  2. Optionally remove WSL: 
    wsl --unregister Ubuntu

Next Steps

Additional Resources