COVID Modelling Web UI

This is a Next.js application that serves the GitHub COVID modelling web interface. It is hosted on Vercel.

The needs of the unified modelling project are changing rapidly, and so we do not have a set-in-stone development roadmap. This application is built with the goal of it hopefully being not too difficult to alter or even rewrite parts of it as requirements change.

To learn more about this project's goals, please see PROJECT-INTENT.md.

Local Development

This app has two development modes: "local" and "advanced" mode. The "local" mode is a much easier development setup, but does not actually queue simulation runs with the development control plane. Instead, it uses a stubbed result. The "advanced" mode is for maintainers only—it requires access to some shared credentials and accounts.

Shared Setup (for both local and advanced modes)

1. Install and start Docker.

2. Clone this repository:

   > git clone https://github.com/covid-modeling/web-ui
   > cd web-ui

3. Install dependencies:

   > npm install

Local Mode Setup

1. Create an OAuth app for local development

   • Go to https://github.com/settings/applications/new to create a new OAuth app
   • In the Authorization callback URL section, fill in http://localhost:3000/api/callback
   • Fill in anything you want for Application name and Homepage URL (this is for personal use only)
   • Click Register application
   • Make a note of the Client ID and Client Secret, you will need them for the next step.

2. Run the environment setup script:

   > script/setup

   This script will ask you a series of questions—you'll want to answer that yes, you do want to run in local mode.

3. Setup the database:

   > script/db-create

   Optionally, run all the database migrations (these will be automatically run every time you start the server).

   > script/db-migrate up

4. Start the server:

   > script/server

5. Fetch case data:

   This script requires some environment variables (see script/fetch-recorded-data --help), but if you've already got your .env set up, you can run the script with foreman to avoid manually setting them:

   > npx foreman run script/fetch-recorded-data

6. Authorize your local user to log in:

   > script/authorize-local-user $my_github_username

Advanced Mode Setup (Maintainers Only)

Advanced mode requires a number of secrets documented in env.yml, whose development values can be accessed by following instructions in the private maintainers-only documentation.

1. Start an HTTP ngrok proxy pointing to port 3000 and note its URL (such as "https://e028f3f1.ngrok.io"):

   > ngrok http 3000

2. Get the OAuth development app client ID and secret. You'll be prompted for them in the next step.

3. Run the environment setup script:

   > script/setup

   This script will ask you a series of questions—you'll want to answer that no, you don't want to run in local mode.

   This script will now ask for a number of environment variables, each of which can be accessed by following instructions in the maintainer docs.

   It'll also ask you for a RUNNER_CALLBACK_URL, which should be the value of your ngrok proxy.

4. Start the server:

   > script/server

5. Fetch case data:

   This script requires some environment variables (see script/fetch-recorded-data --help), but if you've already got your .env set up, you can run the script with foreman to avoid manually setting them:

   > npx foreman run script/fetch-recorded-data

6. Authorize your local user to log in:

   > script/authorize-local-user $my_github_username

Database & Migrations

In development, database migrations are run automatically when the web container starts.

To create a database migration:

# Create a migration
> script/db-migrate create name-of-migration --sql-file

We pass the --sql-file here because we write migrations in plain SQL in this project.

Environment Variables

Environment variables are documented in env.yml.

Architecture

• Pages are in pages/{route}.tsx.
• Components are in components/{Component}.tsx.
• API functions are in pages/api/{route}.tsx.

Useful Documentation

• Next.js pages
• Next.js API routes
• Vercel serverless functions
• Vercel environment variables and secrets
• React documentation

Updating Case Data and Intervention Data

The case_data and intervention_data tables are populated by the fetch-recorded-data script. This is run nightly on staging and production.

Contributing

We welcome contributions to this project from the community. See CONTRIBUTING.md.

License

This project is licensed under the MIT license. See LICENSE.