DiscordBot

A simple Discord bot with OpenAI support and server administration tools.
This bot serves as a starting point (template) for building other bots.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Commands
  • OpenAI
  • Admin/Mod
  • Config
  • Custom Commands
  • Misc
  • Dice Rolls
  • Bot Owner
  • GW2
  • GW2 Config
  • GW2 Key
  • GW2 WvW
• Development and Testing
• Credits
• License
• Support

Features

• OpenAI integration for AI-powered responses
• Guild Wars 2 API integration (accounts, WvW, sessions, wiki)
• Server administration and moderation tools
• Custom commands, profanity filtering, and text-to-speech
• PostgreSQL database with Alembic migrations
• Docker deployment with automatic database migrations

Prerequisites

• Docker and Docker Compose
• A Discord Bot Token
• (Optional) An OpenAI API Key for AI commands
• (Optional) A Guild Wars 2 API Key for GW2 commands

Installation

1. Clone the repository

git clone https://github.com/ddc/DiscordBot.git
cd DiscordBot

2. Configure environment variables

cp .env.example .env

Edit the .env file and set the required values:

# Required
BOT_TOKEN=your_discord_bot_token

# Optional
OPENAI_API_KEY=your_openai_api_key

# Database
POSTGRESQL_HOST=postgres
POSTGRESQL_PORT=5432
POSTGRESQL_USER=postgres
POSTGRESQL_PASSWORD=postgres
POSTGRESQL_DATABASE=discordbot

See Configuration for all available options.

3. Start the bot

The bot expects an external PostgreSQL instance running on a Docker network named postgres_network. If you don't have one, you can start a local database using the included compose file:

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

Then start the bot:

sudo systemctl enable docker
docker compose up --build -d

This will:

1. Build the Docker image
2. Run database migrations automatically
3. Start the bot

4. Verify the bot is running

docker-compose logs -f discordbot

For the full installation guide, see the Wiki.

Configuration

All configuration is done through environment variables in the .env file.

Bot Settings

Variable	Default	Description
BOT_TOKEN		Discord bot token (required)
BOT_PREFIX	!	Command prefix
BOT_EMBED_COLOR	green	Default embed color
BOT_EMBED_OWNER_COLOR	dark_purple	Owner command embed color
BOT_ALLOWED_DM_COMMANDS	owner,about,gw2	Commands allowed in DMs
BOT_BOT_REACTION_WORDS	stupid,noob	Words that trigger bot reactions
BOT_EXCLUSIVE_USERS		Restrict bot to specific users (comma-separated IDs)
BOT_BG_ACTIVITY_TIMER	0	Background activity rotation timer (seconds, 0 = disabled)

OpenAI Settings

Variable	Default	Description
OPENAI_API_KEY		OpenAI API key
BOT_OPENAI_MODEL	gpt-4o-mini	OpenAI model to use

PostgreSQL Settings

Variable	Default	Description
POSTGRESQL_HOST	postgres	Database host
POSTGRESQL_PORT	5432	Database port
POSTGRESQL_USER	postgres	Database user
POSTGRESQL_PASSWORD	postgres	Database password
POSTGRESQL_DATABASE	discordbot	Database name
POSTGRESQL_SCHEMA	public	Database schema

Logging Settings

Variable	Default	Description
LOG_LEVEL	INFO	Log level
LOG_TIMEZONE	UTC	Log timezone
LOG_DIRECTORY	/app/DiscordBot	Log file directory
LOG_DAYS_TO_KEEP	30	Log retention in days

See .env.example for the complete list of configuration options including cooldowns, SSL, connection pooling, and retry settings.

Commands

OpenAI Commands

Command	Description
ai <message>	Ask OpenAI for assistance, response as embed

Admin/Mod Commands

Command	Description
admin botgame <new game>	Change game that bot is playing

Config Commands

Command	Description
admin config list	List all bot configurations
admin config joinmessage [on, off]	Toggle message when a user joins the server
admin config leavemessage [on, off]	Toggle message when a user leaves the server
admin config servermessage [on, off]	Toggle message when a server gets updated
admin config membermessage [on, off]	Toggle message when someone updates profile
admin config blockinvisible [on, off]	Block messages from invisible members
admin config botreactions [on, off]	Toggle bot reactions to member words
admin config pfilter [on, off] <channel>	Configure profanity filter per channel

Custom Commands

Command	Description
admin cc add <command> <text>	Add a new custom command
admin cc edit <command> <text>	Edit an existing custom command
admin cc remove <command>	Remove a custom command
admin cc removeall	Remove all custom commands
admin cc list	List all custom commands

Misc Commands

Command	Description
about	Display bot info
echo <message>	Show your message again
ping	Test latency
pepe	Post a random Pepe image
tts <message>	Send text-to-speech as .mp3 to channel
serverinfo	Show server information
userinfo <member>	Show Discord user information
lmgtfy <search>	Create a LMGTFY link
invites	List active invite links for the server

Dice Rolls Commands

Command	Description
roll	Roll a die (defaults to 100)
roll <size>	Roll a die with specified size
roll results	Display all dice rolls from the server
roll reset	Delete all dice rolls (admin only)

Bot Owner Commands

Command	Description
owner servers	Display all servers in database
owner prefix <new prefix>	Change bot prefix for commands
owner botdescription <new description>	Update bot description

GW2 Commands

Command	Description
gw2 account	Display your GW2 account information
gw2 characters	Display your GW2 characters information
gw2 session	Display your last game session data
gw2 worlds na	List all NA worlds with WvW tier
gw2 worlds eu	List all EU worlds with WvW tier
gw2 wiki <search>	Search the Guild Wars 2 wiki
gw2 info <search>	Information about a given name/skill/rune

GW2 Config Commands

Command	Description
gw2 config list	List all GW2 configurations
gw2 config session [on, off]	Toggle recording of user sessions

GW2 Key Commands

Command	Description
gw2 key add [api_key]	Add your first GW2 API key
gw2 key update [api_key]	Update your existing API key
gw2 key remove	Remove your GW2 API key
gw2 key info	Show your API key information

GW2 WvW Commands

Command	Description
gw2 wvw info [world]	Info about a WvW world
gw2 wvw match [world]	WvW match scores
gw2 wvw kdr [world]	WvW kill/death ratios

Development and Testing

Requires UV to be installed.

Setup

uv sync --all-extras --all-groups

Running Tests

# Unit tests
poe test

# Integration tests (requires Docker for testcontainers)
poe test-integration

# All tests (unit + integration + hadolint + docker)
poe tests

Other Tasks

# Run linter (ruff)
poe linter

# Update all dev dependencies
poe updatedev

# Run database migrations
poe migration

# Profile unit tests
poe profile

# Profile integration tests
poe profile-integration

Credits

• Discord Bot API
• OpenAI API
• Guild Wars 2 API
• PostgreSQL

License

Released under the MIT License

Support

If you find this project helpful, consider supporting development:

• GitHub Sponsor
• ko-fi
• PayPal