hmpps-electronic-monitoring-create-an-order

Contents

• About this project
• Running the app
  • Dependencies
  • Running the application locally
    • One-time setup:
    • Every-time setup:
• Running both the UI and the API locally
• Code quality checks
  • Run linter
  • Run tests
    • Running integration tests
• Change log

About this project

A service to allow users to Create Electronic Monitoring Orders. This Typescript front-end application is the user interface for the HMPPS Create an Electronic Monitoring Order API.

Running the app

The easiest way to run the app is to use docker compose to create the service and all dependencies.

docker compose pull

docker compose up

Dependencies

The app requires:

• hmpps-auth - for authentication
• redis - session store and token caching

Running the application locally

One-time setup:

• Create a personal client in the development environment of DPS with the roles ROLE_EM_CEMO__CREATE_ORDER and ROLE_EM_CEMO__CREATE_DEVICE_WEARER.
  • This service uses HMPPS Auth in development when run locally. Accordingly, to access the service locally you must first have a personal client created in the dev environment of DPS with the relevant roles. You’ll use this to log into the service, including locally.
  • To do this, you must submit a personal client request by cloning the request template and asking for a review on the HMPPS Auth and Audit slack channel.
• Create a .env file in the root level of the repository with the following contents. Replace the Client IDs and Client Secrets with values from Kubernetes secrets.

PORT=3000
HMPPS_AUTH_URL=https://sign-in-dev.hmpps.service.justice.gov.uk/auth
HMPPS_AUTH_EXTERNAL_URL=https://sign-in-dev.hmpps.service.justice.gov.uk/auth
TOKEN_VERIFICATION_API_URL=https://token-verification-api-dev.prison.service.justice.gov.uk
REDIS_ENABLED=false
NODE_ENV=development
TOKEN_VERIFICATION_ENABLED=true
API_CLIENT_ID=[REPLACE WITH API_CLIENT_ID]
API_CLIENT_SECRET=[REPLACE WITH API_CLIENT_SECRET]
SYSTEM_CLIENT_ID=[REPLACE WITH SYSTEM_CLIENT_ID]
SYSTEM_CLIENT_SECRET=[REPLACE WITH SYSTEM_CLIENT_SECRET]
ENVIRONMENT_NAME=DEV
CEMO_API_URL=http://localhost:8080

• Use the command env to check that the environment variables are in your current shell session. If any of them aren't listed, then load the environment variables into your current shell session using export $(cat .env)
• Install dependencies using npm install, ensuring you are using node v20
  • Note: Using nvm (or fnm), run nvm install --latest-npm within the repository folder to use the correct version of node, and the latest version of npm. This matches the engines config in package.json and the CircleCI build config.

Every-time setup:

1. To start the main services, excluding the example typescript template app and hmpps auth:

   docker compose up --scale=app=0 --scale=hmpps-auth=0

2. And then, to build the assets and start the app with esbuild:

   npm run start:dev

3. Access the service via http://localhost:3000, using your dev environment DPS personal credentials to sign in at the sign in page.

Running both the UI and the API locally

Instructions for this can be found in the readme of the Create an EM Order API repo.

Code quality checks

Run linter

npm run lint

Run tests

npm run test

Running integration tests

1. For local running, start a test db and wiremock instance by:

   docker compose -f docker-compose-test.yml up

2. Then run the server in test mode by:

   npm run start-feature (or npm run start-feature:dev to run with auto-restart on changes)

3. And then either:

   • run tests in headless mode with npm run int-test
   • Or run tests with the cypress UI npm run int-test-ui

Running end-to-end scenarios against the CEMO API

1. For local running, start an API, test db and wiremock instance by:

   docker compose -f docker-compose-scenarios.yml up

2. Then run the server so that it can connect to the services in the docker network:

   npm run start-scenarios (or npm run start-scenarios:dev to run with auto-restart on changes)

3. And then either:

   • run scenario tests in headless mode with npm run int-scenarios
   • Or run tests with the cypress UI npm run int-test-ui

Change log

A changelog for the service is available here