Running the bot

A guide on how to create and run the bot.

Intro

  • CroissantBot’s main file is bot.py. This contains the code to run the base bot. This includes the exit, help, ping, test and version commands.

    Tip

    For more commands, see Intro to cogs.

  • CroissantBot uses a file called .env to store its settings and credentials.

  • The bot’s default prefix is !.

Dependencies

This a list of all the packages used by the bot and its cogs. For the packages needed to run the base bot, see Packages below.

I’ve tested the bot with Python 3.6.9 in Ubuntu 18.04 and Python 3.6.1 in Windows 10 using the following packages:

Package

Usage

Cog using it

discord.py[voice]

API wrapper for Discord with voice support

The base bot

python-dotenv

To store API keys and other secrets in a .env file

The base bot

packaging

To check the bot’s current version

The base bot

asyncpraw

Asynchronous Python Reddit API Wrapper, to get memes from Reddit

Meme

yt-dlp

To get music and livestream information from Youtube

Music, Youtube and Playlist

streamlink

To check for YouTube livestreams

Youtube

asyncpg

To connect to the PostgreSQL database

Playlist

Deprecated since version 1.1.0: The youtube-dl package was used for the Music cog, but since it appears to no longer be maintained, using yt-dlp is recommended.

New in version 2.0.0: The asyncpg package.

New in version 2.0.0: The Playlist cog, which also uses the yt-dlp package.

Requirements

Packages

  • The discord.py[voice] package:

python3 -m install -U discord.py[voice]

py -m pip install -U discord.py[voice]

  • The python-dotenv package:

python3 -m install -U python-dotenv

py -m pip install -U python-dotenv

  • The packaging package may be already included, but can be installed with pip:

python3 -m install -U packaging

py -m pip install -U packaging

env variables

The file provided is actually called .env.example and not .env. It contains all the variables the bot may use, alongside some comments on their use.

The base .env variables to set are:

  • DISCORD_TOKEN: the bot’s token. Check the section Creating the bot to know how to get it.

  • BOT_PREFIX: the bot’s prefix, which is the character used before a command to invoke the bot. It’s set to ! by default, but you can change it; just make sure it doesn’t interfere with the prefix of other bots you use.

  • The log files:

    • Create the logs directory.

    • Create the four log files needed: info.log (stores INFO-level logs), debug.log (stores DEBUG-level logs), discord.log (stores DEBUG-level logs generated by discord.py) and streamlink.log (stores logs generated by streamlink).

    • Set the corresponding variables to their paths, relative to bot.py, like the ones already written.

  • LOG_COUNT: the logs files are emptied at midnight and their contents stored in an additional file (named something.log.202x-xx-xx). This variable indicates how many files of each log should be stored at once. By default the bot saves a week’s worth of logs.

Note

streamlink.log is only needed when using the Youtube cog, but it’s better to create it now than wonder why the bot can’t find the file.

Creating the bot

There are two parts to creating the bot: the code itself (which in this case is already provided) and creating an application and its corresponding bot in Discord.

Discord’s side

To create the bot on Discord’s side of things and get the bot’s token, I recommend following this guide. Here’s a quick rundown of the steps to follow:

  • If needed, create a Discord account and verify your email.

  • Login to Discord’s developer portal.

  • Create a new application.

  • In the Bot section (on the left), create a bot. You can change the default name.

  • Grab the token.

  • Scroll down and enable the server members intent under Privileged Gateway intents.

Code side

Keep reading to learn how to actually install the source code and run the bot.

Adding it to a server

To add the bot to a server (a guild in the API’s terminology) see this part of the previous guide. Essentially:

  • In the developer portal, go to the OAuth2 tab.

  • In the OAuth2 URL Generator, select bot in Scopes.

  • As for permissions, there are two options:

    • For a private server, Administrator is the easier choice.

    • For a bigger or more public server, it’s better to select only the permissions needed for the bot to run correctly.

    For now, the permissions I’m using with the bot are:

    Permissions

    View channels

    Send messages

    Embed links

    Attach files

    Add reactions (not used yet)

    Manage messages

    Read message history

    Use Application Commands

    Connect

    Speak

    Use voice activity

You can set the bot to public, allowing anyone who has the link you generated to invite the bot to their server, provided they have the necessary permissions (Manage server permission). Or you can leave the bot as private, which means only you can use the link to add the bot to any server in which you have the Manage server permission.

Installation and setup

Now, time to install the source code and run the bot!

  • If you have a GitHub account, clone the repo.

  • If not, create one or download the code from the releases page (preferably the latest one, since this guide is written for version 2.0.0).

    Note

    Cloning the repo is recommended in order to use Git to easily update the bot.

  • Install Python 3.6+: use your package manager or head over to the download page.

    • This should install pip, Python’s package installer. If unsure, read pip’s getting started to verify and install it if needed.

  • Optional but recommended: create a virtual environment to avoid conflicts with the dependencies.

  • To install all the package dependencies, use:

python3 -m install -U -r requirements.txt

py -m pip install -U -r requirements.txt

  • If you want to only install the packages needed for the base bot, see Packages.

  • If you haven’t already, create the bot on Discord’s side and get its token with the section above.

  • Use the token to fill the DISCORD_TOKEN variable in .env.example. If you haven’t already, set the other variables mentionned above.

  • Rename .env.example to .env.

    Warning

    This step is important. Normally, not renaming the file means the bot won’t be able to find it and will fail starting up. Even if it doesn’t, you should still rename it since it may get overwritten when updating the bot with git pull. That’s why the .example extension was added.

  • Add the bot to a server: for instructions see above.

  • Then, run bot.py:

python3 bot.py

py bot.py

Using cogs

Cogs are like extensions to the bot, and contain most of its commands. To find out more about them and how to use them, see Intro to cogs.