Contributing to Bot

This guide will walk you through setting up and running the Python bot locally, and get you ready to contribute to it.

It focuses on the recommended setup using Docker, though alternative options are linked where relevant.

Setting up the project¶

To start, ensure you have forked and cloned the bot repository to your local machine. For help with this, check out our detailed guide.

Set Up Project Dependencies¶

The following are needed to run the bot:

uv: See the uv installation guide.
Python 3.14: This can be installed using uv.
Project Dependencies: Install by running uv sync in the command line from the root directory of the cloned repository.
Docker. See our docker guide.

Set Up a Test Server¶

The Python bot is tightly coupled with the Python Discord server, so the bot expects the existence of certain channels, roles, and other server configurations to be able to run.

It is highly recommended to use our server template, as it configures most of this for you.

This is not an exact mirror of the Python server, but a reduced version for testing purposes.

Set Up a Bot Account¶

You will need your own bot account on Discord to test your changes to the bot. See our guide for help with setting up a bot account, and inviting it to your server.

If you want to use an existing test bot account, ensure that:

It has the Message Content Intent and Server Members Intent intents enabled.
It was invited to your server with the bot scope and Administrator permission.

Configure the Bot¶

You now have both the bot's code and a server to run it on. It's time for you to connect the two by setting the bot's configuration.

Both .env and .env.server files we talk about below are ignored by git, so they do not get accidentally commit to the repository.

.env¶

This file will contain sensitive information such as your bot's token, do not share it with anybody!

Create a file called .env in the project root with the below content.

BOT_TOKEN=YourDiscordBotTokenHere
GUILD_ID=YourDiscordTestServerIdHere

See here for help with obtaining the bot token, and here for help with obtaining the guild's ID.

This is all that is needed for a basic setup. See the appendix for a full list of supported available variables.

.env.server¶

All server related configuration values are saved in this file, which also needs to be at the root directory of the project.

We provide a script to automatically generate a server config. Note: The script only works with servers created with the template mentioned above.

Running the below command will use the BOT_TOKEN and GUILD_ID from the .env file you created above to download all of the relevant IDs from the template guild into your .env.server

Note: This script will overwrite the .env.server file. We suggest you put any configuration not generated by this script in to .env instead

$ uv run task configure

Once the script has finished running, you'll notice the creation of a new file called .env.server at your project's root directory. This file will contain the extracted IDs from your server which are necessary for your bot to run.

If you want to setup the bot from an existing guild read our manual configuration guide. This is far more complicated and time consuming.

Congratulations, you have finished the configuration and can now run your bot.

Run it!¶

With Docker¶

You are now ready to run the Python bot. The simplest way to do so is with Docker.

With all of the above setup, you can run the project with docker compose up. This will start the bot and all required services! Enter your server and type !help to see the bot in action!

Some other useful docker commands are as follows:

docker compose pull this pulls updates for all non-bot services, such as postgres, redis and our site project!
docker compose build this rebuilds the bot's docker image, this is only needed if you need to make changes to the bot's dependencies, or the Dockerfile itself.

Your bot is now running, all inside Docker.

Without Docker¶

Note: If you want to read about how to make debugging with an IDE a easier, or for additional running methods, check out our extended configuration guide.

Development Tips¶

Now that you have everything setup, it is finally time to make changes to the bot!

Working with Git¶

Version control of our projects is done using Git and Github. It can be intimidating at first, so feel free to ask for any help in the server.

Click here to see the basic Git workflow when contributing to one of our projects.

Running tests¶

This section of the README in the tests repository will explain how to run tests. The whole document explains how unittesting works, and how it fits in the context of our project.

Make sure to run tests before pushing code.

Even if you run the bot through Docker, you might want to setup a development environment in order to run the tests locally.

Lint before you push¶

As mentioned in the contributing guidelines, you should make sure your code passes linting for each commit you make.

For ease of development, you can install the pre-commit hook with uv run task precommit, which will check your code every time you try to commit it. For that purpose, even if you run the bot through Docker, you might want to setup a development environment, as otherwise the hook installation will fail.

Issues?¶

If you have any issues with setting up the bot, come discuss it with us on the #dev-contrib channel on our server.

If you find any bugs in the bot or would like to request a feature, feel free to open an issue on the repository.

Next steps¶

Now that you have everything setup, it is finally time to make changes to the bot! If you have not yet read the contributing guidelines, now is a good time. Contributions that do not adhere to the guidelines may be rejected.

Have fun!

Appendix: Full ENV File Options¶

The following is a list of all available environment variables used by the bot:

Variable	Required	Description
`BOT_TOKEN`	Always	Your Discord bot account's token (see Set Up a Bot Account).
`GUILD_ID`	Always	Your Discord test server's id (see Set Up a Test Server).
`BOT_PREFIX`	When you wish to use a prefix different than "!"	Your Discord bot command's prefix.
`API_KEYS_SITE_API`	When running bot without Docker	Used to authenticate with the site's API. When using Docker to run the bot, this is automatically set. By default, the site will always have the API key shown in the example below.
`BOT_SENTRY_DSN`	When connecting the bot to sentry	The DSN of the sentry monitor.
`BOT_TRACE_LOGGERS`	When you wish to see specific or all trace logs	Comma separated list that specifies which loggers emit trace logs through the listed names. If the ! prefix is used, all of the loggers except the listed ones are set to the trace level. If * is used, the root logger is set to the trace level.
`DEBUG`	In production	`true` or `false`, depending on whether to enable debug mode, affecting the behavior of certain features. `true` by default.
`REDIS_PASSWORD`	When not using FakeRedis	The password to connect to the Redis database (see Staring Redis with other methods).
`USE_METRICITY`	When using Metricity	`true` or `false`, depending on whether to enable metrics collection using Metricity (see Working with Metricity). `false` by default.
`API_KEYS_GITHUB`	When you wish to interact with GitHub	The API key to interact with GitHub, for example to download files for the branding manager.
`METABASE_USERNAME`	When you wish to interact with Metabase	The username for a Metabase admin account.
`METABASE_PASSWORD`	When you wish to interact with Metabase	The password for a Metabase admin account.