geas-bot/README.md

Geas Server Bot

This is a bot I wrote to manage the Discord server for Geas, the Edinburgh University Table-Top Role-Playing Society, during our move to an on-line format. The bot is designed to create and manage channels and roles for gaming groups in order to replicate our in-person pitch events on a Discord space as far as possible. The bot is written in Python, and was the first Python coding project I wrote, so it has a special place in my heart. The first version I am committing to the repository is version 2.1, and I previously handled the version control manually, so migrating old versions to Git would be a pain.

Bot Setup

The Bot is dockerised and uses docker-compose for deployment, so it is fairly straightforward to set up. Clone the repository, install Docker and Docker Compose, navigate to the root directory (that contains the docker-compose.yml file), and use docker-compose up -d to set up and run the bot. The bot uses two containers that are networked internally:

1. A python app that runs the bot, and
2. A MongoDB database that stores the bot's data for persistence.

The database is not exposed externally to the network, and can only be accessed by the Bot in the network of containers.

The bot authenticates using an API key, which I have kept private in a .env file that I have not uploaded to the repository. In order to set up your own instance of the bot, you will need to create two copies of the .env file, one in the root directory and one in the app folder, and enter the respective values for the API keys for the Geas Server Bot and the Test Bot.

You will also need this database to set up a username and password for the MongoDB database. The specific username and password don't matter as the bot refers back to the environment variable when authenticating.

The following is the template for the .env file, with the variable names as are referenced in the bot's code: .env file:

BOT_TOKEN=
TEST_TOKEN=
MONGO_INITDB_ROOT_USERNAME=
MONGO_INITDB_ROOT_PASSWORD=
BOT_VERSION=2.1.1

The correct API keys need to be entered in the environment variables in the .env file, and for a copy of this file to be placed in the root and the app directories.

Also create a new folder in the root directory called db. This is to ensure there is persistence of data when the bot is updated.

N.B.: When the bot is first run, it is configured to log in as the Test Bot, and not the main Geas Server Bot, as a safety measure. To change this, navigate to the last line of the file bot.py and change the line:

client.run(os.getenv('TEST_TOKEN'))

to

client.run(os.getenv('BOT_TOKEN'))

in order for to authenticate as the correct bot.

Bot Structure

The bot is divided into the following files:

app folder
|   bot.py -- bot core functionality and code entrypoint
|   Dockerfile -- Docker instructions on building the bot
|   requirements.txt -- Dependencies to be installed
----cogs -- Individual modules for specific features
       GameManagement.py -- adding or kicking players
       HelpNotifier.py -- notifications for Help channel
       MembershipRestriction.py -- restrictions unverified users
       MembershipVerification.py -- membership verification system
       PitchMenu.py -- automation for generating menus for game pitches

Many of the specific features, such as the bot's prefix, the roles it recognises as Committee, the channels it recognises as the Help or Membership Verification channels, are all hard-coded into the Bot. This is because the bot was only ever supposed to be used on one server, so did not need the flexibility of adapting to multiple channels. In the future, if I ever tinker with this in the future, I might try and add flexibility in the channels and roles it defines for its various functions.

I might also, in future incarnations, not use a database. It was fun to learn how to use a database, but it is overkill.

Bot Commands

A full list of bot commands can be retrieved using the -help command in the bot, and this might be an easier way of retrieving the commands than having a separate copy in the documentation.