Deploying Deluge

Deluge is a lightweight, free, and cross-platform BitTorrent client that prioritizes functionality and user experience. Unlike heavyweight alternatives that consume significant system resources, Deluge is built with efficiency in mind using the libtorrent library and GTK+ interface toolkit. The client follows a client-server architecture, meaning the core daemon can run on a remote server while you control it through various interfaces—web UI, desktop applications, or command-line tools. This separation makes Deluge ideal for running on headless servers where you want torrent downloads to happen 24/7 without tying up your local machine.

What sets Deluge apart is its extensive plugin ecosystem and flexibility. Out of the box, you get essential features like bandwidth scheduling, label management, and connection limits. Through plugins, you can add RSS feed monitoring, automatic file extraction, integration with media servers, notification systems, and much more. The web interface provides full control over your torrents from any browser, making it perfect for remote management. Whether you’re downloading Linux distributions, managing media libraries, or handling large file transfers, Deluge offers the tools to do it efficiently while maintaining a small resource footprint.

Why Deploy Deluge on Klutch.sh?

Deploying Deluge on Klutch.sh offers several advantages for hosting your BitTorrent client:

Automatic Docker Detection: Klutch.sh recognizes your Dockerfile and handles containerization without manual configuration
Persistent Storage: Built-in volume management ensures your downloads, configuration, and torrent state persist across deployments
HTTPS Web Access: Secure access to Deluge’s web interface with automatic SSL certificates
High Bandwidth: Dedicated infrastructure for handling continuous download/upload traffic
Always-On Operation: Keep torrents seeding 24/7 without running your local machine
Port Management: Easy configuration for BitTorrent ports and web interface access
Environment Isolation: Run Deluge in a containerized environment separate from other services

Prerequisites

Before deploying Deluge to Klutch.sh, ensure you have:

A Klutch.sh account (sign up here)
A GitHub account with a repository for your Deluge deployment
Basic understanding of Docker and containerization
Familiarity with BitTorrent protocol and terminology
Understanding of port forwarding and networking concepts
Git installed on your local development machine
Basic knowledge of Linux file permissions

Understanding Deluge Architecture

Deluge follows a modular client-server architecture designed for flexible deployment:

Core Components

Deluge Daemon (deluged)

The daemon is the core engine that handles all BitTorrent operations. It runs as a background service managing torrent downloads, uploads, peer connections, and disk I/O. The daemon uses libtorrent-rasterbar under the hood, which provides efficient implementation of the BitTorrent protocol including support for magnet links, DHT, peer exchange, and encryption. The daemon can run independently on a server and accepts connections from multiple clients simultaneously, making it perfect for remote management scenarios.

Key daemon responsibilities:

Managing torrent state and metadata
Connecting to peers and trackers
Handling file I/O operations
Enforcing bandwidth limits and scheduling
Processing plugin logic
Maintaining session state

Deluge Web Interface (deluge-web)

The web interface provides browser-based access to your Deluge daemon. Built with Python and the Twisted framework, it serves a modern single-page application that communicates with the daemon via RPC calls. The interface offers nearly all functionality available in the desktop client, including torrent management, file browsing, plugin configuration, and real-time statistics. Authentication protects access, and the interface can connect to local or remote daemons.

The web UI provides:

Torrent queue management (pause, resume, remove)
File priority selection
Real-time transfer speeds and progress
Bandwidth limit adjustments
Plugin management interface
Connection statistics and peer information
Label and category organization

Plugin System

Deluge’s plugin architecture extends functionality without bloating the core. Plugins are Python modules that hook into daemon events and can modify behavior, add UI elements, or integrate with external services. Popular plugins include:

Execute: Run scripts or commands when torrent state changes (on completion, on add, etc.) Label: Organize torrents with labels and apply settings per label AutoAdd: Monitor folders and automatically add .torrent files Extractor: Automatically extract compressed archives on completion Notifications: Send email, Pushbullet, or desktop notifications Scheduler: Schedule bandwidth limits by time of day YaRSS2: Monitor RSS feeds and automatically download matching torrents

Plugins integrate seamlessly with the web interface, adding their own configuration panels and features.

libtorrent Backend

Deluge uses libtorrent-rasterbar, a C++ library implementing the BitTorrent protocol. This library handles:

Peer wire protocol implementation
Tracker communication (HTTP, UDP, scrape)
DHT (Distributed Hash Table) for trackerless torrents
Peer exchange and local service discovery
Protocol encryption and obfuscation
Disk caching and I/O optimization
Rate limiting and queue management

The library is highly optimized and provides excellent performance even with hundreds of active torrents.

Configuration System

Deluge stores configuration in several files:

