Development Setup Guide

Caution

Feb. 2024 All of the docs have been moved to https://tomli380576.github.io/yabob-docs/. We will slowly remove the docs in the wiki tab as they will no longer be maintained.

System Requirements

Install Node.js, select the Long Term Support version.

For developers

This guide explains how to fill the production environment variables. For development purposes the guide is the same, except fill in YABOB/src/environment/development.json instead of YABOB/src/environment/production.json

Step 1. Discord Developer Account, BOB App ID

Make a discord server.
Follow Discord's Official Documentation and create a bot account.

a. For the bot permissions at step 6 in the above documentation, choose Administrator.
Look for APPLICATION ID in the General Information tab. This is your YABOB_APP_ID.
Look for TOKEN in the Bot tab (it has a reset token button next to it). This is your YABOB_BOT_TOKEN.
In the Bot tab under Privileged Gateway Intents, enable SERVER MEMBERS INTENT.
In the OAuth2 $\to$ URL Generator tab, select bot in scopes, then select Administrator in bot permissions. Finally copy the generated URL at the bottom and paste it in your browser.
Opening the link will prompt you to invite your YABOB instance! Simply choose the server that you want to invite YABOB to.
If you are inviting YABOB to a server with existing roles, YABOB will prompt you to give it the highest role. Once you have saved the role settings, YABOB will DM you again saying that it got the highest role. Make sure that YABOB's role name is the same as YABOB's username.

Clone the source code

git clone https://github.com/KaoushikMurugan/yet-another-better-office-hour-bot.git

We recommend you rename the folder to YABOB to make it short and simple. We'll be referring to the project's root directory as YABOB from here on out

Step 2. Setup Firebase

Go to Google Firebase Console and sign in with a google account.
Click CREATE A PROJECT and follow the guide.
One the left $\to$ All products $\to$ Cloud Firestore, create a new database. Wait for it to finish.
One the left, Settings $\to$ Project Settings $\to$ Service Accounts $\to$ Generate New Private Key. This will prompt you to download a JSON file.

Go to YABOB/src/environment/production.json

"firebaseCredentials": {
    "projectId": "",
    "privateKey": "",
    "clientEmail": ""
}

From the file you just downloaded:
- Put the value of project_id into projectId
- Put the value of private_key into privateKey
- Put the value of client_email into clientEmail

Step 3. Running YABOB without extensions

Go to YABOB/src/environment/production.json, fill in:

"discordBotCredentials": {
    "YABOB_APP_ID": "",
    "YABOB_BOT_TOKEN": ""
}

For example:

"discordBotCredentials": {
    "YABOB_APP_ID": "1234567890",
    "YABOB_BOT_TOKEN": "qwertyuoikhjgSDJAHGiqdhqweKDSHahjsgdzxvcbzxvcmbn"
}

Install all the dependencies:
```
npm install
```
Now you can run the bot with the fundamental functionalities using this command: (Don't forget the space between the 2 dashes and noExtensions)
```
npm run prod -- noExtensions=true
```
For development, fill in src/environment/development.json, then run this (separates your dev credentials from production credentials):
```
npm run dev -- noExtensions=true
```

Step 3. Setting up extensions (optional)

Right now you have a functioning YABOB! To make YABOB more useful and customizable, we developed the extensions feature in Version 4.

YABOB comes with 3 built in extensions:

Google Sheet Logging

Utilizes Google Sheets to track:
1. Tutor/helper attendance and make sure they are following their schedules.
2. Provides insights to how many help sessions are being held.
Firebase Backup

Utilizes Google Firebase Database to backup server data. In case the bot crashes or accidentally shut down, the most recent snapshot will be stored in firebase and ready to be restored on next startup.
Session Calendar

Utilizes Google Calendar to display upcoming help sessions in the queue.

Ignoring Credentials in Git

For development, run this command in the YABOB directory:

git update-index --skip-worktree ./src/environment/*.json

This will ignore all changes in the credentials json files.

If the file structure changes in the future and requires new commits, run this:

git update-index --no-skip-worktree ./src/environment/*.json

and Git will track these files again. Then ignore the changes after updates.

Before we start

For the rest of this section, we will assume that you are setting up for production use. For development, fill in YABOB/src/environment/development.json instead of YABOB/src/environment/production.json

Google Sheet Logging Extension Requirements

Service Account Key

Go to Google Cloud and add your google account of choice.
Click Select a Project on the top left and create a new project.
Then go to API & Services $\to$ Credentials tab $\to$ Create Credentials $\to$ Service Account.
Follow the guide to create a service account. Enable Owner Permission.
Once you are back at the Credentials tab, click on the account you just created $\to$ KEYS $\to$ Add Key: Create New Key $\to$ Choose JSON $\to$ It will prompt you to download your key.
Copy the corresponding values of this JSON file into YABOB/src/environment/production.json.
```
"googleCloudCredentials": {
     "client_email": "",
     "private_key": ""
 }
```
This client_email is the email of YABOB. We will share the google sheet with this email in the next step.

Google Sheets API

Still in the Google Cloud Console, go to APIs and Services $\to$ Enabled APIs & Services.
Click on ENABLE APIS AND SERVICES.
Search for Google Sheets, Click on that then click ENABLE.
Search for Google Drive, enable this API as well.

Now we have access to google sheets, we just need the sheet itself.

Google Sheets ID

Create an empty Google Sheet and share the sheet to YABOB's service account email with EDIT access.
- This is the client_email field under googleCloudCredentials
The google sheets URL looks like this:
```
https://docs.google.com/spreadsheets/d/<very long string here>/edit
```
That very long string is your YABOB_GOOGLE_SHEET_ID.
Go to YABOB/src/environment/production.json. Fill in YABOB_GOOGLE_SHEET_ID with the string you just found.
```
"googleSheetLogging": {
    "YABOB_GOOGLE_SHEET_ID": ""
}
```

Calendar Extension Requirements

Google Calendar API

Create a google calendar.
Go to that particular calendar's Settings and Sharing tab. Tick the Make available to public checkbox.
Scrolling down will take you do the Integrate Calendar Section. Copy the Calendar ID. It should end with calendar.google.com. This is your YABOB_DEFAULT_CALENDAR_ID and will be used as a fallback calendar
Go to Google Cloud, then go to APIs and Services $\to$ Enabled APIs & Services
Enable the Calendar API
Still in APIs and Services, go to Credentials $\to$ CREATE CREDENTIALS: API KEY
Now you will be prompted with a long string. You can limit the scopes of this key by following the guide on screen. This is your YABOB_GOOGLE_API_KEY

Go to YABOB/src/environment/production.json, fill in

"sessionCalendar": {
    "YABOB_DEFAULT_CALENDAR_ID": "",
    "YABOB_GOOGLE_API_KEY": ""
}

Continue to setup the firebase extension (credentials required for calendar id backup)

Firebase Extension Requirements

Go to Google Firebase Console and sign in with a google account.
Click CREATE A PROJECT and follow the guide.
1. If you made a google cloud project from setting up one of the above extensions, you can choose that one.
One the left $\to$ All products $\to$ Cloud Firestore, create a new database. Wait for it to finish.
One the left, Settings $\to$ Project Settings $\to$ Service Accounts $\to$ Generate New Private Key. This will prompt you to download a JSON file.