NerpyBot

The nerdiest Discord bot! Built with discord.py using the Cog extension system. Provides gaming integrations (WoW, League of Legends), moderation, and music playback.

Quickstart (Local Development)

# Install dependencies
uv sync

# Copy and edit configuration
cp NerdyPy/config.yaml.template NerdyPy/config.yaml
# Fill in your Discord bot token, client ID, and API keys

# Start the bot
python NerdyPy/bot.py

# Debug mode
python NerdyPy/bot.py -l DEBUG

Docker Compose

The recommended way to run NerpyBot in production. The compose setup runs two bot instances (NerpyBot and HumanMusic) with automatic database migrations.

Setup

# Create config files from examples
cp config/nerpybot.yaml.example config/nerpybot.yaml
cp config/humanmusic.yaml.example config/humanmusic.yaml

# Edit both files with your Discord tokens and API keys

Run

# Start all services (pulls images from GHCR)
docker compose up -d

# View logs
docker compose logs -f nerpybot
docker compose logs -f humanmusic

# Stop
docker compose down

Migration containers run automatically before each bot starts, applying any pending database schema changes.

Building Locally

To build from source instead of pulling pre-built images:

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

Using an External Database

To use MariaDB/MySQL instead of SQLite, update your config file:

database:
  db_type: mariadb
  db_name: nerpybot
  db_username: bot_user
  db_password: your_password
  db_host: db_host
  db_port: 3306

MariaDB/MySQL charset: Create the database with utf8mb4 to support emojis and full Unicode:

CREATE DATABASE nerpybot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Using the default utf8 charset will cause errors when storing emoji or other 4-byte Unicode characters.

Supported databases: SQLite (default), MariaDB/MySQL, PostgreSQL. For other databases, specify the type with its driver (e.g., postgresql+psycopg2).

Database Migrations

Migrations are managed with Alembic and run automatically in Docker Compose. For manual usage:

# Install migration dependencies
uv sync --only-group migrations

# Apply all pending migrations
uv run alembic upgrade head

# Create a new migration
uv run alembic revision --autogenerate -m "description"

The migration runner resolves the database URL in this order:

1. DATABASE_URL environment variable
2. Bot config.yaml (path overridable via BOT_CONFIG env var)
3. alembic.ini default (sqlite:///NerdyPy/db.db)

Modules

Module	Description
admin	Server management, prefix configuration, command sync
league	Riot Games API integration
leavemsg	Server leave message announcements
moderation	Server moderation tools
music	Voice channel audio playback
reminder	Timed user reminders
tagging	Audio tag management
wow	Blizzard API integration

Enable modules by listing them in the bot.modules section of your config file.

Configuration

Copy NerdyPy/config.yaml.template (local dev) or config/*.yaml.example (Docker) and fill in:

• bot.client_id / bot.token — from the Discord Developer Portal
• bot.ops — Discord user IDs with bot admin privileges
• bot.modules — list of modules to load
• database — connection settings (see External Database)
• music / league / wow — API keys for respective services

Development

# Lint
ruff check

# Lint with auto-fix
ruff check --fix

# Format
ruff format

# Run tests
pytest

# Run tests with coverage
pytest --cov

Docker Builds

The Dockerfile provides two targets:

# Bot image
docker buildx build --target bot -t nerpybot .

# Migrations image
docker buildx build --target migrations -t nerpybot-migrations .

Bot Invite Links

• NerpyBot — Invite
• HumanMusic — Invite

License

GPL-3.0-or-later