LionBot

LionBot is a Discord bot uniquely featuring integration with Google, allowing for a coherent infrastructure joining Google Accounts with Discord accounts. Its command structure is borrowed from Bold and Bash.

Setup

Prerequisites

Git is required to clone this repository.
Docker is required to run LionBot in a containerized environment.
Node.js is required, alternatively to Docker, to run LionBot directly on the host.

Instructions

Discord Setup

Create a Discord server.
Modify the @everyone role to take away the Send Messages permission in the Text Permissions section.
Make 4 roles:

The admin role. These are administrators, the staff with the most power. The permissions are up to you.
The moderator role. These are moderators, staff members with less power than the administrators. The permissions are up to you.
The LionBot role. This is the bot's role. The permissions must grant:
- Read Text Channels & See Voice Channels to receive commands.
- Send Text Messages to respond to commands.
- Manage Roles for the verification process.
- Manage Messages to delete entered commands that ended successfully, and clean up the verification channel.
The Verified role. The permissions should have everything except for Send Messages disabled, with Send Messages itself enabled.

Make 3 text channels in addition to the default #general channel (The names are up to you.):

The welcome channel. This contains info about the server. The permissions are up to you.
The report channel. This is where the bot reports events related to verification as well as mod mail. The permissions must be:
- @everyone is denied the Read Messages permission.
- Admins, moderators, and the bot are granted the Read Messages permission.

Make a bot user using this guide.
Invite the bot to the server using this guide. For the permissions, just use 0, because you already have made a role with the bot's permissions.
Give the bot role to the newly invited bot.

Google Setup

Log into the Google Cloud console.
- If at any point Google's account switcher doesn't function correctly, you can append the ?authuser=<USER_ID_HERE> to specify which logged in Google user you want to access the console from.
Create a new Google Cloud project.
Find the APIs and Services menu. This might be shown in a quick-access menu, and you can also just search for it, but here are absolute instructions:
1. Open the Navigation menu hamburger menu on the left.
2. Click View all products.
3. Click on the APIs and Services submenu.
Click Enable APIs and Services.
Under Google Workspace, enable the Google Sheets API (for manipulating the spreadsheet) and the Google Drive API (for seeing file modification times).
Still within the APIs and Services menu, click on the Credentials submenu.
Under Service Accounts, click Manage Service Accounts.
Click Create Service Account.
Fill out any details for the account. The optional sections can (and should) be left blank.
Save the credentials JSON for later.

Bot Setup

Open up a terminal or command prompt.
Clone the lionbot repository:

git clone https://gitlab.com/CodingKoopa/lionbot.git

Enter the lionbot directory:

cd lionbot

Make an environment file (e.g. .env) setting the configuration variables specified in env.json. Any fields for which default variables are provided may be omitted. Example excerpt:

LB_LOGGING_LEVEL=Debug
LB_DISCORD_TOKEN=ASFldsDFjk7DFkmslmk9Dmlm.DFnlsi.DFDSMKLSDFK_dfDSF8h7vjkjDFd

Copy the Google Service Account credentials from earlier to Data/GoogleServiceAccount.json.

The next steps depend on whether or not you are using Docker.

Bot Setup with Docker

In this section, there will be two code samples for each step:

A Bash command for use with with the Docker CLI.
A Docker Compose yml configuration, with version: "3.7".

Which one of these two you follow depends on whether or not you use Docker Compose in your setup. Either way, the Docker excerpts should be combined into a final command or yml.

Run the bot (read the following steps before running this!):

docker run --env-file .env registry.gitlab.com/codingkoopa/lionbot/amd64:stable

services:
  lionbot:
    image: registry.gitlab.com/codingkoopa/lionbot/amd64:stable
    env_file: /opt/lionbot/.env

Make the bot restart if it crashes (Optional.):

docker run --restart on-failure

services:
  lionbot:
    restart: on-failure

Use the Data mount point to create a volume:

docker run --mount type=volume,source=lionbot-data,target=/usr/src/app/Data

services:
  lionbot:
    volumes:
      - type: volume
        source: lionbot-data
        target: /usr/src/app/Data

Bot Setup without Docker

Export the configuration variables. This can be done by turning the aforementioned environment file into a script that exports the variables, or a Bash function like so:

# Exports the contents of an "ENV" file.
# Arguments:
#   - The path to the "ENV" file.
function export-env
{
  set -o allexport
  # shellcheck disable=1090
  source "$1"
  set +o allexport
}

Install the Node.js dependencies with the NPM package manager:

npm install

Run the bot:

npm run start

Building

LionBot Docker images are automatically built by GitLab CI/CD and uploaded to the GitLab Container Registry, but it can be built manually:

docker build . -t lionbot

services:
  lionbot:
    build: .

Contributing

If you are interested in working on the bot's code, follow these steps to get a development environment up and running:

Follow Discord Setup again, creating a separate Discord server, and separate bot account.
Create a new environment file with the development bot account info.
It's recommended to start the bot using npm, and the Bash function above:

export-env .env && clear && npm run start

When you've made your changes, use ESLint to check them for errors:

npm run lint

Features

A full list of commands be found by running the help command.

Google Sheets Integration

LionBot's Google Sheets integration follows a pipeline to a Google Sheet for Discord user verification.

Users submit a form via a Google Form.
Google automatically translates the data to a Google Sheet spreadsheet:

LionBot fetches the cells of the spreadsheet. This is done when the bot is started, and when the process command is ran from Discord. Additionally, every 10 minutes the bot will check to see whether a change has been made to the file, and if so fetch the cells again.
LionBot filters the results to users whose status is blank, as shown above. These users have had their submission neither approved nor rejected, as they haven't yet been processed by the bot. This is the user queue.
LionBot runs the user queue through two passes:
- Pass 1, Discord verification. This pass puts users who aren't in the target server or who already have the role into the reject queue. Email verification is also performed at this point, for limiting users to a domain. Users passing these tests go into the accept queue.
- Pass 2, Google verification. This pass cross references the emails of the users in the accept queue with users with status VERIFIED in the spreadsheet. To prevent using one email for multiple accounts, users that test positive here are put into the reject queue.
LionBot processes the queues:
- On Discord, LionBot grants the roles to users in the accept queue, and DMs the user with info and a success message. LionBot DMs the users in the reject queue if possible. In both cases, the action is logged in the report channel.
- On Google Sheets, LionBot populates the sheets with the processed users' statuses, and snowflake ID if accepted, or reject reason if not accepted:

License

LionBot is licensed under the GNU General Public License v2.0.

CodingKoopa / lionbot