Big-Board

Local requirements

PHP 7.4
MySQL
Composer

Set up Slack

Channels

Create a #big-board channel.

Slack Bot

Go to https://api.slack.com/apps
Click Create an App.
Click From scratch.
Name it TobyBot and choose your team's workspace.
Allow the following permission scopes:
- commands
- channels:history
- channels:read
- channels:write.invites
- channels:write.topic
- chat:write
- chat:write.public
- emoji:read
- pins:write
- users.profile:read
- users:read
- users:write
- channels:manage
- channels:join
- im:write
Click "Slash Commands". Create these seven commands. For each one, define the Request URL as http://[YOURAPP].herokuapp.com/tobybot. Include Descriptions and Usage Hints as desired.
- /board: Query for puzzle status
- /solve: Set the solution for a puzzle
- /info: Get info for a puzzle
- /connect: Connect to Big Board
- /avatar: Refresh your avatar
- /tobybot: List all commands

Set up Google API project

Go here
Click "Create credentials". Choose "OAuth client ID".
Add Authorized JavaScript origins
- https://[YOURAPP].herokuapp.com
Add Authorized redirect URIs:
- https://[YOURAPP].herokuapp.com
- https://[YOURAPP].herokuapp.com/oauth
Note your Client ID and Client secret.
Add the privacy policy URL (http://your-domain/privacy) to your OAuth consent screen. Once your app is live, you'll need to go through the verification process here) to get rid of the "unverified app" screen.
Create a separate credential for testing. Add http://localhost:8888 to Authorized JavaScript origins and http://localhost:8888 and http://localhost:8888/oauth to Authorized Redirect URI's for that one
Click "Create credentials" again and choose "Service Account". Download the JSON for login info here for later.
At https://console.developers.google.com/apis/dashboard?project=[your-project-name], enable:
- Google Drive API
- Picker API
- Sheets API
Enable auth/drive.file scope at https://console.developers.google.com/apis/credentials/consent/edit?project=[your-project-id]
Click "Create credentials" again and choose "API Key"

Set up Heroku instance

Note that Heroku does not have a free tier. Many features can be tested using a local instance. The Slack integration must be tested on Heroku.

The current recommendation for testing is to sign your account up for the "eco" tier, which is $5/month and covers both the web and worker dynos.

Provision a MySQL add-on. I used ClearDB. Create a DB. Note your:

URL
DB name
username
password

The free (Ignite) tier is fine for testing, but upgrade to the Punch tier ($9.99/month) for the hunt.

Provision Heroku Redis. At the lowest (mini) tier, this costs $3 per month (prorated to the second).

heroku addons:create heroku-redis:mini -a your-app-name

Allow workers on Heroku.

heroku config:add LD_LIBRARY_PATH=/app/php/ext:/app/apache/lib -a your-app-name

Config variables

Define these locally and Heroku. Locally: copy envvars_example.config to envvars.config, fill out the fields, and run source envars.config. On Heroku: config variables are in the settings tab.

Some notes on figuring these out:

Database configuration

BIG_BOARD_DB_HOST
BIG_BOARD_DB_NAME
BIG_BOARD_DB_USERNAME
BIG_BOARD_DB_PASSWORD

On Heroku - there's a CLEARDB_DATABASE_URL config variable which is in the format mysql://BIG_BOARD_DB_USERNAME:BIG_BOARD_DB_PASSWORD@BIG_BOARD_DB_HOST/BIG_BOARD_DB_NAME?reconnect=true.

Locally - Run mysql and create a database and a user. host is localhost, the rest is what you set while creating this.

Google Drive configuration

GOOGLE_APP_ID - the project number in the google cloud console
GOOGLE_APPLICATION_NAME - the project name
GOOGLE_CLIENT_ID - you got this while setting up google credentials earlier
GOOGLE_CLIENT_SECRET - same
GOOGLE_DEVELOPER_KEY - the API key you got while setting up google credentials
GOOGLE_DRIVE_ID - go to google drive for your team folder, look at the url - it's the long id string there. Similarly for GOOGLE_DOCS_TEMPLATE_ID
GOOGLE_SERVICE_ACCOUNT_APPLICATION_CREDENTIALS - this is the json for when you made the service account credential

Slack configuration

SLACK_DOMAIN - just the id, without any dots or the slack.com domain -- e.g. palindrome2018
TOBYBOT_SLACK_KEY - OAuth Bot Access token. Starts with xoxb.
TOBYBOT_SIGNING_SECRET - Signing secret, listed under Basic Information. 32 characters long.

Other

SIDEBAR_TEAM_INFO - data that goes in Big Board sidebar. Semicolon separated; each semicolon starts a new line.

Set up local environment

Run:

composer install --ignore-platform-reqs

At this point, make sure all the installed libraries (which are at vendor/bin/) are on your PATH. Then run:

composer dump-autoload
propel config:convert
propel sql:insert
propel migrate --fake

You can run the app locally with e.g.

php -S localhost:8888

Push to Heroku

To set up the DB on Heroku, first push, then run:

heroku run bash -a your-app-name
propel sql:insert

Set up automatic deployments by connecting your Heroku instance to your GitHub repo.

Preparing for Hunt

Make a new Drive folder for the current year (if none exists), and add a nested folder for puzzles. The double nesting ensures that only one folder shows up to select when users have to log in, so they can't accidentally select the wrong one. Update the Heroku environment variables with both folder IDs.

Archive any Slack channels for puzzles from the prior hunt:

pip install slack_sdk
TOBYBOT_SLACK_KEY="..." python archive_puzzle_slack_channels.py

Backup the database:

mysqldump -h $BIG_BOARD_DB_HOST -u $BIG_BOARD_DB_USERNAME -p $BIG_BOARD_DB_NAME > backup.sql

You will need to enter the password on the command line when prompted.

Clear the puzzle and member tables:

mysql -h $BIG_BOARD_DB_HOST -u $BIG_BOARD_DB_USERNAME -p $BIG_BOARD_DB_NAME
# enter password
DELETE FROM member;
DELETE FROM puzzle;
DELETE FROM puzzle_archive;
exit;

Send out the tech workflow email, updating the prior year's doc. Ensure the Slack invitation is valid.

jpd236 / Big-Board

readme