Teaching Website Backend

The backend for our teaching website.

Run the Project with VS Code

The Project is ready to be used with dev containers. You only need a recent version of Docker. Then you can reopen the project in a devcontainer (Ctrl+Shift+P > Dev Containers: Reopen in Container).

Setup your local env:

cp .example.env .env

and fill in the values for USER_ID and USER_EMAIL in the .env file:

The USER_ID and USER_EMAIL are used only for seeding the database and are not strictly needed. The USER_ID is the ID attribute from the response of Graph-Explorer/v1.0/me - you need to log in first...

(since the DATABASE_URL is automatically generated by the devcontainer, you should not set DATABASE_URL yourself)

Before the first startup, setup the local dev db:

yarn run db:migrate
yarn run db:seed

and then start the server with

yarn run dev

Environment Variables

Variable	Env	Description	Example
USER_EMAIL	dev	The email of the user to be created on seeding.	reto.holz@gbsl.ch
USER_ID	dev	The UUID of the user to be created on seeding. *	fc0dfc19-d4a3-4354-afef-b5706046b368
PORT		(optional) The port the server should listen on.	3002 (default)
SESSION_SECRET		The secret for the session cookie. Generate with openssl rand -base64 32	secret
MSAL_CLIENT_ID		The client id for the web api from Azure.
MSAL_TENANT_ID		The Tenant ID from your Azure instance
APP_NAME		The name of the app. Used for the cookie name prefix {APP_NAME}ApiKey	xyzTeaching, default: twa
ADMIN_USER_GROUP_ID		The UUID of the group that should be used as the admin group. For this group a RW-Permission will be always added to a newly created document root when it's access is not RW	default: ""
GITHUB_CLIENT_SECRET		Used for the CMS to work properly. Register an app under https://github.com/settings/apps.
GITHUB_CLIENT_ID
GITHUB_REDIRECT_URI
DATABASE_URL	prod	The URL to connect to the PostgreSQL database.	postgresql://{user}:{pw}@localhost:5432/{db_name}
ALLOWED_ORIGINS	prod	A comma-separated list of origins allowed to access the api. E.g. teaching-dev.gbsl.website	localhost:3000
ALLOW_SUBDOMAINS	prod	Wheter subdomains from ALLOWED_DOMAINS should be granted access too.	false
NETLIFY_PROJECT_NAME	prod	When set to the netlify project name (e.g. teaching-dev), the app will allow requests from https://deploy-preview-\d+--teaching-dev.netlify.app and use sameSite=none instead of strict.
SENTRY_PROJECT	prod	Error Tracking: Sentry Project Name, e.g. events-api.
SENTRY_ORG	prod	Error Tracking: Sentry Organisation, e.g. your sentry username.
SENTRY_DSN	prod	Error Tracking: Sentry DSN.
SENTRY_AUTH_TOKEN	prod	Error Tracking: Auth token for uploading sourcemaps to sentry. Get it by configuring your app with npx @sentry/wizard@latest -i sourcemaps.
SENTRY_TRACES_SAMPLE_RATE	prod	Sampling rate for Sentry traces.	0.1 (default)

* When using MSAL Auth, log in and get your id from https://developer.microsoft.com/en-us/graph/graph-explorer.

These variables are stored in a .env file in the root directory. Make sure to not check this file into version control.

Database

Database Views

The access policies and users documents are implemented as database views. To keep track of views and changes, make sure to use yarn db:migrate-views when changing views:

1. Edit or create a new view file in prisma/view-migrations/views/.
2. Make sure the dependencies are correct in migrate.config.yml.
3. Run yarn db:migrate-view to create a new migration for the changed views (this won't run prisma migrate:dev, it only creates the migration files).
4. Eventually change the schema.prisma file to reflect changes in the views (e.g. new fields).
5. Run yarn run prisma migrate:dev to create a new migration for the schema changes.

Warning

Never edit views directly in a prisma migration file (under prisma/migrations/), as these files are auto-generated and will be overwritten the next time yarn db:migrate-views is run.

DB Scripts

# Run all prisma migrations:
yarn db:migrate      # equivalent to yarn run prisma migrate deploy
yarn db:migrate:dev  # equivalent to yarn run prisma migrate dev
yarn db:seed         # * seeds some basic *users*, *documents* and *groups*
yarn db:reset        # resets the database (drops all tables and types)
yarn db:recreate     # resets, migrates and seeds the database
yarn run prisma generate    # generates the prisma client (sometimes needed after changing the schema)

the seed file is located in prisma/seed.ts. It will create

• a user for USER_EMAIL and USER_ID from the .env file (if present)
• a test user foo@bar.ch with the uuid 4e90b891-7e31-4a49-9ac7-a71a0ad6863a
• a group test_group with the memebers

Dump from production

When running inside VSCode DevContainer and have configured a git remote called dokku pointing to the production server, you can dump the production database and restore it locally with the following commands:

dokku postgres:export dev-teaching-api > tdev-backup.dump
psql -U postgres -h localhost -c 'drop database if exists teaching_api;'
psql -U postgres -h localhost -c 'create database teaching_api;'
pg_restore -h localhost --verbose --clean --no-owner --no-privileges -U postgres -d teaching_api < tdev-backup.dump
yarn run prisma migrate dev

Prisma Studio

Run Prisma Studio - a simplistic local database viewer - with

yarn run prisma studio

Undo last migration (dev mode only!!!!)

[!WARNING] Only do this in development, otherwise data loss is possible.

psql -d teaching_api -h localhost -U postgres

(Password is set inside docker-compose.yml)

-- delete last migration
DELETE FROM _prisma_migrations WHERE started_at = (SELECT MAX(started_at)FROM _prisma_migrations);

-- undo your migration, e.g. drop a view or remove a column
drop view view_name; -- drop view
ALTER TABLE table_name DROP COLUMN column_name; -- drop column
-- disconnect
\q

Code Formatting

For a consistent code style, the project uses Prettier. To format the code, run

yarn run format

to format all typescript files.

Dokku

See tdev docs

Troubleshooting Unknown buildpack version

docker pull gliderlabs/herokuish:latest
# when this does not help, try additionally:
dokku buildpacks:set-property <APP> stack gliderlabs/herokuish:latest
dokku repo:purge-cache <APP>

Speed Improvements

If the API and the Database are running on the same server, you can improve the speed by disabling the tcp connection for the database. This can be done by setting the DATABASE_URL to postgresql://teaching_website:teaching_website@localhost/teaching_website?sslmode=disable.

CMS

For the cms to work properly, you need to register a github app under https://github.com/settings/apps. The following settings are required:

• Callback URL:
  • http://localhost:3000/gh-callback for local development
  • https://teaching-dev.domain.ch/gh-callback for the productive environment
  • No whitelist-URL's can be added, so you'd need to add for each deploy-preview a separate url...