BasementBot is a Dockerized Discord bot. Written on top of the Python Discord API, it provides the loading and unloading of custom extensions to extend and scale the bot as much as you want.
Note: this bot requires at minimum a MongoDB connection to maintain guild settings. If you wish to not use a MongoDB connection, check the base module for bots that don't rely on MongoDB. Some extensions also rely on postgres (factoids and more) and rabbitmq.
- Create a
config.yml
file from theconfig.default.yml
file in the repo. - In the
config.yml
file setauth_token
to your Discord developertoken
(see here) - In the
config.yml
file set MongoDB connection settings (username, password, host, port, etc) - (Optional) set any other
config.yml
variables. Some included extensions won't work without the correct API keys.
Note: MongoDB 5.0 x86_64 and later require a CPU that supports the AVX instruction set, it's recommended to use version 4.4. See here for an installation guide.
It's assumed that the bot is being deployed into a Docker container, as such extra configuration is necessary.
Edit the mongod
config located at /etc/mongod.conf
to allow the Docker container's IP address:
# network interfaces
net:
port: 27017
bindIp: 127.0.0.1,172.17.0.1
Edit docker-compose.yml
to include the below under bot
:
extra_hosts:
- "host.docker.internal:host-gateway"
Update the config.yml
file as such:
mongodb:
user: user
password: password
name: dbname
host: "host.docker.internal"
port: 27017
The user
, password
, and name
fields should be updated as you see fit. It does not matter what you choose, but this info will be relevant when setting up mongodb
.
From inside the mongodb
shell:
use admin
Switch to the admin
db, allowing us to create a database admin user for the bot.
db.createUser({ user: "user", pwd: "password", roles:[{role: "userAdminAnyDatabase" , db:"admin"}]})
Create an admin user for the bot to connect as, remember to set user
and password
to the values you specified in config.yml
.
exit
Close the mongodb
shell.
-
Build the prod image:
make prod
-
Run the Docker image using a
docker-compose.yml
configuration (see repo):make upp
-
Check the logs to verify things are working:
make logs
-
Run Discord commands with the prefix you set in the
.env
file (defaults to.
)
-
Build the dev image:
make dev
-
Spin up the dev containers:
make upd
The Makefile offers shortcut commands for development.
sync
makes an updated pipenv virtual environment.check-format
checks the formatting without changing files.format
checks formatting and changes files.lint
runs pylint.test
runs unit tests.dev
builds the dev Docker image.prod
builds the prod Docker image.upd
spins up the development bot container.upp
spins up the production bot container.down
brings down the bot container.reboot
restarts the dev container.restart
restarts the bot container.logs
shows the main container logs.
On startup, the bot will load all extension files in the basement_bot/extensions/
directory. These files hold commands for the bot to use with its prefix. Each command is an async function decorated as a command
, and each file must have an entrypoint function called setup
, which tells the loading process how to add the extension file.
A (very) simple example:
import base
from discord.ext import commands
def setup(bot):
bot.process_extension_setup(cogs=[Greeter])
class Greeter(base.BaseCog):
@commands.command(
name="hello",
brief="Says hello to the bot",
description="Says hello to the bot (because they are doing such a great job!)",
usage="",
)
async def hello(self, ctx):
# H, E, Y
emojis = ["๐ญ", "๐ช", "๐พ"]
for emoji in emojis:
await ctx.message.add_reaction(emoji)
Extensions can be configured per-guild with settings saved on MongoDB. There are several extensions included in the main repo, so please reference them for more advanced examples.