Note: This project has moved to GitLab. This GitHub repository is archived. Development continues on GitLab.

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 PostgreSQL

To use PostgreSQL instead of SQLite, update your config file:

database:
  db_type: postgresql
  db_name: nerpybot
  db_username: bot_user
  db_password: your_password
  db_host: localhost
  db_port: 5432

Alternatively, uncomment the postgres service in docker-compose.yml for an all-in-one setup.

Supported databases: SQLite (default) and PostgreSQL.

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
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 PostgreSQL)
• 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