pyTorrent/scripts/INSTALL.md

pyTorrent stack installer

This document describes the one-command installer for installing rTorrent + pyTorrent from a clean server.

The installer is split into two layers:

• scripts/install_stack.sh - public bootstrap script intended to be downloaded directly from Git.
• scripts/stack_installers/ - OS-specific installers and helper scripts used by the bootstrap script.

Quick install

Run as root or through sudo:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh | sudo bash

The bootstrap script downloads the current pyTorrent repository, detects the operating system family, and runs the matching installer:

• Debian / Ubuntu: scripts/stack_installers/install_stack_debian_ubuntu.sh
• RHEL-compatible systems: scripts/stack_installers/install_stack_rhel.sh

Supported RHEL-compatible systems include RHEL, Rocky Linux, AlmaLinux, CentOS Stream, and Fedora-like systems where dnf or yum is available.

What gets installed

Default installation includes:

• rTorrent v0.16.11
• libtorrent v0.16.11
• minimal rTorrent build without c-ares/custom curl
• rTorrent system user: rtorrent
• rTorrent SCGI endpoint: scgi://127.0.0.1:5000
• rTorrent incoming BitTorrent port: 51300
• pyTorrent application directory: /opt/pytorrent
• pyTorrent HTTP port: 8090
• pyTorrent profile configured through the HTTP API

The installer creates or updates a pyTorrent rTorrent profile through API after both services are installed.

Recommended usage with overrides

Environment variables must be passed to the sudo bash process.

Example:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh \
  | sudo PYTORRENT_PORT=8091 RTORRENT_SCGI_PORT=5001 bash

Another example with a custom profile name:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh \
  | sudo PYTORRENT_PROFILE_NAME="Local rTorrent" PYTORRENT_PORT=8090 bash

Bootstrap parameters

These variables are used by scripts/install_stack.sh.

Variable	Default	Description
PYTORRENT_REPO_URL	https://git.linuxiarz.pl/gru/pyTorrent	Git repository base URL.
PYTORRENT_REPO_BRANCH	master	Branch used to download the repository archive.
PYTORRENT_ARCHIVE_URL	derived from repo URL and branch	Custom repository archive URL.
PYTORRENT_BOOTSTRAP_DIR	/tmp/pytorrent-stack-installer	Temporary directory used by the bootstrap script.
PYTORRENT_KEEP_BOOTSTRAP_DIR	0	Set to 1 to keep the temporary directory after installation.

Example using a different branch:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh \
  | sudo PYTORRENT_REPO_BRANCH=develop bash

rTorrent parameters

These variables are used by both stack installers.

Variable	Default	Description
RTORRENT_USER	rtorrent	System user used to run rTorrent.
RTORRENT_HOME	/home/${RTORRENT_USER}	Home directory for the rTorrent user.
RTORRENT_BASE_DIR	/opt/rtorrent_build	Build and install directory for xmlrpc-c, libtorrent and rTorrent.
RTORRENT_SCGI_PORT	5000	Local SCGI port for rTorrent XMLRPC/SCGI.
RTORRENT_TORRENT_PORT	51300	Incoming BitTorrent listen port.
RTORRENT_REF	v0.16.11	rTorrent Git tag, branch, or commit.
LIBTORRENT_REF	v0.16.11	libtorrent Git tag, branch, or commit.

Example:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh \
  | sudo RTORRENT_USER=rtorrent RTORRENT_SCGI_PORT=5001 RTORRENT_TORRENT_PORT=51400 bash

pyTorrent parameters

Variable	Default	Description
PYTORRENT_APP_DIR	/opt/pytorrent	pyTorrent installation directory.
PYTORRENT_PORT	8090	HTTP port used by the pyTorrent service.
PYTORRENT_BASE_URL	http://127.0.0.1:${PYTORRENT_PORT}	Base URL used by the API configurator.
PYTORRENT_PROFILE_NAME	Local rTorrent	Name of the rTorrent profile created in pyTorrent.
PYTORRENT_API_TOKEN	empty	Bearer token used when pyTorrent API authentication is enabled.
PYTORRENT_SERVICE_NAME	pytorrent	systemd service name for pyTorrent.
PYTORRENT_RTORRENT_SCGI_URL	scgi://127.0.0.1:${RTORRENT_SCGI_PORT}	SCGI URL saved in the pyTorrent rTorrent profile.

Example with API token:

curl -fsSL https://git.linuxiarz.pl/gru/pyTorrent/raw/branch/master/scripts/install_stack.sh \
  | sudo PYTORRENT_API_TOKEN="pt_xxx" bash

API configurator parameters

The API configurator can be run manually:

/opt/pytorrent/venv/bin/python /opt/pytorrent/scripts/stack_installers/configure_pytorrent_api.py \
  --base-url http://127.0.0.1:8090 \
  --profile-name "Local rTorrent" \
  --scgi-url scgi://127.0.0.1:5000

CLI options:

Option	Environment variable	Default	Description
--base-url	PYTORRENT_BASE_URL	http://127.0.0.1:8090	pyTorrent API base URL.
--api-token	PYTORRENT_API_TOKEN	empty	Bearer token for authenticated API calls.
--profile-name	PYTORRENT_RTORRENT_PROFILE_NAME	Local rTorrent	Profile name to create or update.
--scgi-url	PYTORRENT_RTORRENT_SCGI_URL	scgi://127.0.0.1:5000	rTorrent SCGI URL.
--timeout	PYTORRENT_RTORRENT_TIMEOUT	10	rTorrent request timeout in seconds.
--wait	PYTORRENT_API_WAIT_SECONDS	90	Time to wait for the pyTorrent API to become available.
--remote	PYTORRENT_RTORRENT_REMOTE	0	Mark profile as remote. Accepts 1, true, yes, on.

Local installation without bootstrap

If the repository is already cloned:

Debian / Ubuntu:

sudo bash scripts/stack_installers/install_stack_debian_ubuntu.sh

RHEL-compatible systems:

sudo bash scripts/stack_installers/install_stack_rhel.sh

Installed service hints

Check services:

systemctl status pytorrent
systemctl status rtorrent@rtorrent.service

Check logs:

tail -f /data/logs/app.log /data/logs/error.log
journalctl -u pytorrent -f
journalctl -u rtorrent@rtorrent.service -f

Notes

• The default rTorrent build is intentionally minimal.
• c-ares and custom curl are not enabled by the stack installer defaults.
• The rTorrent installer overwrites the generated .rtorrent.rc because the stack installer passes --force-config.
• pyTorrent is configured through the HTTP API after the service starts.
• If API authentication is enabled before profile configuration, pass PYTORRENT_API_TOKEN.

Build logs and troubleshooting

The stack installer writes quiet build output to /var/log/pytorrent-installer by default. Override it with:

PYTORRENT_STACK_LOG_DIR=/tmp/pytorrent-build-logs

For full command output during rTorrent/libtorrent compilation, run with:

PYTORRENT_DEBUG_INSTALL=1

On RHEL-compatible systems the installer also tries to enable CRB/PowerTools and installs libcurl-devel, redhat-rpm-config, patch, diffutils, findutils, file, and libstdc++-devel, because minimal Alma/Rocky images often do not include enough build tooling.