Requirements and first run
Each community runs its own judgebot, with its own Discord application, model key and spend cap. A complete instance is three containers from one compose file:
db: Postgres with pgvector.judgebot: the Discord bot, the web app and HTTP API, and the daily data refresh.proxy: Caddy in front ofjudgebot, on127.0.0.1:8787.
What judgebot runs is a set of roles, JUDGE_ROLES in .env: --discord, --api,
--web, --mcp, --admin (the operator’s pages) and --jobs (the refresh). Unset, it
runs every role but --mcp and --admin, which each need a token of their own. A
further service, refresh, runs the data loads on demand. Two optional ones put the
instance on the internet: edge serves it over HTTPS on ports 80 and 443, and
cloudflared through a Cloudflare Tunnel without opening a port. The web app works
without Discord, and the bot is the last thing to add.
Requirements
Section titled “Requirements”- A host that stays on, with Docker and the compose plugin. Running takes about 200 MB of
RAM across the two containers.
scripts/deploy.shpulls the CI-built image. Building it from the checkout (scripts/deploy.sh --build) takes ~4 GB and a lot of CPU. - No Rust. The image carries
judgebot ingestas itsrefreshservice, so the data loads run in a container. To work from source, see Development setup. A binary run on the host checks HTTPS against the system’s CA certificates (ca-certificateson Debian and Ubuntu) and refuses to start without them. - A model provider. With
.envalone that is Anthropic’s API (ANTHROPIC_API_KEY). Ajudge.tomlchooses anything else. - Optionally, an embedder for semantic search: a Voyage AI key, or an embedding model on an OpenAI-compatible server. Without one the bot searches by category and full text only, and logs a warning at startup.
- For Discord, an application of your own and its bot token. Create the Discord app walks through the developer portal with links into Discord’s documentation.
Order of operations
Section titled “Order of operations”-
Configure with the config editor:
docker compose pullscripts/config.sh, then open the URL it prints.- Set your model key (
ANTHROPIC_API_KEY, or a provider in the Models tab), andVOYAGE_API_KEYfor semantic search if you have one. - Set
JUDGE_OPERATOR_EMAIL(a support address, required by the web app and the API), andJUDGE_OPERATOR_DISCORD(your Discord username, required by the bot) if you know it already. - Set
JUDGE_ROLESto--api --web --jobsin the Roles group: the web app and the refresh, without Discord until you add the bot. - Check the side panel, which shows whether each role would start. Save on the Review tab, then Ctrl-C.
To edit by hand instead,
cp .env.example .envand fill it in. Every variable is documented in the file and in the configuration reference. -
scripts/deploy.sh --dbstarts the database alone. Postgres publishes on localhost:5432 (loopback only). If something on the host already has that port, setDB_PORTand change the port inDATABASE_URLto match. -
docker compose run --rm refresh initloads everything: the schema, the cards, the current rules, the alias and note lists, embeddings if you have an embedder, and the emoji ifDISCORD_TOKENis already set.initis safe to run again. It counts as a refresh, so the first scheduled one comes a day later. The first embed pays the embedder once for every rule and glossary entry, a few cents on Voyage. After that, only changed rules are re-embedded. -
scripts/deploy.shstartsjudgebotandproxy, and waits untiljudgebotis healthy. It applies pending migrations at startup unlessJUDGE_AUTO_MIGRATE=false. Open http://localhost:8787 and ask a question. This runs the full pipeline, so it checks the model setup before Discord is involved. -
Create the Discord app, clear
JUDGE_ROLES(or add--discordto it), thenscripts/deploy.sh, which puts the edited.envlive without downtime. Then rundocker compose run --rm refresh emojionce, so answers show mana symbols as pictures instead of{W}. -
Turn on the weekly backup to an S3-compatible bucket (Cloudflare R2, AWS S3, Backblaze B2, MinIO): add
backuptoCOMPOSE_PROFILES, fill in.env.deploy, thenscripts/deploy.sh, which starts thebackupservice. The deployment runbook has each provider’s settings, the steps, the restore drill, and the cron line forscripts/backup-db.shinstead. The data refresh needs no schedule of yours:judgebot’s--jobsrole runs it everyJUDGE_REFRESH_HOURS(default 24), once step 3 has loaded the data. Until then it waits for it, with one warning naminginit.
Single steps
Section titled “Single steps”init is these, in this order, and each can be run by itself:
docker compose run --rm refresh migratedocker compose run --rm refresh cardsdocker compose run --rm refresh rules latestdocker compose run --rm refresh aliases # the list built into the binarydocker compose run --rm refresh notesdocker compose run --rm refresh embed # with an embedder configureddocker compose run --rm refresh emoji # once the Discord app existsTo load your own aliases or notes list, mount the file and name it, running from the
repository root. Each command replaces its whole table and records the list as yours, so
the daily refresh and a later init leave it alone. That also opts it out of updates to
the built-in list until you run the command again with no file. A built-in list is
reloaded by the refresh when an upgrade changes it.
docker compose run --rm -v ./data:/data:ro refresh aliases /data/aliases.yamlEmbedding width
Section titled “Embedding width”The schema is created with vector(1024) columns, Voyage’s width. Your embedder may
produce another width (OpenAI’s text-embedding-3-small is 1536):
inithandles it. On a database with no vectors yet, it takes the configured embedder’s width.- Loading step by step, run
reembed --yesinstead ofembedthe first time. It retypes the columns and records the embedding space before filling them.
The bot never mixes vectors from two embedders. On a mismatch it logs an error naming both and runs without vector search.
Behind a domain
Section titled “Behind a domain”Until a profile says otherwise, the stack answers on 127.0.0.1:8787 only. That is
enough for Discord over its gateway connection, which dials out. To publish the web app:
-
Point a DNS
Arecord for the name at the host, not proxied by Cloudflare, and forward ports 80 and 443 to it. Leave out anAAAArecord unless the compose network has IPv6: otherwise every IPv6 visitor reachesedgefrom Docker’s gateway and they share one rate-limit bucket (the runbook has the override that enables it). -
Set in
.env:COMPOSE_PROFILES=publicJUDGE_DOMAIN=judge.example.comAPI_CLIENT_IP=proxy -
scripts/deploy.sh. It starts the bundled Caddy (edge), which gets a Let’s Encrypt certificate and serveshttps://judge.example.com.
A reverse proxy of your own, or a Cloudflare Tunnel with no open port, works instead.
The deployment runbook has all three. API_CLIENT_IP must
match the route, or the rate limit counts the wrong address; the
security page gives the reason.
MTG Judgebot is unofficial Fan Content permitted under the Fan Content Policy. Not approved or endorsed by Wizards of the Coast. Portions of the materials used are property of Wizards of the Coast. ©Wizards of the Coast LLC.
The Comprehensive Rules come from Wizards of the Coast. Card data, rulings and card symbols come from Scryfall, which is not affiliated with this project. Rule links go to the Yawgatog mirror. License and attribution.