Discord-Bot

A Discord bot that you can use as your own.
Built with a robust structure, seamless error handling, and easy configuration. Configure and edit effortlessly for a personalized experience.

Table of content

• About the project
  • Major features
  • Built with
• Getting started
  • Python prerequisites
  • Discord developper configuration
  • Configure the bot
  • Run the bot
• Database
  • SQL tables structure
• Development
• Workflows

About the project

This discord bot was made for an IT School in 2020. It has a lot of features including all the latest features from discord.py. Made by student(s) for students.

Major features

• Administrative Tools
  • Custom prefix per guild
  • Invite tracker
• Developement & Tools
  • ANSI color support
  • Dynamic structure (Does not require a reboot to apply changes in code & files)
  • Database support (SQL)
  • Error handling
  • Image processing
  • Logging
  • Multiple configs
  • Metrics about usage of the bot
  • Powerful, dev & debuging commands
  • Utility functions
  • Socket communication system
• Discord support
  • AppCommands (Slash-commands)
  • Cogs/GroupCogs
  • Commands
  • ContextMenus (Right-click commands)
  • Custom-Modals (Forms)
  • Custom-Views (Buttons, Dropdown, ..)
  • Groups
  • HybridCommands (Slash-commands + Commands)
• User Interaction
  • Custom Help command
  • Dynamic Starboard
  • Language detector & Translation
  • Private text channel on demand (cog: privatetext)
  • Private vocal channel on demand (cog: privatevocal)
  • Reddit posts listner
• And more..

Built with

• Python 3 >= 3.8
• discord.py == stable
• SQL
  • MariaDB (or MySQL)

Note

More about requirements in the requirements.txt file.

Getting started

Python Prerequisites

Install python packages with:

• pip

$ pip install -r requirements.txt

Discord developper configuration

1. Create an application on Discord Developpers

2. Enable the bot status in Discord Developpers/applications/{YOUR_APP_ID}/bot

3. Please make sure you have enabled each needed Privileged Gateway Intents in Discord Developpers/applications/{YOUR_APP_ID}/bot #Privileged Gateway Intents for your application.

4. Copy the token bot from Discord Developpers/applications/{YOUR_APP_ID}/bot #Token

Tip

In URL replace {YOUR_APP_ID} with your own app/bot ID.

Configure the bot

1. Paste your discord bot token in the "token" field inside /config/bot.json.

2. Configure the prefix in the /config/bot.json.

3. If you are using a database, fill your database credentials in the /config/database.json file.

4. Inside your SQL database, create the following tables listed in the SQL tables structure section.

Important

If you are NOT using any/or a compatible database, check the Acknowledgement section.

Run the bot

Now that you've set up the Python environment and configured the Discord application, it's time to run your bot.

Open a terminal and navigate to the project directory. Execute the following command:

python bot.py

This will start your Discord bot, and if everything is configured correctly, you should see the bot coming online in your Discord server.

Note

Keep the terminal open while the bot is running. If you encounter any issues, check the logs for error messages (by default discord.log), and ensure that you've followed all the configuration steps accurately.

Congratulations! Your bot is now up and running, ready to respond to commands and interact with users on your Discord server.

Database

Acknowledgement

Important

If you have not planned to use a SQL database:

1. set the "use_database" field to false in the /config/database.json file.
2. in the folder /cogs you should remove the following files (which are using the database): birthday.py, croissants.py, invite.py, me.py, metrics.py, starboard.py.

To set up a SQL database such as MariaDB or any other SQL database, and host it on a Raspberry Pi or any other server, you need to follow these steps:

1. Install MariaDB or any other SQL database on the desired server. The installation process may vary depending on the operating system and which SQL database you have selected. You may also want to install a graphical user interface for your database, such as phpMyAdmin, which makes it easier to manage and configure your database.

2. Create a new user with password that the bot is going to use and grant the necessary permissions such as SELECT, INSERT, UPDATE, DELETE, and SHOW DATABASES.

3. If the database is on the same server, no additional configuration is usually required. However, if the database is hosted on a different server, you may need to configure network settings to allow access to the database server. Specifically, you might need to open port 3306, which is the default port for SQL databases, on the server where the database is hosted.

4. Create a new database. Add the tables listed in the SQL tables structure section. You can change the structure of the tables as you wish, but you will need to reconfigure some keys/values of the /config/cogs.json.

5. Fill the database settings for your bot in the /config/database.json file as following:

   • use_database: This line configures the bot to either use the database or not. If set to false you won't use any database features and your bot will run.
   • host: Sepcify the IP address/hostname of the database server. It could be a local IP adress if you're running your bot in the same local network than you're database is running (e.g. 192.168.1.31).
   • port: This specifies the port number on which the database server is listening. It's often set to the default SQL port, which is 3306, except if you change it you may not need to change the port number.
   • user: Here, you need to replace "user" with the actual username you will be using to connect to the database server. This should be the username that has appropriate privileges to access the desired database.
   • password: Replace this with the actual password for the specified username. It is the password that allows you to connect to the database server.
   • database: Replace this with the name of the database you want your bot to connect to. Specify the actual name of the database that contains the data your bot needs to access or modify.

