The purpose of this guide is to get you a running local version of the Python bot. You should have already forked the repository and cloned it to your local machine. If not, check out our detailed walkthrough.

This page will focus on the quickest steps one can take, with mentions of alternatives afterwards.

Setting up the project¶

Setup Project Dependencies¶

Below are the dependencies you must have installed to get started with the bot.

1. Make sure you have Python 3.12 installed. It helps if it is your system's default Python version.
2. Install Poetry.
3. Install the project's dependencies.
4. Docker.

Set Up a Test Server¶

The Python bot is tightly coupled with the Python Discord server, so to have a functional version of the bot you need a server with channels it can use. It's possible to set the bot to use a single channel for all cogs, but that will cause extreme spam and will be difficult to work with.

You can start your own server and set up channels as you see fit, but for your convenience we have a template for a development server you can use: https://discord.new/zmHtscpYN9E3.

Keep in mind that this is not an exact mirror of the Python server, but a reduced version for testing purposes. The channels there are mostly the ones needed by the bot.

Set Up a Bot Account¶

You will need your own bot account on Discord to test your changes to the bot. See here for help with setting up a bot account. Once you have a bot account, invite it to the test server you created in the previous section.

Privileged Intents¶

It is necessary to explicitly request that your Discord bot receives certain gateway events. The Python bot requires the Server Member Intent to function. In order to enable it, visit the Developer Portal (from where you copied your bot's login token) and scroll down to the Privileged Gateway Intents section. The Presence Intent is not necessary and can be left disabled.

If your bot fails to start with a PrivilegedIntentsRequired exception, this indicates that the required intent was not enabled.

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!

To start, create a .env file in the project root with the below content.

BOT_TOKEN=YourDiscordBotTokenHere
GUILD_ID=YourDiscordTestServerIdHere
BOT_PREFIX=YourDesiredPrefixHere

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

Other values will be added to your .env over time as you need to interact with other parts of the bot, but those are not needed for a basic setup. For a full list of support values see the ENV file option appendix

.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.

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

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

$ poetry 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.

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

Run it!¶

With Docker¶

You are now almost 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 projec with docker compose up. This will start the bot an all required services! Enter your server and type !help (or whatever prefix you chose instead of !) to see the bot in action!

Some other useful docker commands are as follows:

1. docker compose pull this pulls updates for all non-bot services, such as postgres, redis and our site project!
2. 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.

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