Matchy

Matchy matches matchees.

Matchy is a Discord bot that groups up users for fun and vibes. Matchy can be installed on your server here.

Note: Matchy currently only allows owner-authorised users to trigger posts in channels.

Commands

Matchy supports a bunch of user, matcher and bot owner commands. / commands are available in any channel the bot has access to, and $ commands are only available in DMs.

Command	Permissions	Description
/join	user	Joins the matchee list
/leave	user	Leaves the matchee list
/pause	user	Pauses the user for days: int days
/list	user	Lists the current matchees and scheduled matches
/match	user*	Shares a preview of the matchee groups of size group_min: int with the user. *Offers a button to post the match to matcher users
/schedule	matcher	Schedules a match every week with group_min: int users on weekday: int and at hour: int, on a weekly cadence: int. Can pass cancel: True to stop the schedule
/cancel	matcher	Cancels any scheduled matches in this channel
$sync	bot owner	Syncs bot command data with the discord servers
$close	bot owner	Closes the bot connection so the bot quits safely
$grant	bot owner	Grants matcher to a given user (ID)

Development

Development has been on on Linux so far, but running on Mac or Windows should work fine. Please report any issues found.

Dependencies

• python3 - Obviously, ideally 3.11
• venv - Used for the python virtual env, specs in requirements.txt
• docker - Optional, for deployment

Getting Started

git clone https://forge.mdiluz.io/mdiluz/matchy.git
cd matchy
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
git checkout -b [feature-branch-name]

VSCode can be configured to use this new .venv and is the recommended way to develop.

Tests

Python tests are written to use pytest and cover most internal functionality. Tests can be run in the same way as in the Github Actions with test.py, which lints all python code and runs any tests with pytest. A helper script test-cov.py is available to generate a html view on current code coverage.

Hosting

State

State is stored locally in a .matchy/state.json file. This will be created by the bot. This stores historical information on users, maching schedules, user auth scopes and more. See state.py for schema information if you need to inspect it.

Secrets

The TOKEN envar is required run the bot. It's recommended this is placed in a local .env file. To generate bot token for development see this discord.py guide.

Docker

Docker and Compose configs are provided, with the latest release tagged as forge.mdiluz.io/mdiluz/matchy:latest. A location for persistent data is stil required so some persistent volume will need to be mapped into the container as /usr/share/app/.matchy.

An example for how to do this may look like this:

docker run -v --env-file=.env ./.matchy:/usr/src/app/.matchy forge.mdiluz.io/mdiluz/matchy:latest

Docker compose

Matchy can easily be hosted with docker compose using a file like so:

services:
  matchy:
    image: forge.mdiluz.io/mdiluz/matchy:${MATCHY_TAG:-latest}
    env_file: ".env"
    volumes:
      - ${MATCHY_DATA:-./.matchy}:/usr/src/app/.matchy