Porla

Porla is a powerful BitTorrent client with high performance and low memory usage. It is designed for headless operations on servers and seedboxes and can easily manage tens of thousands of torrents.

The focus of Porla is to provide a BitTorrent client that is fast, correct and extensible.

Features

User-defined workflows.
Support for both BitTorrent v1 and v2.
Embedded query language to find torrents. Fast.
HTTP API with JWT auth.
Modern web UI.

Workflows

Workflows can be used to automate and integrate Porla with all types of applications and services, such as Discord and ntfy.sh. They are inspired by GitHub Actions.

The Porla query language (PQL)

To make it easy to navigate and filter a large amount of torrents Porla has a simple, embedded query language named PQL.

With PQL you can easily find torrents matching specific criterias.

Getting started

Download the latest release and put it somewhere safe. Then, run it. By default, Porla bind the web UI to localhost:1337. On first use you will be prompted to set up a user account.

porla

To show all options available, suffix with --help.

porla --help

For example, you can run porla with an in-memory SQLite database by passing --db=:memory:.

porla --db=:memory:

Configuration

You can configure Porla in three ways - environment variables, command line arguments, and a TOML config file.

Command line arguments have the highest priority, then the config file, and lastly the environment variables. The app will, however, run without any applied configuration and use sensible defaults instead.

Environment variables and command line args

PORLA_CONFIG_FILE or --config-file - path to a TOML config file with additional configuration.
PORLA_DB or --db - path a file (which does not need to exist) that porla will use to store its state.
PORLA_HTTP_AUTH_DISABLED_YES_REALLY - set to true to disable HTTP JWT authentication (not recommended).
PORLA_HTTP_BASE_PATH or --http-base-path - set to a path where the HTTP parts of Porla will be served. Defaults to /.
PORLA_HTTP_HOST or --http-host - set to an IP address which to bind the HTTP server. Defaults to 127.0.0.1.
PORLA_HTTP_METRICS_ENABLED or --http-metrics-enabled - set to true/false to enable or disable the metrics endpoint. Defaults to true.
PORLA_HTTP_PORT or --http-port - set to the port to use for the HTTP server. Defaults to 1337.
PORLA_LOG_LEVEL or --log-level - the minimum log level to use. Valid values are trace, debug, info, warning, error, fatal. Defaults to info.
PORLA_SESSION_SETTINGS_BASE or --session-settings-base - the libtorrent settings base to use for session settings. Valid values are default, min_memory_usage, high_performance_seed. Defaults to default.
PORLA_STATE_DIR or --state-dir - a path to a directory where Porla will store its state.
PORLA_TIMER_DHT_STATS or --timer-dht-stats - the interval in milliseconds to push DHT stats. Defaults to 5000.
PORLA_TIMER_SESSION_STATS or --timer-session-stats - the interval in milliseconds to push session stats. Defaults to 5000.
PORLA_TIMER_TORRENT_UPDATES or --timer-torrent-updates - the interval in milliseconds to push torrent state updates. Defaults to 1000.
PORLA_WORKFLOW_DIR or --workflow-dir - the path to where Porla will load user workflows from.

Refer to the official documentation for information on how to set up the TOML configuration.

Development

Various bits and pieces of information regarding development.

Building

We try to make sure Porla is easy to get running directly from the Git repository. Dependencies are managed with vcpkg.

git clone --recursive https://github.com/porla/porla
cd porla
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build

You can also remove -G Ninja if you don't have Ninja available.

Updating the pre-built Dockerfile build environment

To reduce build times, we use a pre-built Docker layer with all the vcpkg dependencies already built. This needs to be updated whenever we update the vcpkg submodule or radically change the project structure.

Requires push access to the Porla container registry.

docker build -t porla-build-env -f Dockerfile.build-env .
docker tag porla-build-env ghcr.io/porla/build-env:<timestamp>
docker push ghcr.io/porla/build-env:<timestamp>

Generating ANTLR4 grammar source files

This is only needed when PorlaQueryLang.g4 is modified.

wget https://www.antlr.org/download/antlr-4.11.1-complete.jar
pushd src/query
java -jar ../../antlr-4.11.1-complete.jar -Dlanguage=Cpp -visitor -no-listener -o _aux PorlaQueryLang.g4
popd

samip5 / porla