blinry / recurse-faces

A flashcard app to help you learn the faces of your fellow Recursers!

Recurse Faces

Learn the faces of your fellow Recursers!

Local set up

The app is comprised of a Flask back-end and a React front-end.

Front End

You will need to install dependencies:

$ npm install

If you want to do front end development only, you may set the REACT_APP_USE_TEST_DATA variable:

$ REACT_APP_USE_TEST_DATA=true npm run start

If you want to run the front end with the API, set it up as below. The React dev server is configured to proxy the Flask API, so you need only start both (in separate terminals, probably):

$ npm run start

Back End

The Python server is a Flask app that serves the index page and the JavaScript, handles the OAuth login process, and looks up names and images in the database.

Running the API locally requires populating the database and setting up the Python environment.

Python Virtual Environment

You'll first need to install the Python dependencies. First, set up a virtual environment:

$ python3 -m venv venv

or

$ python3 -m virtualenv --python=python3 venv

Then, activate the virtual environment and install the app's dependencies into it:

$ . venv/bin/activate
(venv)$ pip install -r requirements.txt

To populate the database or start the Flask app, the scripts must be run in this virtual environment (venv). The virtual environment can be reactivated at any time with the command:

$ . venv/bin/activate

Database

We use PostgreSQL as our database. Follow the installation instructions for your platform to set up the database server.

First, choose or create a database:

$ createdb --owner=$(whoami) faces

Depending on your platform, you may need to run that command as the operating system user which owns the database server:

$ sudo -u postgres createdb --owner=$(whoami) faces

Then, create the schema:

$ psql faces < schema.sql

There is a script to get the data the application needs from the Recurse Center API and store it in the database. To connect to the Recurse Center API, the script needs a personal access token, which you can create in the Apps page in your RC Settings. The personal access token will only be shown once, so copy it to a safe place.

Run the script in your [Python Virtual Environment](#Python Virtual Environment) with your personal access token:

(venv)$ DATABASE_URL=postgres:///faces \
  RC_API_ACCESS_TOKEN=<personal access token> \
  ./update-data.py

It should print out how many people were added.

Note: the DATABASE_URL can be any libpq connection string. Alternate database URLs you might try are postgres://localhost/faces or postgres://localhost/, to connect over TCP/IP to the databases named faces and your username, respectively.

Flask app

The Flask app needs some configuration, which it takes through environment variables.

When running in development mode, the app does not require authentication, so it needs to know your Recurse Center user ID. You can find your ID by going to the directory, looking yourself up, and examining the number in the URL; for example, 2092 in https://www.recurse.com/directory/2092-jason-owen.

If you are working on the RC OAuth integration, you will need to create an OAuth app in your RC Settings. Put the generated client ID and the client secret into the respective placeholders below. Otherwise, those can be set to placeholder values like _ (but must still be present and nonempty).

Start the Flask API in your [Python Virtual Environment](#Python Virtual Environment) by:

(venv)$ FLASK_APP=faces.py \
  FLASK_ENV=development \
  CLIENT_CALLBACK=http://127.0.0.1:5000/auth/recurse/callback \
  CLIENT_ID=<your_client_id> \
  CLIENT_SECRET=<your_client_secret> \
  DATABASE_URL=postgres:///faces \
  DEFAULT_USER=<your_recurse_user_id> \
  python -m flask run

The CLIENT_CALLBACK URL must include the port number the Flask instance is running on, which defaults to port 5000.

Heroku set up

This is app is deployed on Heroku:

$ heroku apps:create

To set up your Heroku app, add both the Python and Node buildpacks:

$ heroku buildpacks:add heroku/python
$ heroku buildpacks:add heroku/nodejs

You will also need to set several environment variables.

Three relate to the Recurse Center OAuth API. When you create your OAuth app in your RC account settings, you will need to set the callback to be https://<your_url>/auth/recurse/callback. Once you create it, you will get a CLIENT_ID and CLIENT_SECRET. You will also need to set a randomly chosen password for Flask to encrypt sessions with.

$ heroku config:set \
    CLIENT_CALLBACK=https://<your_url>/auth/recurse/callback
    CLIENT_ID=<your_client_id> \
    CLIENT_SECRET=<your_client_secret> \
    FLASK_SECRET_KEY=$(makepasswd --chars=64) \
    FLASK_ENV=production

You will also need to create a database:

$ heroku create heroku-postgresql:hobby-dev

and populate it:

$ heroku pg:psql < schema.sql

And you'll probably want logs of some sort. I'm using Papertrail:

$ heroku addons:create papertrail:choklad

Then, in theory, it should be a simple git push heroku master!