Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/porla/porla

A high performance BitTorrent client for servers and seedboxes.
https://github.com/porla/porla

automation bittorrent seedbox server torrent

Last synced: 2 days ago
JSON representation

A high performance BitTorrent client for servers and seedboxes.

Awesome Lists containing this project

README 

        


  


  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



 * Based on libtorrent with support for both BitTorrent v1 and v2.

 * Lua API for writing [plugins and workflows](https://porla.org/plugins/getting_started).

 * Supports multiple, distinct sessions with different settings.

 * Embedded query language to find torrents. Fast.

 * [HTTP API](https://porla.org/api/auth) with JWT auth.

 * Modern web UI.



#### Plugins and workflows



The Lua API can be used to automate and integrate Porla with all types of

applications and services, such as Discord and [ntfy.sh](https://ntfy.sh).



#### Multiple sessions



You can easily set up multiple sessions to separate your public torrents from

your private torrents, for example. Each session binds to its own network

device and port pair, and can have custom rate limits, queueing rules, etc.



#### 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.



```shell

porla

```



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



```shell

porla --help

```



For example, you can run `porla` with an in-memory SQLite database by passing

`--db=:memory:`.



```shell

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](https://porla.org/configuration/) 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](https://github.com/microsoft/vcpkg).



```shell

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_.



```shell

docker build -t porla-build-env -f Dockerfile.build-env .

docker tag porla-build-env ghcr.io/porla/build-env:

docker push ghcr.io/porla/build-env:

```



### Generating ANTLR4 grammar source files



This is only needed when `PorlaQueryLang.g4` is modified.



```shell

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

```