Ren-chan

Ren-chan is a Discord bot for riichi club management, using Google Sheets for data store. Ren-chan is based on Ronhorn, as an effort to:

1. isolate the club management commands from the mahjong analysis commands (e.g., /injustice)
2. eventually create an end-to-end club management bot with minimal setup

See Running the bot section on a "quick" start guide.

Highlighted Functionalities

1. manages recurring events
   • creates each specified event if its next occurrence is missing
   • posts a reminder some time before a recurring event's start.
2. manages club memberships through the register slash commands
   • supports self-registration and registration by admin.
3. enables score tracking through the enter_scores slash commands
   • supports entering scores for multiple game modes
   • supports entering scores into multiple leaderboards
   • validates the score entry before pushing it to the database).

Setting up the bot

First, cp config.template.env config.env.

Discord Stuff

1. set up a bot account on Discord's developer portal (New Application).
   • (SETTINGS → Bot) Privileged Gateway Intents: SERVER MEMBERS INTENT AND MESSAGE CONTENT INTENT
2. invite the bot to the respective servers. You can use the developer portal's OAuth2 URL Generator (SETTINGS → OAuth2 → URL Generator):
   • Scopes: bot
   • Bot Permissions:
     • General Permissions: Manage Roles, View Channels, Manage Events, Create Events
     • Text Permissions: Send Messages, Create Public Threads, Send Messages in Threads, Manage Messages, Manage Threads, Use External Emojis
   • Current Bot Invite URL
3. fill in the Discord Stuff section of config.env. The bot token can be obtained through (SETTINGS → Bot [→ Reset Token])

Google Sheets Stuff

1. set up a Google Cloud project. Enable Google Sheets API access, and "Create Credentials" for a service account (no need to give it access to the project). Generate a JSON key for that service account and save it as gs_service_account.json in the root directory
2. make a suitable Google Spreadsheet (example)
3. share the Spreadsheet with that service account.
4. fill in the Google Sheets Stuff section of config.env

Ruleset Stuff

1. fill in the Ruleset Stuff section of config.env -- should be pretty straightforward.

Recurring Events

1. update the EventPoster cog with the appropriate recurring events you want the bot to manage. In the future, these will be configured in a config file instead.

OPTIONAL: Continuous Deployment

This repo does contain a GitHub Actions workflow that automates deployment to a server via SSH. Follow the below stops to enable this CD pipeline.

1. ensure that you have the repo at ~/Ren-chan (deploy.yml assumes this) and you have finish the previous setup steps.
2. generate your SSH key pair. Note that you should replace the username part with the target username on the server.

   ssh-keygen -t ed25519 -C "username" -f ~/.ssh/github_deploy_key

3. if you can manually manage ~/.ssh/authorized_keys on your server, then append the content of ~/.ssh/github_deploy_key.pub into that file. HOWEVER, if you are not supposed to manually manage that file -- for example, you are using a Google Cloud VM -- then you should follow your cloud platform's instructions.
   • For Google Cloud VM, you want to add the SSH public key to the VM instance like so. Note that if you are pasting the content of your public key to Google Cloud console's SSH box, you need to ensure that it ends with the target username (hence the note in the previous step).
4. ensure that your target user has passwordless sudo access. Check with sudo ls /root. If password is required, changing the setting with sudo visudo, and add the following to the end of the file:

   username ALL=(ALL) NOPASSWD:ALL
   

5. finally, you should configure the repository with the following Actions secrets (deploy.yml depends on them):
   • SERVER_IP: the external IP of your server
   • SERVER_SSH_KEY: the content of ~/.ssh/github_deploy_key
   • SERVER_USER: the same username as you configured earlier

Running the bot

1. ensure you complete all steps in the setup.
2. run ./deploy/deploy.sh (see repo structure for a breakdown of deploy.sh).
3. IF this is your first time deploying the bot to a server, OR IF you made a change to the I/O of any slash commands, then you need to run the rc/sync regular command to sync the slash commands (just post this as a message in the server and ensure it's visible to the bot).
   • rc/restart is another convenient admin command to restart the bot. For all bot admin commands, check bot.py.

Repository Structure:

• bot.py: entry point of the Discord bot. Does the following:
  1. imports global_stuff.py, which does the following:
     1. load all the environment variabels from config.env
  2. set up the non-slash Discord commands
  3. set up command error handlers (both slash and non-slash)
• deploy/: deployment-related scripts and service units.
  • ren-chan@.service: template for the system-wide service (it cannot be a user-level service because it would die with the user session).
    • The input specifier determines the user running the service.
    • Restarts the bot automatically 5 seconds after it dies.
  • deploy.sh: deploys the bot as a system-wide service, under the current user.
    1. pulls from remote
    2. installs latest depdendencies according to Pipfile.lock
    3. sets up the service according to ren-chan@.service under the current user.
  • stop_service.sh: stops the service (i.e., shuts down the bot)
  • undeploy.sh: stops and deletes the service, uninstalls the pip environment, and removes the log files.
• /ext/: Discord bot extensions (each extension is a suite of slash commands and their helper functions)
  • EventPoster: automates posting regular events and reminders for those events.
  • Utilities: various utilities, including recording in-person games, managing club membership, etc.

Relevant Links / References

• Ronhorn
• Ronnie