Skip to content

For Developers

Jump to bottom
Silas Santini edited this page Aug 9, 2024 · 8 revisions

This is a guide for project developer and repository maintainer to set up environment and start developing.

Local Setup

Step 1: Clone Repo

Clone the repository and change directories into the repository.

	git clone [email protected]:berkeley-cdss/seating.git
	cd seating

Step 2: Setup Virtual Environment

Create and activate a virtual environment.

Windows:

	python3 -m venv venv
	./venv/Scripts/activate

Mac:

	python3 -m venv venv
	source venv/bin/activate

Step 3: Install Dependencies

You should install from both requirements.txt and requirements-dev.txt. Make sure you are in the virtual environment.

    pip install -r requirements.txt
    pip install -r requirements-dev.txt

requirements.txt includes psycopg2 which may have trouble installing. You may run the below to address this.

    pip install psycopg2-binary

Step 4: Setup Environment Variables

Copy the .env.example file to .env and fill in the environment variables. See .env.example for a list of environment variables and explanations. You will need a few API keys and secrets. See the section on external Services for more details.

Make sure you are in the virtual environment!

Step 5: Setup Database

For development, we are using a local sqlite3 database. Hence, no need to configure any server or connection string. You only need to initialize the database once.

   flask resetdb

Step 6: Spin up the Server

   flask run

Open localhost:5000. You should be able to see the app running locally.

Step 7: Navigate the App

Try clicking into a course offering and create an exam.

Use this demo Google Sheet to import rooms and students, and trying out assigning seatings.

External Services

To use the full functionality of the app, you will need to set up the following external services.

Bare Minimum

This section covers the bare minimum that is needed for functionality of the app.

Canvas API

This is for user authentication and data fetching of courses, students, etc.

Contact School LTI team to register your app and client ID and secret.

GCP Service Account

This is for Google Sheets API to bulk import rooms and students

Setup a GCP Project and create a service account with the role Project Editor.

There are two ways to provide service account credentials to the app. In any case you will need to download the service account key as a JSON file from GCP Dashboard first, and set GCP_SA_CRED_TYPE to either file or env.

  • Use credentials file
    1. Download the service account key as a JSON file from GCP Dashboard and save it to root directory of the repo as gcp-service-account-credentials.json.
    2. Set the environment variable GCP_SA_CRED_TYPE to file.
    3. Set the environment variable GCP_SA_CRED_FILE to gcp-service-account-credentials.json.
    4. You could of course use a different file path, but make sure you set the environment variable accordingly and never commit the file to version control. The default name of gcp-service-account-credentials.json is already in .gitignore.
  • Use environment variables
    1. Sometimes, using a credentials file is not convenient (on GitHub Action/Heroku for example). You can also encode the content of the downloaded JSON file into a base64 string and supply it via an environment variable.
    2. Download the service account key as a JSON file from GCP Dashboard.
    3. Encode the content of the JSON file into a base64 string. base64 -w 0 path/to/your/service-account-file.json
    4. Set the environment variable GCP_SA_CRED_TYPE to env.
    5. Set the environment variable GCP_SA_CRED_VALUE to the base64 string you just obtained.

Right now, on GitHub, GCP service account credential uses my personal account (which, should not be the case). If I graduate or if it expires you should get a new one. We should consider shifting to department service account at some point in the future.

An SMTP server

This is for sending emails to students about their seat assignments.

We have not yet decided on a SMTP server to use. For now, you can use your own Gmail account SMTP server.

Right now, on GitHub, it is using my own personal Gmail account (which, should not be the case). If I graduate or if it expires you should get a new one. We should consider shifting to department service account at some point in the future.

Non-essential

The following are related not to functionality but to devops aspects.

Heroku

We use heroku for staging environment. You can use any staging environment. This integration is not instusive and you do not need to remove anything from the repo if you move away from Heroku.

Right now, we have a Heroku staging environment which uses my personal account (which, should not be the case). If I graduate or if it expires you should get a new one. We should consider shifting to department service account at some point in the future.

Codecov

We integrated Codecov for testing coverage report in Github CI. We have already set up the relevant workflow step and put in the Github Repository secret CODECOV_TOKEN, using my personal account (which, should not be the case). If the token expires or if I graduate, make sure to get a new CodeCov account and get a new token. We should consider shifting to department service account at some point in the future.

Sentry

We integrated Sentry for server monitoring. We have already integrated it and the only relevant piece of codes are in the root __init__.py. If that dsn expires of if I graduate, make sure to get a new account and new token. We should consider shifting to department service account at some point in the future. We should also apply to Open Source credential for Sentry.

Available CLI Commands

# intialize database
flask initdb
# drop database
flask dropdb
# seed database
flask seeddb
# reset database (drop, init, seed)
flask resetdb
# run linting check
flask lint
# run unit tests
flask unit
# run e2e tests
flask e2e
# run a11y tests
flask a11y
# run all tests (unit, e2e, a11y)
flask test
# run security audit
flask audit

Devops

Testing

This repo is equipped with some typical testing scaffoldings you might expect to find in a full-stack application:

  • Test runner: pytest
  • Coverage: pytest-cov, which uses coverage.py under the hood
  • HTTP request stubbing: responses
  • Seeding database from fixture files: flask-fixtures
  • Webdriver for UI/e2e tests: selenium

There are a few other aspects worth noting:

  • Canvas OAuth

We did not use responses library to stub out Auth API Call. Instead, when MOCK_CANVAS env var is set to True, our app would connect to a fake local OAuth2 server instead of the actual Canvas OAuth2 server. It still completes the entire OAuth2 flow but draws user information from server/services/canvas/fake_data/fake_users.json.

  • Canvas API

We did not use responses library to stub out Canvas API as we are using the canvasapi library instead of calling HTTP endpoints directly. What we did is to use a fake CanvasClient when MOCK_CANVAS env var is set to True, which draws information from server/services/canvas/fake_data.

  • Email

We provide three ways to test the email feature. For details see here.

CI

We are using GitHub Action for CI and Heroku for staging environment.

Deployment

At some point we should deploy this app properly, following department guidelines.

Clone this wiki locally