Introduction

This is the documentation for Rodhaj, the modern ModMail bot for the transprogrammer server.

Software Requirements

Before you get started, please ensure you have the following installed:

If you are using Linux, the following dependencies will need to be installed:

For a debian-based system, you can install them with the following command:

$ apt install libffi-dev libnacl-dev python3-dev libssl-dev

Caution

Rodhaj uses uvloop on Linux and MacOS and winloop on Windows. Replacing the default event loop with these Cython-based implementations provides a significant performance boost. Although Rodhaj is natively developed and deployed on Linux, Windows support should work but is not tested.

Setup

Rodhaj only supports Python 3.9 or higher

Important

  • Ensure that you are in the root of the repo throughout this process and have the database running

  • Rodhaj also supports Poetry, but for simplicity, virtualenvs are demonstrated here instead

  1. Fork and clone the repo

  2. Create an virtualenv

python3 -m venv rodhaj

  1. Activate the virtualenv

# Linux/MacOS
$ source rodhaj/bin/activate

# Windows
$ rodhaj/Scripts/activate.bat

  1. Install dependencies and set up pre-commit hooks

pip install -r requirements-dev.txt \
&& pre-commit install

  1. Copy over the config-example.yml template over to the bot directory. Modify the values as appropriate.

cp config-example.yml bot/config.yml

  1. Run the SQL migrations

python3 bot/migrations.py init

  1. In order to demonstrate, you can run the bot to test everything out

python3 bot/launcher.py

Database

The following SQL queries can be used to create the user and database:

CREATE ROLE rodhaj WITH LOGIN PASSWORD 'somepass';
CREATE DATABASE rodhaj OWNER rodhaj;

Note

This step is largely skipped if you are using Docker to run the PostgreSQL server. If you decide not to use Docker, you will need to manually create the database as shown below

Using Docker

If you decide to use Docker to run the local PostgreSQL server, then a pre-built Docker Compose file is provided. Setup instructions are as follows:

  1. Copy docker/example.env to .env within the docker folder. Modify as appropriate.

cp docker/example.env docker/.env

  1. Run the following command to start the PostgreSQL server

docker compose -f docker/docker-compose.dev.yml up -d

Extensions

Rodhaj includes the following extensions as noted:

Rodhaj currently includes an Prometheus exporter. This exporter is intended to be used in production environments, where metrics surrounding ticket usage, bot health, and others would provide valuable insight. This exporter can be enabled by setting the rodhaj.prometheus.enabled key within config.yml.

Note

Prometheus client libraries are listed within the requirements.txt file. By default, these libraries should be installed, but disabling the exporter will not affect the usage of these libraries.