Skip to content

Deployment guide

Jump to bottom
Zaki Amin edited this page Dec 19, 2024 · 13 revisions

Running locally

Environment variables

To begin, create a copy of .env.template called .env located at the root level of the project. Follow the instructions from the template and copy the values of the environment variables from the impaas app where needed.

For the DATABASE_URL environment variable, create a local PostgreSQL database and use its connection string.

Instructions

  1. Set up environment variables as described before
  2. npm install: install necessary packages
  3. npx prisma migrate reset: apply migrations and populate the database with seed data. To leave the database empty, use the skip-seed option
  4. npm run dev: run the server
  5. (optional, in another terminal) npx prisma studio: nice, interactive web view of the database

Setting up SSO with Microsoft Entra

  1. Visit the Microsoft Entra portal and move to tab Applications -> App registrations from the sidebar.
  2. Register a new app with New registration from the toolbar. Choose an application name and set the account types to Accounts in this organizational directory only. Set up 2 redirect URIs with type Web and the URLs http://localhost:3000/api/auth/callback/microsoft-entra-id and https://ug-admissions.impaas.uk/api/auth/callback/microsoft-entra-id.
  3. Confirm the details. Copy Application (client) ID into the environment variable AUTH_MICROSOFT_ENTRA_ID_ID. Copy the value of Directory (tenant) ID into https://login.microsoftonline.com/<tenant_id>/v2.0 for environment variable AUTH_MICROSOFT_ENTRA_ID_ISSUER.
  4. Navigate to Certificates & secrets and click New client secret on the toolbar. Enter any description and set the expiration to 6 months (NB: a new client secret must therefore be generated in 6 months). The Add button will then generate a secret which is the value for environment variable AUTH_MICROSOFT_ENTRA_ID_SECRET.
  5. The last authentication environment variable, AUTH_SECRET, is generated by running npx auth.

GitHub set up

Pipeline

The pipeline can be found here. The steps are as follows: type checking, style checking, linting, building + pushing image, deploying to impaas and applying migrations.

Secrets

There are 2 repository actions secrets which must be set manually on GitHub.

  • DATABASE_URL allows migrations to be executed by a GitHub runner. It should have the exact same value as the identically named DATABASE_URL environment variable.
  • TSURU_TOKEN is for the pipeline to authenticate with impaas / tsuru. This must be obtained from impaas by someone with elevated permissions on impaas itself.

Deploying to production with impaas (tsuru)

Note that impaas is an alias for tsuru so either can be used

Installation, team and app set-up

  1. Install impaas as described here 
curl -fsSL "https://tsuru.io/get" | bash
echo "alias impaas='tsuru'" >> ~/.bashrc
source ~/.bashrc
  1. Login: impaas login
  2. Create a new team: impaas team create <team_name>
  3. Add any members to the team as required: impaas role-assign team-member <email_address> <team_name>
  4. Create a new app within that team: impaas app create <app_name> --team <team_name>
  5. Create a token for the team with impaas token create --id <token_name> --team <team_name> --description "CI token"
  6. Assign the token the team-deployer role to give it sufficient permissions for deployment: impaas role-assign team-deployer <token_name>

If using an impaas database, follow these additional instructions

  1. Create Postgres service: impaas service-instance-add postgres <db_name>
  2. Bind Postgres service to app: impaas service-instance-bind postgres <db_name> -a <app_name>

Useful commands

  • View app information: impaas app info -a <app_name>
  • View logs of the app running: tsuru app log -a <app_name>

Injecting environment variables

When using impaas as the means of deploying the application, most environment variables found in .env will need to be manually injected.

The command tsuru env get -a <app_name> displays all the set environment variables in the application <app_name>. The postgres and tsuru environment variables are automatically set and managed.

Any missing environment variables should be set with the command tsuru env set <ENV_VAR_NAME>=<env_var_value> -a <app_name>. The variables which will need to be set are AUTH_MICROSOFT_ENTRA_ID_ID, AUTH_MICROSOFT_ENTRA_ID_ISSUER, AUTH_MICROSOFT_ENTRA_ID_SECRET, AUTH_SECRET and NEXT_PUBLIC_UGA_ADMINS. The last environment variable is prefixed with NEXT_PUBLIC_ because it must be available to the browser.

Clone this wiki locally