core.conf: Main daemon configuration (ports, bandwidth, paths)
web.conf: Web interface settings (port, authentication)
state/*: Torrent state files and resume data
plugins/*.egg: Plugin packages
ssl/: SSL certificates for secure connections

Configuration files use JSON format and can be edited directly or through the interface.

Data Flow

User adds torrent via web interface, magnet link, or file upload
Web interface sends RPC command to daemon
Daemon parses torrent metadata and creates torrent object
libtorrent connects to tracker to get peer list
Daemon negotiates connections with peers
Data chunks downloaded and verified against hash checks
Completed pieces written to disk at configured location
Daemon continues seeding to maintain share ratio
Plugins react to torrent state changes
Web interface polls daemon for status updates

Storage Architecture

Deluge requires several persistent storage locations:

Downloads Directory: Where completed torrent files are saved. This should be your largest volume since it stores all downloaded content. Deluge can move completed downloads to a separate location or leave them in place.

Incomplete Downloads: Optional separate location for in-progress downloads. Using a separate directory prevents media scanners from detecting incomplete files.

Torrent Files: Storage for .torrent files. Deluge can auto-add torrents from this directory.

Watch Directory: Optional directory that Deluge monitors. Any .torrent files placed here are automatically added to the queue.

State Directory: Contains torrent resume data, fast-resume information, and session state. Critical for preserving progress across restarts.

All directories need proper permissions for the Deluge daemon user to read and write.

Network Architecture

Deluge uses several network components:

Incoming Port (BitTorrent): Default 58846 or random port. Incoming peer connections arrive on this port. Opening this port improves connectivity and download speeds.

Outgoing Connections: Deluge initiates outgoing connections to peers on various ports. No special configuration needed.

Web Interface Port: Default 8112. Serves the web UI over HTTP. Should be behind HTTPS proxy in production.

Daemon Port: Default 58846. RPC interface for client-daemon communication. Should not be exposed to internet.

DHT Port: UDP port for DHT protocol. Usually same as incoming port.

Proper port configuration significantly impacts performance and connectivity.

Storage Requirements

Deluge itself is lightweight, but storage needs depend on download usage:

Application: 100-500MB for Deluge and dependencies
Configuration: 10-50MB for state files and plugins
Downloads: Size depends entirely on your usage (provision generously)
Torrents Directory: 1-10MB per thousand torrents

A typical deployment might allocate:

50GB-500GB for downloads
10GB for incomplete downloads
1GB for configuration and state

Installation and Setup

Let’s walk through setting up Deluge for deployment on Klutch.sh.

Step 1: Create the Project Structure

First, create a new directory for your Deluge deployment:

mkdir deluge-deployment
cd deluge-deployment
git init

Step 2: Create the Dockerfile

Create a Dockerfile in the root directory:

FROM ubuntu:22.04

# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive \
    DELUGE_VERSION=2.1.1 \
    DELUGE_WEB_PORT=8112 \
    DELUGE_DAEMON_PORT=58846 \
    PUID=1000 \
    PGID=1000

# Install dependencies
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-libtorrent \
    python3-setuptools \
    python3-wheel \
    python3-twisted \
    python3-openssl \
    python3-rencode \
    gettext \
    intltool \
    geoip-database \
    ca-certificates \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Deluge
RUN pip3 install --no-cache-dir \
    deluge==${DELUGE_VERSION} \
    deluge-web==${DELUGE_VERSION}

# Create deluge user
RUN groupadd -g ${PGID} deluge && \
    useradd -u ${PUID} -g ${PGID} -m -s /bin/bash deluge

# Create necessary directories
RUN mkdir -p /config /downloads /watch /incomplete && \
    chown -R deluge:deluge /config /downloads /watch /incomplete

# Copy configuration files
COPY --chown=deluge:deluge config/ /config/

# Copy startup script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

# Switch to deluge user
USER deluge

# Set working directory
WORKDIR /config

# Expose ports
EXPOSE 8112 58846 58946 58946/udp

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8112 || exit 1

# Start Deluge
ENTRYPOINT ["/entrypoint.sh"]

Step 3: Create Configuration Files

Create config/core.conf:

{
  "file": 2,
  "format": 1
}{
  "add_paused": false,
  "allow_remote": true,
  "auto_managed": true,
  "cache_expiry": 60,
  "cache_size": 512,
  "compact_allocation": false,
  "copy_torrent_file": true,
  "daemon_port": 58846,
  "del_copy_torrent_file": false,
  "dht": true,
  "download_location": "/downloads",
  "download_location_paths_list": [],
  "enabled_plugins": [],
  "enc_in_policy": 1,
  "enc_level": 2,
  "enc_out_policy": 1,
  "geoip_db_location": "/usr/share/GeoIP/GeoIP.dat",
  "ignore_limits_on_local_network": true,
  "info_sent": 0.0,
  "listen_interface": "",
  "listen_ports": [58846, 58946],
  "listen_random_port": null,
  "listen_reuse_port": true,
  "listen_use_sys_port": false,
  "lsd": true,
  "max_active_downloading": 3,
  "max_active_limit": 8,
  "max_active_seeding": 5,
  "max_connections_global": 200,
  "max_connections_per_second": 20,
  "max_connections_per_torrent": -1,
  "max_download_speed": -1.0,
  "max_download_speed_per_torrent": -1,
  "max_half_open_connections": 50,
  "max_upload_slots_global": 4,
  "max_upload_slots_per_torrent": -1,
  "max_upload_speed": -1.0,
  "max_upload_speed_per_torrent": -1,
  "move_completed": false,
  "move_completed_path": "/downloads",
  "natpmp": true,
  "new_release_check": false,
  "outgoing_interface": "",
  "outgoing_ports": [0, 0],
  "path_chooser_accelerator_string": "Tab",
  "path_chooser_auto_complete_enabled": true,
  "path_chooser_max_popup_rows": 20,
  "path_chooser_show_chooser_button_on_localhost": true,
  "path_chooser_show_hidden_files": false,
  "peer_tos": "0x00",
  "plugins_location": "/config/plugins",
  "pre_allocate_storage": false,
  "prioritize_first_last_pieces": false,
  "proxy": {
    "anonymous_mode": false,
    "force_proxy": false,
    "hostname": "",
    "password": "",
    "port": 8080,
    "proxy_hostnames": true,
    "proxy_peer_connections": true,
    "proxy_tracker_connections": true,
    "type": 0,
    "username": ""
  },
  "queue_new_to_top": false,
  "random_outgoing_ports": true,
  "random_port": true,
  "rate_limit_ip_overhead": true,
  "remove_seed_at_ratio": false,
  "seed_time_limit": 180,
  "seed_time_ratio_limit": 7.0,
  "send_info": false,
  "sequential_download": false,
  "share_ratio_limit": 2.0,
  "shared": false,
  "stop_seed_at_ratio": false,
  "stop_seed_ratio": 2.0,
  "super_seeding": false,
  "torrentfiles_location": "/config/torrents",
  "upnp": true,
  "utpex": true
}

Create config/web.conf:

{
  "file": 2,
  "format": 1
}{
  "base": "/",
  "cert": "ssl/daemon.cert",
  "default_daemon": "127.0.0.1:58846",
  "enabled_plugins": [],
  "https": false,
  "interface": "0.0.0.0",
  "language": "",
  "pkey": "ssl/daemon.pkey",
  "port": 8112,
  "pwd_salt": "c26ab3bbd8b137f99cd83c2c1c0963bcc1a35cad",
  "pwd_sha1": "2ce1a410bcdcc53064129b6d950f2e9fee4edc1e",
  "session_timeout": 3600,
  "sessions": {},
  "show_sidebar": true,
  "show_timestamp": true,
  "sidebar_multiple_filters": true,
  "sidebar_show_zero": false,
  "theme": "gray"
}

Step 4: Create Authentication File

Create config/auth:

localclient:2ce1a410bcdcc53064129b6d950f2e9fee4edc1e:10
admin:2ce1a410bcdcc53064129b6d950f2e9fee4edc1e:10

This creates two users (localclient and admin) with password “deluge” and full permissions (level 10).

Step 5: Create Entrypoint Script

Create entrypoint.sh:

#!/bin/bash
set -e

# Set default values if not provided
PUID=${PUID:-1000}
PGID=${PGID:-1000}
DELUGE_WEB_PORT=${DELUGE_WEB_PORT:-8112}
DELUGE_DAEMON_PORT=${DELUGE_DAEMON_PORT:-58846}

# Create directories if they don't exist
mkdir -p /config /downloads /watch /incomplete

# Update user/group IDs if needed
if [ "$PUID" != "1000" ] || [ "$PGID" != "1000" ]; then
    echo "Updating UID:GID to $PUID:$PGID"
    groupmod -o -g "$PGID" deluge
    usermod -o -u "$PUID" deluge
fi

# Set permissions
chown -R deluge:deluge /config /downloads /watch /incomplete

# Generate default password if auth file doesn't exist
if [ ! -f /config/auth ]; then
    echo "Generating default authentication file..."
    cat > /config/auth << EOF
localclient:2ce1a410bcdcc53064129b6d950f2e9fee4edc1e:10
admin:2ce1a410bcdcc53064129b6d950f2e9fee4edc1e:10
EOF
    chown deluge:deluge /config/auth
fi

# Start deluged in background
echo "Starting Deluge daemon..."
/usr/local/bin/deluged -d -c /config -L info

# Wait for daemon to start
echo "Waiting for daemon to start..."
sleep 5

# Start deluge-web
echo "Starting Deluge web interface on port $DELUGE_WEB_PORT..."
exec /usr/local/bin/deluge-web -c /config -L info --do-not-daemonize

Step 6: Create Environment Configuration

Create .env.example:

# User/Group Configuration
PUID=1000
PGID=1000

# Port Configuration
DELUGE_WEB_PORT=8112
DELUGE_DAEMON_PORT=58846

# Download Paths
DOWNLOAD_PATH=/downloads
INCOMPLETE_PATH=/incomplete
WATCH_PATH=/watch
CONFIG_PATH=/config

# Bandwidth Limits (in KB/s, -1 for unlimited)
MAX_DOWNLOAD_SPEED=-1
MAX_UPLOAD_SPEED=-1

# Connection Limits
MAX_CONNECTIONS_GLOBAL=200
MAX_CONNECTIONS_PER_TORRENT=-1
MAX_UPLOAD_SLOTS_GLOBAL=4

# Queue Settings
MAX_ACTIVE_DOWNLOADING=3
MAX_ACTIVE_SEEDING=5
MAX_ACTIVE_LIMIT=8

# Seeding Settings
STOP_SEED_AT_RATIO=false
STOP_SEED_RATIO=2.0
SHARE_RATIO_LIMIT=2.0
REMOVE_SEED_AT_RATIO=false

# Network Settings
DHT_ENABLED=true
LSD_ENABLED=true
UPNP_ENABLED=true
NATPMP_ENABLED=true

# Security
RANDOM_PORT=true
ENCRYPTION_LEVEL=2

Step 7: Create Startup Helper Script

Create scripts/setup-plugins.sh:

#!/bin/bash
# Helper script to install Deluge plugins

PLUGINS_DIR="/config/plugins"
mkdir -p "$PLUGINS_DIR"

echo "Plugin installer for Deluge"
echo "Place .egg plugin files in $PLUGINS_DIR"
echo ""
echo "Popular plugins:"
echo "- Label: Organize torrents with labels"
echo "- Execute: Run scripts on torrent events"
echo "- AutoAdd: Auto-add torrents from folders"
echo "- Extractor: Auto-extract archives"
echo ""
echo "Download plugins from: https://dev.deluge-torrent.org/wiki/Plugins"

Step 8: Create Docker Ignore File

Create .dockerignore:

.git
.gitignore
*.md
README.md
.env
.DS_Store
Thumbs.db
node_modules/
downloads/
incomplete/
watch/
*.log
.vscode
.idea

Step 9: Create Configuration Directory Structure

mkdir -p config/plugins config/ssl config/state config/torrents

Step 10: Create Documentation

Create README.md:

# Deluge BitTorrent Client

This repository contains a Deluge deployment configured for Klutch.sh.

## Features

- Lightweight BitTorrent client
- Full-featured web interface
- Plugin support
- Bandwidth scheduling
- Label management
- RSS feed monitoring (with plugin)
- Automatic extraction (with plugin)
- Remote management

## Default Credentials

- Username: `admin`
- Password: `deluge`

**Change the password immediately after first login!**

## Configuration

Edit `.env` file to customize:
- Port settings
- Bandwidth limits
- Download paths
- Connection limits
- Seeding ratios

## Plugins

Install plugins by placing .egg files in `/config/plugins/` and enabling them through the web interface.

Popular plugins:
- Label
- Execute
- AutoAdd
- Extractor
- Notifications
- Scheduler

## Deployment

This application is configured to deploy on Klutch.sh with automatic Docker detection.

## Changing Password

Via web interface:
1. Preferences → Interface → Password
2. Enter new password twice
3. Click Apply

Via command line:
```bash
deluge-console "config -s max_upload_speed 500"

### Step 11: Initialize Git Repository

```bash
git add .
git commit -m "Initial Deluge setup for Klutch.sh deployment"
git branch -M master
git remote add origin https://github.com/yourusername/deluge-deployment.git
git push -u origin master

Deploying to Klutch.sh

Now that your Deluge application is configured, let’s deploy it to Klutch.sh.

Log in to Klutch.sh
Navigate to klutch.sh/app and sign in with your GitHub account.
Create a New Project
Click “New Project” and select “Import from GitHub”. Choose the repository containing your Deluge deployment.
Configure Build Settings
Klutch.sh will automatically detect the Dockerfile in your repository. The platform will use this for building your container.
Configure Traffic Settings
Select “HTTP” as the traffic type. Deluge’s web interface runs on port 8112, and Klutch.sh will route HTTPS traffic to this port.
Set Environment Variables
In the project settings, add the following environment variables:
- PUID: 1000 (User ID for file permissions)
- PGID: 1000 (Group ID for file permissions)
- DELUGE_WEB_PORT: 8112
- DELUGE_DAEMON_PORT: 58846
Optional bandwidth configuration:
- MAX_DOWNLOAD_SPEED: -1 (unlimited, or set KB/s limit)
- MAX_UPLOAD_SPEED: -1 (unlimited, or set KB/s limit)
Connection limits:
- MAX_CONNECTIONS_GLOBAL: 200
- MAX_ACTIVE_DOWNLOADING: 3
- MAX_ACTIVE_SEEDING: 5
Seeding configuration:
- STOP_SEED_AT_RATIO: false
- STOP_SEED_RATIO: 2.0
Configure Persistent Storage
Deluge requires persistent storage for downloads and configuration:
- Downloads Volume:
  - Mount path: /downloads
  - Size: 100GB (adjust based on your needs)
- Configuration Volume:
  - Mount path: /config
  - Size: 5GB
- Incomplete Downloads Volume:
  - Mount path: /incomplete
  - Size: 50GB
- Watch Directory Volume:
  - Mount path: /watch
  - Size: 1GB
These volumes ensure your downloads, torrent state, and configuration persist across deployments.
Deploy the Application
Click “Deploy” to start the build process. Klutch.sh will:
- Clone your repository
- Build the Docker image using your Dockerfile
- Install Deluge and dependencies
- Configure the daemon and web interface
- Deploy the container
- Provision an HTTPS endpoint
The build process typically takes 3-5 minutes.
Access Deluge Web Interface
Once deployment completes, access your Deluge instance at the provided URL (e.g., example-app.klutch.sh).

Login with default credentials:
- Username: admin
- Password: deluge
Important: Change the default password immediately after first login!
Configure Connection
On first login, you’ll be prompted to connect to the daemon:
- Host: 127.0.0.1
- Port: 58846
- Username: admin
- Password: deluge
Click “Connect” to establish the connection.

Getting Started with Deluge

Once your Deluge instance is deployed, here’s how to use it:

First-Time Setup

Change Default Password

Immediately change the default password:

Click “Preferences” (gear icon)
Navigate to “Interface” section
Enter new password in “Password” field
Re-enter password in “Confirm Password” field
Click “Apply” then “OK”

Configure Download Paths

Set up your download locations:

Preferences → Downloads
Set “Download to” path: /downloads
Optional: Enable “Move completed to” and set path: /downloads/completed
Set “Copy of .torrent files to” path: /config/torrents
Optional: Enable “Autoadd .torrent files from” and set path: /watch

Set Bandwidth Limits

Configure bandwidth usage:

Preferences → Bandwidth
Set “Maximum Download Speed”: Your desired limit in KB/s (0 for unlimited)
Set “Maximum Upload Speed”: Your desired limit in KB/s (0 for unlimited)
Set “Maximum Connections”: 200 (default, adjust based on your network)
Set “Maximum Upload Slots”: 4 (affects upload efficiency)

Adding Torrents

Via Magnet Link

magnet:?xt=urn:btih:HASH&dn=Name&tr=tracker_url

Click “Add Torrent” button (+ icon)
Select “URL” tab
Paste magnet link
Click “Add”

Via Torrent File

Click “Add Torrent” button
Select “File” tab
Click “Browse” and select .torrent file
Choose download location (optional)
Select files to download (optional)
Click “Add”

Via Web URL

Click “Add Torrent”
Select “URL” tab
Enter URL to .torrent file
Click “Add”

Via Watch Directory

Simply copy .torrent files to /watch directory. Deluge automatically detects and adds them.

# From outside the container
cp ubuntu-22.04.torrent /path/to/watch/

Managing Torrents

Torrent Controls

Right-click on any torrent for options:

Pause: Stop downloading/uploading
Resume: Continue downloading/uploading
Force Recheck: Verify downloaded data integrity
Update Tracker: Refresh peer list from tracker
Set Maximum Download/Upload Speed: Per-torrent bandwidth limits
Move Storage: Change download location
Remove Torrent: Delete from queue (optionally delete data)

Queue Management

Control download priority:

Queue Up/Down: Change torrent position in queue
Move to Top/Bottom: Priority adjustment
Preferences → Queue: Configure active torrent limits

File Selection

Choose which files to download:

Select torrent
Click “Files” tab
Check/uncheck individual files
Set priority: Low, Normal, High, or Do Not Download

Plugin Configuration

Installing Plugins

Deluge’s functionality extends through plugins. Popular options:

Label Plugin (Organize torrents)

Preferences → Plugins
Check “Label” to enable
Right-click torrents → Label → Add Label
Create labels: Movies, TV Shows, Music, etc.
Use labels to filter and organize downloads

Execute Plugin (Run scripts on events)

Enable “Execute” plugin
Preferences → Execute
Add commands for events:
- Torrent Added
- Torrent Complete
- Torrent Removed

Example: Send notification on completion

Event: Torrent Complete
Command: /scripts/notify.sh
Arguments: "$name" "$path"

AutoAdd Plugin (Monitor folders)

Enable “AutoAdd” plugin
Preferences → AutoAdd
Add watch folder: /watch
Configure options:
- Download location
- Label to apply
- Owner (for multi-user setups)

Extractor Plugin (Auto-extract archives)

Enable “Extractor” plugin
Preferences → Extractor
Configure:
- Extract path: Same as torrent or custom
- Auto-extract: ZIP, RAR, TAR files
- Create subfolder: Yes/No

Scheduler Plugin (Bandwidth scheduling)

Control bandwidth by time of day:

Enable “Scheduler” plugin
Preferences → Scheduler
Configure time blocks:
- Green: Full speed
- Yellow: Limited speed
- Red: Stop torrents

Example schedule:

9 AM - 5 PM: Limited (working hours)
5 PM - 9 AM: Full speed (off-hours)

Advanced Configuration

Connection Settings

Optimize peer connections:

Preferences → Network

Incoming Port: 58846 (or random)
- Use Random Ports: Check for privacy
- Test Active Port: Verify port forwarding

Connections Per Torrent: -1 (unlimited)
Upload Slots Per Torrent: 4

Encryption Settings

Protect traffic from inspection:

Preferences → Network → Encryption

Level: Full Stream
- Prefer encrypted connections
- Force encrypted connections (may reduce peers)

Cache Settings

Improve disk I/O performance:

Preferences → Cache

Cache Size: 512 MB (adjust based on RAM)
Cache Expiry: 60 seconds

Queue Settings

Manage active torrents:

Preferences → Queue

Total Active: 8
Total Active Downloading: 3
Total Active Seeding: 5

Check "Do not count slow torrents" to maximize active torrents

Proxy Configuration

Route traffic through proxy:

Preferences → Network → Proxy

Type: SOCKS5 (or HTTP)
Host: proxy.example.com
Port: 1080
Username/Password: If required

Check:
- Proxy hostnames
- Proxy peer connections
- Proxy tracker connections

Web API Usage

Deluge provides a JSON-RPC API for automation.

Authentication

# Login and get session cookie
curl -X POST https://example-app.klutch.sh/json \
  -H "Content-Type: application/json" \
  -d '{
    "method": "auth.login",
    "params": ["deluge"],
    "id": 1
  }' \
  -c cookies.txt

Get Torrent List

curl -X POST https://example-app.klutch.sh/json \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "method": "web.update_ui",
    "params": [
      ["name", "state", "progress", "download_payload_rate"],
      {}
    ],
    "id": 2
  }'

Add Torrent by Magnet

curl -X POST https://example-app.klutch.sh/json \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "method": "core.add_torrent_magnet",
    "params": [
      "magnet:?xt=urn:btih:HASH",
      {}
    ],
    "id": 3
  }'

Pause Torrent

curl -X POST https://example-app.klutch.sh/json \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "method": "core.pause_torrent",
    "params": [["TORRENT_HASH"]],
    "id": 4
  }'

Get Session Status

curl -X POST https://example-app.klutch.sh/json \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "method": "core.get_session_status",
    "params": [["payload_download_rate", "payload_upload_rate"]],
    "id": 5
  }'

Monitoring and Statistics

Dashboard Overview

The main interface displays:

Download/Upload speeds (real-time)
Number of active torrents
Total downloaded/uploaded data
Available disk space
Connection status

Detailed Statistics

Click on any torrent to view:

Progress percentage
Download/upload speeds
ETA (estimated time remaining)
Peers connected
Seeds available
Share ratio
Downloaded/uploaded amounts

Graphs

View historical bandwidth usage:

Preferences → Interface → Graphs
Enable bandwidth graphs
Graphs show:
- Download rate over time
- Upload rate over time
- Connections over time

Session Statistics

View overall statistics:

Total data downloaded (all time)
Total data uploaded (all time)
Overall share ratio
Active time

Advanced Configuration

Seeding Strategy

Configure optimal seeding behavior:

Ratio-Based Seeding

Stop seeding after reaching ratio:

Preferences → Queue

Stop seeding when share ratio reaches: 2.0
- Ensures fair sharing (2:1 ratio)
- Saves bandwidth after contributing

Remove torrent when: Ratio reached
- Automatically clean up completed torrents

Time-Based Seeding

Seed for specific duration:

Seed time ratio: 7.0
- Seeds for 7x the download time
- Good for fast connections

Seed time (minutes): 180
- Minimum seeding time regardless of ratio
- Ensures availability for slow torrents

Selective Seeding

Use labels to apply different rules:

Label: Movies
- Share ratio: 1.5
- Remove at ratio: Yes

Label: Linux ISOs
- Share ratio: 3.0
- Remove at ratio: No (seed forever)

Custom Scripts

Execute Plugin Scripts

Run custom actions on torrent events.

Completion Notification Script

Create /scripts/notify.sh:

#!/bin/bash
TORRENT_NAME="$1"
TORRENT_PATH="$2"

echo "Torrent completed: $TORRENT_NAME" >> /config/completed.log
echo "Location: $TORRENT_PATH" >> /config/completed.log
echo "Time: $(date)" >> /config/completed.log

Configure in Execute plugin:

Event: Torrent Complete
Command: /scripts/notify.sh
Arguments: $name $path

Auto-Organization Script

Create /scripts/organize.sh:

#!/bin/bash
TORRENT_NAME="$1"
TORRENT_PATH="$2"
TORRENT_LABEL="$3"

case "$TORRENT_LABEL" in
  "Movies")
    DEST="/downloads/Movies"
    ;;
  "TV")
    DEST="/downloads/TV"
    ;;
  "Music")
    DEST="/downloads/Music"
    ;;
  *)
    DEST="/downloads/Other"
    ;;
esac

mkdir -p "$DEST"
mv "$TORRENT_PATH" "$DEST/"
echo "Moved $TORRENT_NAME to $DEST" >> /config/organize.log

Bandwidth Scheduling

Create time-based bandwidth rules:

Work Hours Schedule

Monday-Friday 9 AM - 5 PM: Limited
- Download: 500 KB/s
- Upload: 100 KB/s
- Active downloads: 1

Monday-Friday 5 PM - 9 AM: Full Speed
- Download: Unlimited
- Upload: Unlimited
- Active downloads: 5

Weekends: Full Speed
- No restrictions

Implementation via Scheduler Plugin

Enable Scheduler plugin
Create hourly grid
Color code time blocks:
- Green: Full speed
- Yellow: Limited (configure limits)
- Red: Stop all transfers
Apply schedule

Port Forwarding

Improve connectivity with port forwarding:

Why Port Forward?

Better peer connectivity
Faster downloads
Ability to seed to more peers
Reduced reliance on DHT/PXE

Configuration

Choose static port in Deluge (e.g., 58846)
Disable random port: Preferences → Network → Use Random Ports = No
Configure router to forward port 58846 (TCP/UDP) to your server
Test port: Preferences → Network → Test Active Port

Multi-User Setup

Configure Deluge for multiple users:

Create Additional Users

Edit /config/auth:

admin:PASSWORD_HASH:10
user1:PASSWORD_HASH:5
user2:PASSWORD_HASH:5

Permission levels:

10: Full admin access
5: Normal user (can add/remove own torrents)
1: Read-only

Generate Password Hash

import hashlib
password = "your_password"
salt = "your_salt"
hash_value = hashlib.sha1((salt + password).encode()).hexdigest()
print(hash_value)

Label-Based Separation

Use labels to segregate downloads:

User1 → Label: user1_downloads
User2 → Label: user2_downloads

Configure AutoAdd per user:
- User1 watch: /watch/user1
- User2 watch: /watch/user2

RSS Feed Monitoring

Use YaRSS2 plugin for automatic downloads:

Setup YaRSS2

Download YaRSS2 plugin (.egg file)
Place in /config/plugins/
Enable in Preferences → Plugins
Configure feeds:
- Add feed URL
- Set update interval
- Create filters for auto-download

Example Filter

Feed: https://example.com/rss
Filter: TV Show Name
Quality: 1080p|720p
Download location: /downloads/TV
Label: TV

Production Best Practices

Follow these recommendations for running Deluge in production:

Security

Change Default Credentials

Never use default passwords:

Change web interface password
Change daemon password in auth file
Use strong passwords (16+ characters)
Different passwords for different environments

Limit Web Interface Access

Restrict access to trusted IPs only. Use Klutch.sh’s built-in HTTPS and consider additional authentication layers.

Enable Encryption

Force encrypted connections:

Preferences → Network → Encryption

Level: Full Stream
Encrypt entire stream: Yes

Disable UPnP/NAT-PMP in Production

Automatic port mapping can expose services:

Preferences → Network

UPnP: No
NAT-PMP: No

Manually configure port forwarding instead.

Regular Security Updates

Keep Deluge updated:

# Update to latest version
pip3 install --upgrade deluge deluge-web

Performance Optimization

Disk I/O Optimization

Reduce disk writes:

Preferences → Cache

Cache Size: 1024 MB (if RAM available)
Cache Expiry: 120 seconds

Preferences → Downloads
Pre-allocate disk space: No (for dynamic allocation)
Compact allocation: Yes (reduces fragmentation)

Connection Optimization

Tune for your network:

Fast connection (100+ Mbps):
- Max Connections Global: 500
- Max Connections Per Torrent: 100
- Max Upload Slots Global: 10

Slow connection (< 10 Mbps):
- Max Connections Global: 100
- Max Connections Per Torrent: 50
- Max Upload Slots Global: 4

Queue Optimization

Balance downloading vs seeding:

High download priority:
- Active Downloading: 5
- Active Seeding: 3
- Total Active: 8

High seed priority:
- Active Downloading: 2
- Active Seeding: 10
- Total Active: 12

Tracker Optimization

Improve peer discovery:

Preferences → Network

DHT: Enabled (trackerless torrents)
LSD: Enabled (local peer discovery)
PeX: Enabled (peer exchange)

Update tracker interval: 30 minutes

Storage Management

Download Organization

Implement folder structure:

/downloads/
├── completed/
│   ├── Movies/
│   ├── TV/
│   ├── Music/
│   └── Other/
├── incomplete/
└── watch/

Automatic Cleanup

Remove completed torrents automatically:

Preferences → Queue

Remove torrent when: Share ratio reached
Stop seeding when ratio reaches: 2.0

Or use Execute plugin with cleanup script

Monitor Disk Space

Set up alerts for low disk space:

#!/bin/bash
THRESHOLD=10  # 10GB
AVAILABLE=$(df -BG /downloads | tail -1 | awk '{print $4}' | sed 's/G//')

if [ "$AVAILABLE" -lt "$THRESHOLD" ]; then
    echo "Low disk space: ${AVAILABLE}GB remaining" >> /config/alerts.log
    # Send notification here
fi

Monitoring

Log Monitoring

Monitor Deluge logs for issues:

# View daemon logs
tail -f /config/deluged.log

# View web interface logs
tail -f /config/deluge-web.log

# Monitor for errors
grep -i error /config/deluged.log

Performance Monitoring

Track key metrics:

Download/upload speeds
Active connections
Disk usage
Memory usage
CPU usage

Automated Monitoring Script

#!/bin/bash
# Get session stats via API
STATS=$(curl -s -X POST http://localhost:8112/json \
  -H "Content-Type: application/json" \
  -b /config/cookies.txt \
  -d '{"method":"core.get_session_status","params":[[]],"id":1}')

# Log stats
echo "$(date): $STATS" >> /config/stats.log

# Alert on slow speeds or connection issues
# Add your alerting logic here

Backup Strategy

Configuration Backup

Regularly backup critical files:

#!/bin/bash
BACKUP_DIR="/backups/deluge-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Backup configuration
cp -r /config/*.conf "$BACKUP_DIR/"
cp /config/auth "$BACKUP_DIR/"

# Backup state
cp -r /config/state "$BACKUP_DIR/"

# Backup torrents
cp -r /config/torrents "$BACKUP_DIR/"

echo "Backup completed: $BACKUP_DIR"

Restore Procedure

#!/bin/bash
# Restore from backup

BACKUP_DIR="/backups/deluge-20250101"

# Stop Deluge
killall deluged deluge-web

# Restore files
cp "$BACKUP_DIR"/*.conf /config/
cp "$BACKUP_DIR"/auth /config/
cp -r "$BACKUP_DIR"/state /config/
cp -r "$BACKUP_DIR"/torrents /config/

# Restart Deluge
deluged -c /config
deluge-web -c /config

Troubleshooting

Connection Issues

Problem: Cannot access web interface

Solutions:

Verify container is running
Check port 8112 is exposed
Verify firewall allows traffic
Check logs: docker logs container_name
Test locally: curl http://localhost:8112

Problem: Cannot connect to daemon

Solutions:

Verify daemon is running: ps aux | grep deluged
Check daemon port (58846)
Verify auth credentials in /config/auth
Check daemon logs: /config/deluged.log
Restart daemon: killall deluged && deluged -c /config

Problem: Slow download speeds

Solutions:

Check port forwarding is configured
Test active port in Preferences → Network
Increase connection limits
Disable encryption (for testing)
Verify bandwidth limits not too restrictive
Check torrent has enough seeds
Try different torrents to isolate issue

Torrent Issues

Problem: Torrents stuck at 0%

Solutions:

Check torrent has seeds available
Verify DHT is enabled
Test with known-good torrent (Linux ISO)
Check download path has write permissions
Verify disk space available
Force recheck: Right-click → Force Recheck

Problem: Torrents not seeding

Solutions:

Check if reached stop seed ratio
Verify upload slots available
Check upload bandwidth limit
Ensure port forwarding configured
Verify torrent data still in place
Check queue settings allow seeding

Problem: Cannot add torrents

Solutions:

Check torrent file is valid
Verify download path exists and is writable
Check disk space available
Review logs for specific errors
Try different add method (file vs magnet)
Clear browser cache if using web upload

Permission Issues

Problem: Cannot write to download directory

Solutions:

Check directory permissions: ls -la /downloads
Verify PUID/PGID match volume ownership
Fix permissions: chown -R 1000:1000 /downloads
Check parent directory permissions
Verify no SELinux/AppArmor blocking access

Problem: Config files not persisting

Solutions:

Verify /config volume is mounted
Check volume permissions
Ensure config directory owned by deluge user
Check for read-only filesystem
Verify no disk space issues

Plugin Issues

Problem: Plugin not loading

Solutions:

Verify .egg file in /config/plugins/
Check plugin compatible with Deluge version
Review logs for plugin errors
Disable and re-enable plugin
Delete plugin and reinstall
Check Python dependencies available

Problem: Execute plugin not running scripts

Solutions:

Verify script has execute permissions: chmod +x script.sh
Check script path is correct
Test script manually
Review execute plugin logs
Verify script interpreter (#!/bin/bash) correct
Check script doesn’t require user input

Performance Issues

Problem: High CPU usage

Solutions:

Reduce active torrents
Lower connection limits
Increase cache size (if RAM available)
Disable unnecessary plugins
Check for disk I/O bottleneck
Reduce DHT load by limiting nodes

Problem: High memory usage

Solutions:

Reduce cache size
Limit active torrents
Disable memory-intensive plugins
Check for memory leaks (restart daemon)
Reduce connection limits

Problem: Slow web interface

Solutions:

Reduce update interval: Preferences → Interface
Limit torrent list display
Disable unnecessary columns
Clear browser cache
Check server load
Use thin/gtk+ client instead for large lists

Additional Resources

Conclusion

Deluge provides a lightweight, powerful solution for BitTorrent downloads with the flexibility to run anywhere. Its client-server architecture makes it ideal for remote deployments where you want downloads happening 24/7 without tying up your local machine. The extensive plugin ecosystem lets you customize behavior to match your exact needs, whether that’s RSS monitoring, automatic extraction, or custom scripting on torrent events.

Deploying Deluge on Klutch.sh gives you a dedicated, always-on BitTorrent client accessible from any browser. Your downloads continue uninterrupted, seeds remain active to maintain healthy share ratios, and you can manage everything remotely through the clean web interface. Whether you’re downloading Linux distributions, managing media libraries, or handling large file transfers, Deluge provides the tools to do it efficiently.

Start downloading with Deluge today and enjoy the freedom of a self-hosted BitTorrent client that’s always available when you need it.