73 lines
3.9 KiB
Markdown
73 lines
3.9 KiB
Markdown
# Matchy
|
|
<img src="img/matchy_alpha.png" width="255">
|
|
|
|
Matchy matches matchees.
|
|
|
|
Matchy is a Discord bot that groups up users for fun and vibes. Matchy can be installed on your server [here](https://discord.com/oauth2/authorize?client_id=1270849346987884696&permissions=0&integration_type=0&scope=bot).
|
|
|
|
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`.<br>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
|
|
```bash
|
|
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`](`tests/test.py`), which lints all python code and runs any tests with `pytest`. A helper script [`test-cov.py`](tests/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`](matchy/files/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](https://discordpy.readthedocs.io/en/stable/discord.html).
|
|
|
|
### 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:
|
|
```bash
|
|
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:
|
|
```yaml
|
|
services:
|
|
matchy:
|
|
image: forge.mdiluz.io/mdiluz/matchy:${MATCHY_TAG:-latest}
|
|
env_file: ".env"
|
|
volumes:
|
|
- ${MATCHY_DATA:-./.matchy}:/usr/src/app/.matchy
|
|
```
|