Minerva Developer Guide

Note

This guide is based on the original Minerva documentation in Google Docs:

This document is for developers who want to hack on the minerva‑rewrite Slackbot. It combines the Developer Onboarding and Developer Reference PDFs.

1. Getting Access

Development Slack Workspace

  • URL : https://waterloorocketrydev.slack.com

  • Join via the Development Slack Invite pinned in #software or by DMing a contributor.

  • Messages older than 90 days disappear due to free tier.

Development Google Calendar

  • Calendar ID: uwaterloo.rocketry.dev@gmail.com.

  • Request “Make changes to events” permission from the Software Lead.

Oracle Cloud Instance

  • Shape VM.Standard.A1.Flex - 4 vCPU, 24 GiB RAM .

  • Public IP: 129.153.48.52.

  • Runs two PM2 apps: minerva (prod) and minerva-dev (dev).

  • To grant access, add the developer’s SSH public key to ~/.ssh/authorized_keys.

Slack Apps

  • minerva - production, minerva-dev - development.

  • Add collaborators via Settings → Collaborators; production access only for trusted devs.

Optional Development Google Account

Credentials for uwaterloo.rocketry.dev@gmail.com are available in #accounts (ask lead).

2. Local Setup

Clone and bootstrap :

git clone https://github.com/waterloo-rocketry/minerva-rewrite
cd minerva-rewrite
# Install Node ≥ 18 LTS and Yarn or pnpm
cp .env.example .env  # fill with dev secrets (see below)
yarn install
yarn start            # run locally

3. Deployment Workflow

Overview

  • GitHub Actions builds → SSHes into Oracle VM → swaps artefact.

  • Branch development → auto-deploys to dev workspace.

  • Branch main → auto-deploys to production after PR merge.

Local Testing

Run yarn start locally. Avoid port clashes with the dev bot in Oracle Cloud; ensure your local .env uses dev tokens.

Deploy to Development

Force-push to development or execute:

yarn deploy-dev

Deploy to Production

Merge PR → Actions run tests → deployment to prod Slack.

Viewing Logs

ssh ubuntu@129.153.48.52
pm2 list
pm2 logs minerva        # production
pm2 logs minerva-dev    # development

4. Environment Variables

Both dev and prod use these variables.

Environment Variables

Variable

Where to Get / Notes

GOOGLE_ACCOUNT_CLIENT GOOGLE_ACCOUNT_SECRET

Google Cloud Console → Credentials of • Production: waterloorocketry-minerva project. • Dev: rocketry-minerva project.

GOOGLE_ACCOUNT_TOKEN

Generate new refresh token via Google OAuth Playground; scope calendar.events.

GOOGLE_ACCOUNT_OAUTH_REDIRECT

Typically https://developers.google.com/oauthplayground/.

SLACK_APP_TOKEN SLACK_OAUTH_TOKEN SLACK_SIGNING_SECRET

Slack API → Basic Information → App-Level Tokens Slack API → OAuth & Permissions Slack API → Basic Information → App Credentials

NODE_ENV

production or development to toggle runtime settings .

DEPLOY_COMMIT_SHA

Auto-injected by GitHub Actions at deploy.

5. SSH Quick Commands

# Restart dev bot safely
pm2 restart minerva-dev

# Tail last 200 lines
pm2 logs minerva --lines 200

6. Onboarding Checklist

  • Add dev to Development Slack.

  • Grant Make changes to events on Dev Calendar.

  • Add their SSH key to Oracle VM.

  • Provide .env dev secrets (DM or scp from server).

  • (Optional) Add as collaborator to minerva-dev Slack App.