Skip to content

Latest commit

 

History

History
208 lines (137 loc) · 8.51 KB

README.md

File metadata and controls

208 lines (137 loc) · 8.51 KB
Raw

Discord bot for the BUT FIT Discord server

About

This bot manages the verification process, karma and a bunch of other simple commands on our BUT FIT Discord server. It is written in Python with the help of Disnake and its DB runs on PostgreSQL with ORM.

Since the most of the features are custom-made, we wouldn't recommend using it for different servers.

Setup

Creating a Discord App

Before you proceed to the environment setup, you will need to create a Discord application to get the Discord API key. We will not provide you with the exact steps on how to do this as there already exists this awesome guide from the developers of Disnake, Discord API Python library.

  • When creating an invite URL in the Inviting Your Bot section, the bot and applications.commands scopes are required. We also strongly recommend choosing Administrator in the Bot permissions as it is hard to figure out which of these permissions you actually need for the development.

Important

You should set up a separate server just for the development purposes so it shouldn't be that much of a security risk anyway.

  • After you create the Discord application, one additional step is required. You will also need to enable SERVER MEMBERS INTENT in Bot tab:

image

Tip

You can do this by going to the Discord Developer Portal and selecting your newly created application. Then click on the Bot tab on the left and scroll down to the Privileged Gateway Intents section.

Installing and running the bot

Start by cloning the repo:

git clone https://github.com/vutfitdiscord/rubbergod.git
cd rubbergod

Important

If you want to contribute to this project, refer to the contribution section first.

Configuration

cp config/config.template.toml config/config.toml

Now open the config.toml file in your editor. Insert the Discord API key you obtained earlier in the setup process:

1 [base]
2 command_prefix = ['?', '!']
3 default_prefix = '?'
4 ignored_prefixes = ['!']
5 key = '<Your Discord API key>'
...

Warning

Be careful. Bad things will happen if anyone else gets a possession of this key. Do not share it with anyone, ever!

On the next two lines, insert your Discord user and server ID so you get administrator rights over the bot:

6 admin_ids = [<Your Discord user ID>]
7 guild_id = <Your Server ID here>

Tip

Where can I find my User/Server/Message ID?

Then, create the following 5 channels (or use one channel for all of them) on your server and paste their IDs to the config:

72 log_channel = <Channel ID>
73 bot_dev_channel = <Channel ID>
74 vote_room = <Channel ID>
75 bot_room = <Channel ID>
76 mod_room = <Channel ID>

(Optional) For some features you will also need to set other config variables, usually they are divided into categories based on cogs.

Permissions and variables

Caution

There are needed some additional steps for permissions and variables.

./init.sh

Environment setup

Install Docker & Docker Compose V2 by going to their official documentation. Just select your OS and follow the steps.

  • Most installers should do that automatically, but just to be sure, enable docker service on startup: sudo systemctl enable --now docker.service.
  • To use Docker without sudo, you also need to be in docker group (eg. sudo usermod -aG docker $USER).
  • It's recommended to restart your system at this point (to get all the permissions and other stuff right).

a. Dev containers in VS Code (one click run) — preferred option

If you are using VS Code, you can simply run Rubbergod by using the Dev containers extension. Either by clicking on a notification or by clicking on arrows in bottom left corner (Open a Remote Window) and choosing Reopen in container.

b. Docker Compose CLI — if you don't use VS Code

This command should do the trick:

docker compose up

Docker will download all the necessary stuff and run the container. If you did everything correctly, bot will connect to the DB, load all the extensions and print Ready at the end. It will also send :peepowave: emoji to the #bot-room if you configured one. You're now all set!

Development

If you didn't run the container in detached mode, just press Ctrl+C to stop it.

Try to tweak some command a little bit and run the bot again, this time you can try to open it in detached mode so it won't block your terminal:

docker compose up --detach

Note

You can use shorter -d instead of --detach.

Important

If you changed some internal command logic, it should be applied instantly. If, however, your change involves Discord-side API changes — command name change, for example — it can take longer (few minutes to a few hours in extreme cases).

To stop the detached container, use this command:

docker compose down

Tips (optional)

Note

These things are not necessary for development but can help from time to time.

Enable commands sync debug

On startup the bot automatically syncs commands. Restarting the bot too frequently can lead to excessive synchronization attempts, causing the bot to time out from the Discord API. This timeout duration can vary widely, ranging anywhere from 10 minutes to up to X days. For debugging purposes it is recommended to set the sync_commands=False parameter. Be aware that the commands will not be updated on discord side (name, description, permissions, etc.), the functionality however will be updated.

Furthermore, if you want to enable command sync debugging info -- what exact update is being sent to the API and when --, you can also set the sync_commands_debug to True (info will be sent to stderr).

command_sync_flags=commands.CommandSyncFlags(sync_commands=True, sync_commands_debug=False),

Database-related tips can be found in database README.

List with all cogs, their commands and tasks can be found in cog README.

Contribution

To participate in the development, you need to create a fork and send us your contributions through "Pull requests". You can read more in About forks and Creating a pull request guides directly from GitHub. It may look scary at the first moment, but don't worry, it's actually pretty simple. If you don't know where to start, we can help you on Discord (mentioned below).

pre-commit (useful for contributors)

We use pre-commit for lint check before each commit. Use it by running these commands:

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

Authors

Pull requests, issues or tips for new features are very much welcome!

Discord development channel

Got stuck with the above steps? Any questions?

You can discuss bot-related stuff in the #bot-development channel on the BUT FIT Discord server.

Other bots

GrillBot — our 2nd Discord bot almost entirely developed and maintained by @Misha12 aka Hobit.

Pumpkin.py — Highly modular Discord bot created by folks at BUT FEEC.

License

This project is licensed under the GNU GPL v.3 License.