Learn the faces of your fellow Recursers!
The app is comprised of a Flask back-end and a React 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
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.
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
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.
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.
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
!