README.md

PCGL DACO API

Node.js Express API for the Pan-Canadian Genome Library's Data Access Compliance Office.

This app uses features from Node ^20.9, in combination with TSX for TypeScript support, and it provides access to a Postgres database using Drizzle ORM.

Local Development

The easiest way to run the DACO UI is by following the general setup instructions from the workspace README.

To run the DACO API requires a Postgres database connection. The workspace's docker-compose provides a Postgres container that is pre-configured to work with the default environment variables.

Follow these steps to prepare your local machine to run this application from source:

1. Install all npm dependencies: pnpm i
2. Run Docker dependencies. From the root of this workspace: docker-compose up -d
3. Initialize this repository: pnpm setup
   1. Creates a .env and .env.docker file with default values. Update the values in this file if you need to change the application configuration.
   2. Runs migrations to setup database
4. Start application: pnpm dev

Environment Variables

DACO requires multiple services to be running to be used, importantly the clinical-submission service. Clinical-Submission requires environment variables to be set to function properly. Clinical-submission service environment variables are defined in two locations: .env.docker and the docker-compose.yml file itself. The purpose of the division of variable locations is to separate the environment variables that are sensitive from those that are not. Environment variables in the docker-compose.yml file are values that are not sensitive and can be shared with others, the values by default show automatically work without any additional configuration(unless needed for your specific use-case).

The following sub-sections list the environment variables that can be set to configure the DACO API. If the property is listed as required, the app will fail to run without a value being provided to the server's runtime environment.

Environment Variables DACO

Name	Description	Type	Required	Default
APPROVED_PERMISSION_EXPIRES_IN_DAYS	Number of days the applicant will have read access to the study when application gets approved.	number	Optional	365
AUTH_CLIENT_ID	Client ID for OIDC Provider registered private client.	string	Conditional DISABLE_AUTH !== true
AUTH_CLIENT_SECRET	Client Secret for OIDC Provider registered private client.	string	Conditional DISABLE_AUTH !== true
AUTH_PROVIDER_HOST	OIDC Provider host URL.	string	Conditional DISABLE_AUTH !== true
AUTHZ_ENDPOINT	Authorization server endpoint.	string	Conditional DISABLE_AUTH !== true
AUTHZ_FETCH_RETRIES	Number of times to retry a failed fetch request URL.	number	Optional	2
AUTHZ_FETCH_RETRY_DELAY_MS	Delay in milliseconds between retry attempts. URL.	number	Optional	500
AUTHZ_FETCH_TIMEOUT_MS	Maximum time in milliseconds to wait for a fetch request before timing out. URL.	number	Optional	10000
AUTHZ_GROUP_ADMIN	Authorization group for admins.	string	Conditional DISABLE_AUTH !== true
AUTHZ_GROUP_PREFIX_DAC_MEMBER	Authorization group for DAC members.	string	Conditional DISABLE_AUTH !== true
AUTHZ_GROUP_PREFIX_DAC_CHAIR	Authorization group for DAC chair.	string	Conditional DISABLE_AUTH !== true
AUTHZ_SERVICE_ID	Authorization Service ID.	string	Conditional DISABLE_AUTH !== true
AUTHZ_SERVICE_UUID	Authorization Service UUID.	string	Conditional DISABLE_AUTH !== true
DISABLE_AUTH	Set this to true to disable auth. Any other value and this will default to auth enabled.	boolean	Optional	false
PG_DATABASE	Postgres database name.	string	Required
PG_HOST	Postgres database host address.	string	Required
PG_PASSWORD	Postgres database password.	string	Required
PG_USER	Postgres database user name.	string	Required
PORT	Port number this service will listen to.	number	Optional	3000
SESSION_KEYS	Secret keys to use to encrypt and validate session tokens. This can be a single key or multiple keys as a comma separated list. The first key will be used for encrypting new tokens, the rest can be used to validate existing keys. An array of values can be used to rotate session secrets without invalidating existing sessions.	string	Required
SESSION_MAX_AGE	Number of miliseconds that a session token will remain active. Must be an integer.	number	Optional	30 minutes
VALKEY_HOST	Valkey host address.	string	Required
VALKEY_PASSWORD	Valkey user password.	string	Required
VALKEY_PORT	Valkey port.	number	Required
VALKEY_USER	Valkey user name.	string	Required

Environment Variables .env.docker

Name	Description	Default
AUTH_CLIENT_ID	Used to identify the application to the authentication server. Required when AUTH_ENABLED is enabled.
AUTH_CLIENT_SECRET	A secret value used to authenticate the application with the authentication server. Required when AUTH_ENABLED is enabled.
AUTH_PROVIDER_HOST	The domain or IP address of the authentication server. Required when AUTH_ENABLED is enabled.
AUTH_PROTECT_METHODS	Specifies a list of HTTP methods to protect, separated by commas. (Example: DELETE,GET,POST,PUT).	'DELETE,GET,POST,PUT'
AUTHZ_ENDPOINT	The domain or IP address of the authorization server. Required when AUTH_ENABLED is enabled.
AUTHZ_GROUP_ADMIN	Authorization group configuration for determining admin group
AUTHZ_SERVICE_ID	Authorization Service ID.
AUTHZ_SERVICE_UUID	Authorization Service UUID.

Unit Testing

• Unit tests are built using the Node Test Runner and are triggered using pnpm run test

Database

• This application implements a Postgres database based on the following data model and managed by Drizzle ORM
• There is a known issue when using pnpm drizzle-kit generate / pnpm drizzle-kit migrate for future migrations. generate may work but migrate can throw an error that a given enum is already defined: drizzle-team/drizzle-orm#3206
  • The current work around is to run pnpm drizzle-kit generate, then use pnpm drizzle-kit up to update the Drizzle snapshots.
• A schema dbml (database markup language) file can be generated using the script pnpm run dbml. This file is found at ./src/db/schema.dbml.