Waterloo Jam League (wjl)

This repository is for the Waterloo Jam League. A fun little Kan Jam league due to most sports being closed for the time being. This app was a repository I created to allow people to submit their game scores and to keep track of schedule/standings. Also, I got to try some new things out.

Assumed Dependencies:

python
npm

Python Webapp

TLDR

    # install all python requirements
    pip install -r requirements.txt
    # export following if plan on testing locally
    export ARE_TESTING=True
    # allow for oauth from http
    export OAUTHLIB_INSECURE_TRANSPORT=1
    export OAUTHLIB_RELAX_TOKEN_SCOPE=1
    python runserver.py

This will use an in-memory database. To actually test with a PostGres database one just needs to setup the appropriate environment variables.

Environment Variables

The following variables are used by wjl and the defaults are in brackets:

DATABASE_URL: the database url to connect to (“sqlite://“)
SECRET_KEY: the secret key for the app (random uuid1)
GOOGLE_OAUTH_CLIENT_ID: the Google OAuth client id (default off)
GOOGLE_OAUTH_CLIENT_SECRET: the Google OAuth secret (default off)
FACEBOOK_OAUTH_CLIENT_ID: the Facebook OAuth client id (default off)
FACEBOOK_OAUTH_CLIENT_SECRET: the Facebook OAuth client secret (default off)
GITHUB_OAUTH_CLIENT_ID: the Github OAuth client id (default off)
GITHUB_OAUTH_CLIENT_SECRET: the Github OAuth client secret (default off)
ARE_TESTING: True if testing using Cypress (default False)

The various OAuth providers are off by default and one has to setup the client/secret
for their local development.

Database

One like wants persistence data for testing locally. First create a PSQL database and
set its URL in an environment variable

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/<DATABASE_NAME>

Now calling python initDB.py will create the database schema.

Adding OAuth Provider

This can be a bit of a pain. The easiest one to setup is Github (good for local development).

Github

Visit here to register an application on GitHub. You must set the application’s authorization callback URL to http://localhost:5000/login/github/authorized.

Once you’ve registered your application on GitHub, GitHub will give you a client ID and client secret, which we’ll can be set using

export GITHUB_OUATH_CLIENT_ID=<YOUR ID HERE>
export GITHUB_OUATH_CLIENT_SECRET=<YOUR SECRET HERE>

Google

I was unable to get this working locally. See here for how it was setup in production.

Facebook

I was unable to get this working locally. See here for how it was setup in production.

Github Actions

When doing a pull-request to the master branch some checks are
executed using Github actions. These actions are to ensure
the changes in the PR do not break anything. The following is executed:

Check the Python code for any flake8 issues
Run the webapp
Run the Cypress tests against the webapp

Cypress Testing Locally

TLDR

    cd cypress-testing
    # install all dependencies
    npm install
    # set application URL
    export CYPRESS_baseUrl=<Application URL: http://localhost:5000>
    # run the cypress app then choose test
    npm run open
    # run all tests
    npm run test

See the Readme in cypress-testing folder for more details.

Additional Sources

Python Resources

Flask - documentation for Flask
Flask-Login - documentation for login extension
Flask-Dance - documentation for handling OAuth providers
Flask-SQLAlchemy - dpocumentation for database flask extension
Flake8 - the python linter for the project

JavaScript Resources

jQuery - used for some basic pages
Boostrap - CSS framework
Vue - used for the score app and other more complex UI
Cypress - documentation for Cypress
TypeScript - a super set of JavaScript