Stay up to date with Torrust!

Watch our GitHub repos

How To Setup The Dev Env

Published on 11/07/2023
Updated on 24/04/2024
7 min read
How To Setup The Dev Env


Before explaining how to setup the development environment, it’s important to understand how the Torrust Index works. The Torrust Index is composed of multiple services, each one with its own codebase and repository. The services are:

  • A BitTorrent Tracker, which is responsible for tracking the torrents and providing the peers to the clients.
  • The Index, which is a REST API that provides the data to the frontend.
  • And the Index GUI, which is a webapp that displays the data to the user.
Torrust Architecture

You do not need to setup all services to contribute to the Torrust Index, but in this article we will explain how to setup the full development environment, which includes all services. Sometimes you might want to contribute with a full feature that involves multiple services, so it’s useful to have the full development environment setup.

Setting up the development environment requires to setup the three main services.

First, we need to create the folder (in this example, a temp folder) where we will store the repositories of our services.

mkdir -p ~/Tmp/torrust
cd ~/Tmp/torrust
This guide used bash commands and it has been tested on Ubuntu Ubuntu 23.04. You should not encounter any problem if you are using a different Linux distribution, but there are some reported issues with Windows compilation for the Tracker. The installation scripts are very simple, so you can easily adapt them to your system or run the commands manually.

Common Dependencies

If you are using SQLite3 as database driver for the Tracker or the Backend, you will need to install the following dependency:

sudo apt-get install libsqlite3-dev

Set Up the Torrust Tracker

This tutorial is tested with this Rust version:

  • rustc 1.72.0-nightly (839e9a6e1 2023-07-02)

Since we are using the openssl crate with the vendored feature, enabled, you will need to install the following dependencies:

sudo apt-get install pkg-config libssl-dev make

Now, we will build the tracker and create the storage folders where persistent data like databases will be stored:

git clone \
  && cd torrust-tracker \
  && cargo build --release \
  && mkdir -p ./storage/tracker/lib/database \
  && mkdir -p ./storage/tracker/lib/tls

You can run the Tracker with the following command:

cargo run
NOTICE: You do not need to change the default values for development.

After running the Tracker with cargo run you should see the following output:

       Finished `dev` profile [optimized + debuginfo] target(s) in 0.10s
     Running `target/debug/torrust-tracker`
Loading default configuration file: `./share/default/config/tracker.development.sqlite3.toml` ...
2024-04-22T16:24:23.241961292+01:00 [torrust_tracker::bootstrap::logging][INFO] logging initialized.
2024-04-22T16:24:23.242613018+01:00 [UDP TRACKER][INFO] Starting on: udp://
2024-04-22T16:24:23.242649758+01:00 [torrust_tracker::bootstrap::jobs][INFO] TLS not enabled
2024-04-22T16:24:23.242670038+01:00 [HTTP TRACKER][INFO] Starting on:
2024-04-22T16:24:23.242744307+01:00 [HTTP TRACKER][INFO] Started on:
2024-04-22T16:24:23.242753177+01:00 [torrust_tracker::bootstrap::jobs][INFO] TLS not enabled
2024-04-22T16:24:23.242834227+01:00 [API][INFO] Starting on
2024-04-22T16:24:23.242848277+01:00 [API][INFO] Started on
2024-04-22T16:24:23.242864747+01:00 [HEALTH CHECK API][INFO] Starting on:
2024-04-22T16:24:23.242897537+01:00 [HEALTH CHECK API][INFO] Started on:
IMPORTANT: Every time you change the configuration you need to restart the service.

By default, if you don’t specify any Config.toml file, the application will use this:

Loading default configuration file: `./share/default/config/tracker.development.sqlite3.toml` ...

You can’t change that file because it’s a template included in the repo. If you want to set your custom configuration, you can either:

  1. Use a different path for the config file.
  2. Inject the configuration with an environment variable.

Custom config file

First, copy the template file to the storage folder:

cp share/default/config/tracker.development.sqlite3.toml storage/tracker/etc/tracker.toml

Then, you can change any value and finally run the tracker with:

TORRUST_TRACKER_PATH_CONFIG="./storage/tracker/etc/tracker.toml" cargo run

That would give you this output:

TORRUST_TRACKER_PATH_CONFIG="./storage/tracker/etc/tracker.toml" cargo run
    Finished `dev` profile [optimized + debuginfo] target(s) in 0.09s
     Running `target/debug/torrust-tracker`
