ScorvBot

Discord bot for the Grim Dawn server. Written using Python 3, Discord.py, and Redis for storage.

Table of Contents

• Contributing
  • Local Setup
    • Install Python
    • Create a virtual Python environment
    • Install the bot's dependencies
    • Environment variables
  • Running the bot
    • Installing Docker & Docker Compose
    • Running the bot with Docker Compose
  • Notes on Redis

Contributing

Local Setup

Follow these steps to get the bot running on your machine.

Install Python

Download and install Python 3.12. Either download Python from the downloads page, or install Python using a package manager like asdf (any OS), winget (Windows), Homebrew (macOS), or your Linux distribution's package manager.

Create a virtual Python environment

It is highly recommended that you user a virtual environment for each project. This will keep your Python version and packages separate from project to project.

There are a few different virtual environment tools like venv, pyenv, and Conda. venv ships with Python 3. To create a virtual environment with venv run this command in the project root directory:

python3 -m venv .venv

This will create a .venv folder in the project root directory. To activate the virutal environment run this command:

source .venv/bin/activate

(Optional) Install direnv to automatically activate your virtual environment when you change directories. Once direnv is installed create a .envrc file in the project root directory:

echo -e 'source .venv/bin/activate\n' > .envrc

Then run the following command to enable direnv:

direnv allow

Now direnv will automatically activate your virtual enviornment when you change to the project directory, and disable it when you leave.

Install the bot's dependencies

A requirements.txt file is included with all of the packages you need to use the bot. To install the dependencies run this command at the project root directory:

pip install -r requirements.txt

Additionally, we use Black for formatting and pre-commit to ensure that formatting is done automatically on push. Install these packages using this command:

pip install black pre-commit

Then activate pre-commit (only necessary on first-time install) to install the git hooks by running this command at the project root directory:

pre-commit install

Environment variables

Some environment variables are required for the bot to function:

DISCORD_TOKEN='<Discord app token>'
TEST_GUILD='<ID of your test server>'
TAG_APPROVAL_ID='<ID of the #channel where tag approval messages will go>'
ENV='dev'

Follow this guide for setting up a Discord app and getting a token.

You can either define these manually in your environment, or create a .env file at the project root directory. If you are running the bot without Docker Compose, then you will want to install python-dotenv.

Additionally, if you are not using Docker Compose, you will need to provide the following variables for the connection to Redis:

REDIS_HOST_NAME=''
REDIS_HOST_PORT=''

Running the bot

The recommended way to build and run the bot is with Docker & Docker Compose. The included Dockerfile and compose.yaml have all the necessary configuration for building the bot and running the Redis.

Installing Docker & Docker Compose

For Windows and Mac you will need to install Docker Desktop. For Linux, follow these instructions.

Running the bot with Docker Compose

Docker Compose will handle building & running the bot, runing the Redis, and sets up the connection to the Redis. To start the bot with Compose run this command in the project root directory:

docker compose up

If you make changes to the source code or container configuration you will need to rebuild the images when you run compose. To do that run this command in the project root directory:

docker compose up --build

The Docker compose also creates a couple of volumes on your host machine. The first is the logs/ folder. This folder will be populated with the bot's logs if ENV='prod'. The second is the redis/data/ folder. This will contain all of the Redis persistence data so stored values are not lost between runs.

Notes on Redis

By default, Redis is an in-memory data store. With the default configuration the data would be lost between runs. A configuration file is included at redis/redis.conf that enables both RDB and AOF persistence, and is loaded automatically when run with the included compose.yaml. You can read more about Redis persistence here.