SQL tables structure

Note

These tables are required in the database if you have planned to use the bot as if provided

• table_birthday

CREATE TABLE IF NOT EXISTS `table_birthday`
(
    `guild_id`          BIGINT unsigned NOT NULL,
    `user_id`           BIGINT unsigned NOT NULL,
    `user_birth`        DATE NOT NULL,
CONSTRAINT `me_per_guild` UNIQUE (`guild_id`, `user_id`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_croissants

CREATE TABLE IF NOT EXISTS `table_croissants`
(
    `user_id`           BIGINT unsigned NOT NULL,
    `user_count`        SMALLINT unsigned,
UNIQUE(`user_id`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_invite

CREATE TABLE IF NOT EXISTS `table_invite`
(
    `guild_id`           BIGINT unsigned NOT NULL,
    `channel_id`         BIGINT unsigned NOT NULL,
    `custom_message`     varchar(4096),
UNIQUE(`guild_id`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_me

CREATE TABLE IF NOT EXISTS `table_me`
(
    `guild_id`          BIGINT unsigned NOT NULL,
    `user_id`           BIGINT unsigned NOT NULL,
    `user_me`           varchar(1024),
CONSTRAINT `me_per_guild` UNIQUE (`guild_id`, `user_id`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_metrics

CREATE TABLE IF NOT EXISTS `table_metrics`
(
    `command_name`      varchar(32) NOT NULL,
    `command_count`     MEDIUMINT unsigned NOT NULL,
    `command_type`      varchar(64) NOT NULL,
UNIQUE(`command_name`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_prefix

CREATE TABLE IF NOT EXISTS `table_prefix`
(
    `guild_id`           BIGINT unsigned NOT NULL,
    `guild_prefix`       varchar(256),
UNIQUE(`guild_id`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

• table_starboard

CREATE TABLE IF NOT EXISTS `table_starboard`
(
    `reference_message`   VARCHAR(100) NOT NULL,
    `display_message`     VARCHAR(100) NOT NULL,
    `star_count`          SMALLINT unsigned NOT NULL,
UNIQUE(`reference_message`)
)
ENGINE = InnoDB,
CHARACTER SET utf8mb4,
COLLATE utf8mb4_unicode_ci;

Development

To add a new cog, place the Python file in the /cog folder.
While the bot is running, you can dynamically register the cog using the loadcog command followed by the name of the file without the .py extension. If you make changes to the cog after registering it, simply use rl or rel <cog_name> to reload the cog without restarting the bot.

The following commands provide flexibility and efficiency during the development phase, allowing you to seamlessly update and test your bot without restarting it.

Commands Overview:

Command	Alias	Description	Example
?loadcog <cog_name>		Loads a cog from the /cogs directory.	?loadcog basic
?unloadcog <cog_name>		Unloads a cog from the /cogs directory.	?unloadcog basic
?reloadallcogs	rell	Reloads all cogs inside the /cogs directory.	?reloadallcogs
?reload <cog1> <cog2> ...	rel	Reloads specified cogs from the /cogs directory.	?reload basic birthday
?reloadlatest <n_cogs>	rl	Reloads the n latest edited cogs in the /cogs directory.	?reloadlatest 3
?reloadviews	rv	Reloads all registered views in the /views directory.	?reloadviews
?reloadconfig	rc	Reloads all JSON config files inside the /config folder.	?reloadconfig
?synctree <guild_id>	st	Syncs applications commands with discord.	?synctree or ?synctree 123456789012345678

Most of the time you will be using, rl for reloading the latest edited cogs and rv for reloading all registered views.
These commands are essential for development, often used to quickly apply and test code changes, making the development process smooth and efficient.

Workflows

Update and restart discord bot

Github setup:

• On Github.com go on your project repository
• Then click on Settings > Actions > Runners > New self-hosted runner.
• Then select the right runner-image related to your machine and the right architecture.
• Then follow the Download and the Configure instructions.

Server setup:

• If you want to start the self-runner on boot, you can follow this guide. :warning: The self-hosted runner should have the following permissions, install apps and start/restart services. (install the service as --user usernameWithPermissions)

Discord bot service: This step is made for linux only.

• Create a service file in /etc/systemd/system/your-service-name.service with the following content:

[Unit]
Description=Discord bot startup service
After=multi-user.target

[Service]
Type=simple
Restart=no
User={usernameWithPermissions}
WorkingDirectory=/home/{username}/actions-runner/_work/Discord-Bot/Discord-Bot
ExecStart=python3 /home/{username}/actions-runner/_work/Discord-Bot/Discord-Bot/bot.py

[Install]
WantedBy=multi-user.target

Tip

Replace {username} & {usernameWithPermissions} with your username and Discord-Bot/Discord-Bot with your project name.

• Then enable the service with systemctl enable your-service-name.service

Contributors :