hmpps-find-and-refer-an-intervention-ui

This repository contains the ui code for the Find and Refer an Intervention UI.

Required software

Most software can be installed using homebrew.

• Docker
• Node (>=22)

Running the application locally

After setting up the dependencies (below), run the application locally with with:

npm run start:dev

The dev server comes with Hot Module Reloading (reloads and restarts when any file changes are detected)

Docker

This project includes docker compose files to start the required dependencies for running the UI locally.

Run the following command to pull the relevant dependencies for the project.

docker-compose pull

and then the following command to run the containers.

docker-compose up

can optionally be run in detached mode in order to retain terminal use

docker-compose up -d

Environment Files (.env)

Node requires a .env file to start the application, but the project does not make heavy use of environmental variables.

Before starting the application create a new blank .env file by either creating a blank .env file:

touch .env

or copying the example file:

cp .env.example .env

Connecting to local database

The service uses a postgres database alongside flyaway migrations to create and populate the database. To connect to the database locally in your preferred database client (IntelliJ Ultimate, Dbeaver, Pgadmin, etc).

Create new connection using local database credentials;

Variable	Value
Port	5432
Username	root
Password	dev

Authorization and Authentication

The service uses an Oauth 2.0 setup managed through the Hmpps Auth project. To call any endpoints locally a bearer token must be generated. This can be done through calling the auth endpoint in the Hmpps-auth service.

Variable	Value
Grant type	Client credentials
Access token URL	http://hmpps-auth:8090/auth/oauth/token
Client ID	hmpps-find-and-refer-an-intervention-ui-client
Client Secret	clientsecret
Scope	Read

For Client ID and Secret refer to the relevant credentials for the Find and Refer Project.

Client Credentials flow

These are used by the application to request tokens to make calls to APIs. These are system accounts that will have their own sets of roles.

Most API calls that occur as part of the request/response cycle will be on behalf of a user.

To make a call on behalf of a user, a username should be passed when requesting a system token. The username will then become part of the JWT and can be used downstream for auditing purposes.

These tokens are cached until expiration.

These credentials are configured using the following env variables:

• CLIENT_CREDS_CLIENT_ID
• CLIENT_CREDS_CLIENT_SECRET

System tokens are obtained by making a call to HMPPS-Auth using the username of the logged in user. This token can then be added to the appropriate rest client calling to another service.

Logging in with a test user

Once the application is running you should then be able to login with:

Community User username: REFER_MONITOR_PP password: R8Mpassword

Custody User username: FRI_USER_ACP_REF_TEAM password: password123456

Extra commands

Run linter

• npm run lint runs eslint.
• npm run typecheck runs the TypeScript compiler tsc.

Run unit tests

npm run test

Deployments

Deployments are part of our CI process, on the main branch using the build-test-and-deploy Workflow.

This is a link to the most recent runs of that Workflow.

Deployments require a manual approval step.

Testing a Deployment

The Find & Refer an Intervention Service is not presently live. We therefore do not have a Production environment available.

It is only possible to do User Acceptance Testing (UAT), i.e. click around a browser, on our Dev environment.

To test a deployment to production, we have to examine the logs of a pod, to assert if it has spun up successfully or not. This is obviously not ideal.

Kubernetes

All deployments and environments are managed through Kubernetes.

For information on how to connect to the Cloud Platform's Kubernetes cluster follow the setup guide here.

For further Kubernetes commands a useful cheat sheet is provided here. Similarly, the --help flag on any kubectl command will give you more information.

Testing a Deployment

1. Find the deployments in the hmpps-find-and-refer-an-intervention-prod namespace:

$ kubectl get deployments -n hmpps-find-and-refer-an-intervention-prod

NAME                                           READY   UP-TO-DATE   AVAILABLE   AGE
hmpps-find-and-refer-an-intervention-service   0/0     0            0           41d
hmpps-find-and-refer-an-intervention-ui        2/2     2            2           41d

If you have done a deployment of UI, there should be more than 0 Pods marked as READY in that response, indicating that they have, indeed, been spun up.

2. Double-check the Pod(s) associated with the Deployment:

Per Kubernete's docs:

A Pod is similar to a set of containers with shared namespaces and shared filesystem volumes.

View the Pods in the namespace, these are what the READY column in the get deployments refer to:

$ kubectl get pods -n hmpps-find-and-refer-an-intervention-prod

NAME                                                       READY   STATUS    RESTARTS   AGE
hmpps-find-and-refer-an-intervention-ui-58b989489d-blprx   1/1     Running   0          2m49s
hmpps-find-and-refer-an-intervention-ui-58b989489d-mkb7p   1/1     Running   0          2m49s

3. Check the logs of a Pod

It is possible to read the logs of a given Pod to check that the build and spin-up process for the Pod has been successful.

To view the logs from any of the Pods whose name is given in the previous responses:

$ kubectl logs $POD_NAME --namespace hmpps-find-and-refer-an-intervention-prod

# ...
Application Insights 2.X SDK. []
14:25:13.500Z  INFO HMPPS Find And Refer An Intervention Ui: Server listening on port 3000

Where $POD_NAME is the full string Pod name given in the get pods response.

4. Scale down the Pods

While we are in pre-release, it's important not to leave the pods running.

We scale down the number of running Pods in the Kubernetes deployment with the following:

$ kubectl scale deployment hmpps-find-and-refer-an-intervention-ui --namespace hmpps-find-and-refer-an-intervention-prod --replicas=0

deployment.apps/hmpps-find-and-refer-an-intervention-ui scaled

And then double-check this has taken effect:

$ kubectl get deployments --namespace=hmpps-find-and-refer-an-intervention-prod

NAME                                           READY   UP-TO-DATE   AVAILABLE   AGE
hmpps-find-and-refer-an-intervention-service   0/0     0            0           41d
hmpps-find-and-refer-an-intervention-ui        0/0     0            0           41d

By checking for the 0 in the READY column.

Change log

A changelog for the service is available here

Troubleshooting

For any issues please reach out to the Find and Refer Interventions team in slack #find-refer-interventions-team