CodersHQ Discord Bot

📝 Table of Contents

1. Introduction
2. Features
3. Dependencies
4. Setup
• Discord bot creation
• GitHub settings
• Setup environment variables
• Running the files directly
• Getting up and running locally with Docker
5. Contributors

🤖 Introduction

The CodersHQ Discord Bot is a general-purpose bot designed to communicate with the CodersHQ platform to announce events, moderate, and gamify servers.

Back to top ↥

🧠 Features

The CHQ Discord Bot comes with these features:

• Logging
• Member messages that are profane
• Member join/leave
• Member message edits
• Member message deletes
• Member updates
• Commands to interact with the bot
• Moderation
• Kick members
• Ban/Unban members
• Mute/Unmute members
• Purge messages
• Softban members
• Timeout members
• Lockdown channels
• Manage GitHub Issues within discord server
• Create/Edit GitHub issues
• Fetch all/specific GitHub issues
• Close GitHub issues

Back to top ↥

🛠️ Dependencies

There are requirements to run the bot, namely:

• Python 3.10+
• Postgres server (only if the /mute command is used)
• GitHub PAT (only if the /issue commands are used)
• Docker (optional for containerized deployment)
• Libraries in requirements.txt
• .env file to hold environment variables (same format from sample.env)
• Discord server requirements:
• Bot must have all the moderation and read permissions
• "Muted" role in server
• "moderation" and "micro-logs" channels in server

We recommend installing these dependencies in a Python Virtual Environment to keep management easy. To install all the libraries inside requirements.txt quickly, run this command in the root folder: python -m pip install -r requirements.txt

Back to top ↥

⚙️ Setup

There are some steps that needs to be followed in order for the bot to connect with Discord API as well as for the proper functioning of all the bot features mentioned above.

⭐ Discord Bot Creation

To begin inviting and running a Discord bot onto your server, first of all, you need to head over to Discord Developers Portal and create your bot there. After that, you need to retrieve your bot token and create a webhook URL (ignore the "Quick Example" section), both of which you need to save for later. Finally, you need to make some changes in the server:

• Create a "Muted" role in your server (only if you want the /muted command to work)
• Create "moderation" and "micro-logs" channels in your server for the moderation panel and in-server logs to show up
• Invite your bot to the required server

Back to top ↥

🐙 GitHub Settings

Once the Discord bot is created and installed to the server, the next step is to connect the code with the bot we just added to the server. Start by cloning the repository to get access to the code. You will also need a PAT from GitHub (explained here on how to get). The PAT is only needed if you wish to manage issues for a repository within the discord server.

Back to top ↥

🍀 Setup Environment Variables

To run the Discord bot, you need to setup environment variables. This can be done by adding a .env file to the root directory of your clone*. The sample.env file contains required variables to be defined. All these variables MUST be present, even if the value is empty.
Note that the field with the values are the ones that are expected by the docker container and not what is expected if the bot runs directly. Also note that if you don't have the value for an environment variable, leave it blank, do not delete the entire field instead. Here's what each field represents:

• TOKEN field should contain your Discord bot token that you generated earlier.
• WEBHOOK_URL field should contain your webhook URL from the webhook that you created earlier.
• DB_HOST field should contain the host in which your postgres server is running (usually localhost but micro_postgres (name of the postgres service inside docker-compose.yml), if you are using Docker)
• DB_USER field should contain the user to connect to in the server (usually postgres)
• DB_PASS field should contain the password of the user to connect to the server (usually root)
• DB_PORT field should contain the port where the postgres service is running (usually 5432)
• DB_DATABASE field should contain the database to connect to (usually postgres, but micro is kept default for docker.)
• PGADMIN_MAIL field should contain the mail (any) to connect to pgadmin for viewing (only required if running via docker)
• GITHUB_TOKEN field should contain a PAT (Personal Access Token) generated from your account.
• GITHUB_REPO field should contain your repository in the format username/repository_name

Do NOT upload your .env file to your GitHub repository as it contains sensitive information that shouldn't be published online.

Back to top ↥

🧑‍💻 Run the files directly

It's finally time! Once you're done with steps above, run this command once you have switched directory to micro folder: python main.py. Your Discord bot should now be online on your server as long as the code is running.

Back to top ↥

🐋 Run the containarized Discord bot with Docker (Alternative)

This step is optional, and you may skip it if you wish to run the discord bot via local python files. The root folder contains a docker-compose.yml file and a Dockerfile, which are used for creating the services and container image respectively.

To build the stack, execute this command:

docker-compose -f docker-compose.yml build

Then, to run the stack, execute this command:

docker-compose -f docker-compose.yml up

To run it in detached (background) mode, use:

docker-compose -f docker-compose.yml up -d

You can use this command to stop the stack whenever you wish:

docker-compose -f docker-compose.yml down

but keep in mind that the volumes containing the database will still be intact. To delete those, you can check the volume names that are currently attached to your container by executing this command: docker volume ls, and then executing this command individually on each volume that you want to delete to get a fresh start:

docker volume rm <name_of_volume>

Back to top ↥

🖥️ Contributors

Muhammad Arsalan Nawazish 💻 🚧

Nihaal Nz 💻 🚧

Back to top ↥

✨ Want to contribute?

If you wish to contribute, create a fork and put up a PR explaining the changes you have made. You can also get more information or help by joining the discord server (linked at the top).

*This same file will be used to supply environment variables to the docker container as well

Back to top ↥