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
Documentation
Tutorial
Guide
Development
Setup
How To Setup The Dev Env

Table of Contents

Introduction

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.

terminal
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:

terminal
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:

terminal
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:

terminal
git clone https://github.com/torrust/torrust-tracker.git \
  && 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:

terminal
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:

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://0.0.0.0:6969
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: http://0.0.0.0:7070
2024-04-22T16:24:23.242744307+01:00 [HTTP TRACKER][INFO] Started on: http://0.0.0.0:7070
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 http://127.0.0.1:1212
2024-04-22T16:24:23.242848277+01:00 [API][INFO] Started on http://127.0.0.1:1212
2024-04-22T16:24:23.242864747+01:00 [HEALTH CHECK API][INFO] Starting on: http://127.0.0.1:1313
2024-04-22T16:24:23.242897537+01:00 [HEALTH CHECK API][INFO] Started on: http://127.0.0.1:1313
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:

output
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:

terminal
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:

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

That would give you this output:

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://0.0.0.0:6969
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: http://0.0.0.0:7070
2024-04-22T16:32:57.036209310+01:00 [HTTP TRACKER][INFO] Started on: http://0.0.0.0:7070
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 http://127.0.0.1:1212
2024-04-22T16:32:57.036283750+01:00 [API][INFO] Started on http://127.0.0.1:1212
2024-04-22T16:32:57.036301960+01:00 [HEALTH CHECK API][INFO] Starting on: http://127.0.0.1:1313
2024-04-22T16:32:57.036385919+01:00 [HEALTH CHECK API][INFO] Started on: http://127.0.0.1:1313

Inject the configuration with an environment variable

You can also inject the configuration with:

terminal
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:

json
{
	"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:

terminal
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:

terminal
cargo install sqlx-cli

We will now clone the torrust-index repository:

terminal
  git clone https://github.com/torrust/torrust-index.git \
  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:

terminal
TORRUST_INDEX_API_CORS_PERMISSIVE=true cargo run

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:

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

You should be able to load the API entrypoint on http://0.0.0.0:3001/

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.

terminal
git clone https://github.com/torrust/torrust-index-gui.git \
  && 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:

http://localhost:3000/signup

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.

Conclusion

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!

Related Posts

How To Run A Local Demo

Published on 11/07/2023
3 min read

You can easily run the Torrust Index demo on your computer easily with Git and Docker.

Demo
Tutorial

Containerizing Rust Applications

Published on 09/11/2023
26 min read

Torrust services (Tracker and Index) support docker, we want to ensure that contributors understand our containerfile and we also want to share good practices for containerizing Rust applications.

Documentation
Docker

Deploying Torrust To Production

Published on 20/12/2023
21 min read

Dive into our step-by-step tutorial on deploying a BitTorrent Index and Tracker, written in Rust, on a Digital Ocean droplet. From initial server setup to advanced configurations, this guide is designed for both non-developers and tech-savvy users, ensuring a seamless, production-ready deployment.

Tutorial
Deployment