Loading configuration file: `./storage/tracker/etc/tracker.toml` ...
2024-04-22T16:32:57.035457075+01:00 [torrust_tracker::bootstrap::logging][INFO] logging initialized.
2024-04-22T16:32:57.036048971+01:00 [UDP TRACKER][INFO] Starting on: udp://
2024-04-22T16:32:57.036079671+01:00 [torrust_tracker::bootstrap::jobs][INFO] TLS not enabled
2024-04-22T16:32:57.036117731+01:00 [HTTP TRACKER][INFO] Starting on:
2024-04-22T16:32:57.036209310+01:00 [HTTP TRACKER][INFO] Started on:
2024-04-22T16:32:57.036218550+01:00 [torrust_tracker::bootstrap::jobs][INFO] TLS not enabled
2024-04-22T16:32:57.036280190+01:00 [API][INFO] Starting on
2024-04-22T16:32:57.036283750+01:00 [API][INFO] Started on
2024-04-22T16:32:57.036301960+01:00 [HEALTH CHECK API][INFO] Starting on:
2024-04-22T16:32:57.036385919+01:00 [HEALTH CHECK API][INFO] Started on:

Inject the configuration with an environment variable

You can also inject the configuration with:

TORRUST_TRACKER_CONFIG=`cat share/default/config/tracker.development.sqlite3.toml` cargo run
NOTICE: We load the whole file into the env var. This is not useful for development, but it's a different way to inject the configuration. It's used when running the tracker with docker.

The response should be like this:

	"torrents": 0,
	"seeders": 0,
	"completed": 0,
	"leechers": 0,
	"tcp4_connections_handled": 0,
	"tcp4_announces_handled": 0,
	"tcp4_scrapes_handled": 0,
	"tcp6_connections_handled": 0,
	"tcp6_announces_handled": 0,
	"tcp6_scrapes_handled": 0,
	"udp4_connections_handled": 0,
	"udp4_announces_handled": 0,
	"udp4_scrapes_handled": 0,
	"udp6_connections_handled": 0,
	"udp6_announces_handled": 0,
	"udp6_scrapes_handled": 0

For more details about the Torrust Tracker, check the Tracker documentation.

Set Up the Torrust Index

This tutorial has been tested with this Rust version:

  • rustc 1.77.1-nightly (839e9a6e1 2024-03-26)

To run the tests you will also need to install a command line tool to handle torrent files called imdl. You can install it with the following command:

cargo install imdl

You will also need to install a tool for database migrations if you are going to make changes to the database schema. We are using SQLx. You can install it with the following command:

cargo install sqlx-cli

We will now clone the torrust-index repository:

  git clone \
  cd torrust-index \
  && cargo build --release \
  && mkdir -p ./storage/index/lib/database \
  && mkdir -p ./storage/index/lib/tls

You can run the Torrust Index with the following commands:


As you can see we are using the environment variable TORRUST_IDX_BACK_CORS_PERMISSIVE to enable a permissive CORS policy. The default port for the Backend is 3001 and for the web server serving the frontend application is 3000. Since they are different ports, we need to tell the backend to allow request from a different port so that the frontend can make request to the API. To know more about CORS, check the Mozilla CORS documentation.

After running the Backend with cargo run you should see the following output:

2023-07-11T11:54:17.553899587+01:00 [torrust_index::web::api::server][INFO] Starting API server with net config: ...
2023-07-11T11:54:17.553946897+01:00 [torrust_index::web::api::server][INFO] API server listening on

You should be able to load the API entrypoint on

Screenshot of Torrust Backend API entrypoint response

For more details about the Torrust Index Backend, check the Index Backend documentation.

Set Up the Torrust Index GUI

At the time of writing, the Index GUI requires:

  • Node: ^v20.12.2

The frontend is a Nuxt application.

The last repository we need to clone is the torrust-index-gui repository . Remember to install Node.js and we need to be in the torrust folder to clone the repository.

git clone \
  && cd torrust-index-gui.git \
  && npm install \
  && npm run dev

You should see the following output:

Screenshot of Torrust Index Frontend running from the terminal

Go to http://localhost:3000/torrents and you should see the torrent list page page:

Screenshot of torrent list page on the browser

For more details about the Torrust Index GUI, check the Index GUI documentation.

Application Setup

There are some public pages like the torrent list or torrent details pages. But there are some pages that require authentication like the admin pages or the pages for uploading or editing torrents.

To access those pages you need to create an account. You can do it from the signup page:


The first user created will be the admin user.

Development tools

We found some tools very useful to develop the Torrust Tracker and Index. We hope you find them useful too.


As you can see, the Torrust Tracker and Index are very easy to set up. We hope you find this guide useful. You might have problems:

  • Setting up some of the projects on Windows. We are working on it.
  • Or with some missing system dependencies.

If you have any questions or issues please open an issue on the corresponding repository:

We very welcome any contributions to the project!