HexBug

A Discord bot for Hex Casting.

If you're here to get your mod added to HexBug, please start by opening an issue using the "Addon support" template.

Development

Setup

Install uv and clone this repository, then run the following commands in this repository to set up your dev environment:

# set up environment
uv run poe setup

# generate database
docker compose up --detach postgres
uv run alembic upgrade head

Note: If using Docker with WSL2 on Windows, networkingMode=mirrored seems to make Postgres connections extremely slow.

Bot setup (https://discord.com/developers/applications):

• Overview:
  • OAuth2:
    • Redirect: https://127.0.0.1
• Activities:
  • Settings:
    • Enable Activities
    • Enable all supported platforms
    • Set maximum participants to 1
  • URL Mappings:
    • Root Mapping: your Tailscale Funnel URL

Running

Generate a keypair for signing JWTs:

openssl genpkey -algorithm Ed25519 -out jwt_private_key
openssl pkey -in jwt_private_key -pubout -out jwt_public_key

Create a file called .env, and replace all values starting with ... with your actual values:

# bot
ENVIRONMENT="dev"
TOKEN="...discord bot token"
CLIENT_ID="...discord bot oauth2 client id"
CLIENT_SECRET="...discord bot oauth2 client secret"
JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
...contents of jwt_private_key
-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
...contents of jwt_public_key
-----END PUBLIC KEY-----"
API_PORT="6502"
API_ROOT_PATH="/api"
METRICS_PORT="6500"

# book
GITHUB_REPOSITORY="object-Object/HexBug"
GITHUB_SHA="main"
GITHUB_PAGES_URL="https://book.hexxy.media"

# activity
VITE_CLIENT_ID="${CLIENT_ID}"
VITE_JWT_PUBLIC_KEY="${JWT_PUBLIC_KEY}"

Run the bot standalone (faster for development):

docker compose up --detach postgres
uv run hexbug build --indent 2
uv run hexbug bot

Run the bot in Docker:

docker compose up --build

After running the bot for the first time or modifying a command, you'll need to sync slash commands and/or bot emoji. To do this, use the sync message command. For example: @HexBug sync

Build and serve the Book of Hexxy:

uv run hexbug build
uv run poe build-data
uv run hexbug web build-props
uv run hexdoc serve

Creating database migrations

https://alembic.sqlalchemy.org/en/latest/autogenerate.html

Book of Hexxy for addon developers

Gist by penguinencounter: https://gist.github.com/penguinencounter/ace5c45455ea968738a80b8c5e777235

Note that the hexdoc dependencies and static data files have moved from bot/ to data/.