This is a front-end application used by staff in HMPPS to record someone’s education, skills and work experience; create goals for their time in prison and future employment.
It is a nodeJS application which by default starts up and listens on URL http://localhost:3000
The UI application needs a suite of services to work:
| Dependency | Description | Default | Override Env Var |
|---|---|---|---|
| hmpps-auth | OAuth2 API server for authenticating requests | http://localhost:9090/auth | HMPPS_AUTH_URL |
| education-and-work-plan-api | API to access offender profile details | http://localhost:8083 | EDUCATION_AND_WORK_PLAN_API |
| offender-search | OpenSearch API to find probation offenders | No default | PRISONER_SEARCH_URL |
| postgres | PostgreSQL database server for storing profiles | psql://localhost:5432 | None - required locally |
| redis | Redis cache for user 'session' data (roles) | localhost:6379/tcp | None - required locally |
| nomis-user-roles-api | Authenticate and retrieve user name & email | http://localhost:8097 | NOMIS_USER_ROLES_API_URL |
| curiousApi | Offenders employment, skills and neurodivergence data (3rd party API managed by MegaNexus) | http://localhost:8083 | CURIOUS_API_URL |
More information about the template project including features can be found here.
Some types are imported from the Open API docs for hmpps-education-and-work-plan-api.
You will need to install the node module openapi-typescript globally with the following command:
npm install -g openapi-typescript
To update the types from the Open API docs run the following commands:
npx openapi-typescript https://learningandworkprogress-api-dev.hmpps.service.justice.gov.uk/v3/api-docs -o server/@types/educationAndWorkPlanApi/index.d.ts
Note that you will need to run prettier over the generated files and possibly handle other errors before compiling.
The types are inherited for use in server/@types/educationAndWorkPlanApi/index.d.ts which may also need tweaking for use.
Do not re-import the specs lightly! Reformatting the generated code with prettier is no small task, especially with large specs such as Prisoner Search.
Once the UI is running users will need to authenticate with hmpps-auth using a valid DPS username. The DPS user needs to have the followings roles
dependent on the access/functionality required:
ROLE_EDUCATION_WORK_PLAN_VIEWER- required to be able to perform read only actionsROLE_EDUCATION_WORK_PLAN_EDITOR- required to be able to perform actions that edit/create data
The easiest way to run the app is to use docker compose to create the service and all dependencies.
docker-compose pull (as and when required)
docker-compose up --scale=app=0
The app requires:
- hmpps-auth - for authentication
- redis - session store and token caching
Install dependencies using npm install, ensuring you are using node v20 and npm v10
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.
And then, to build the assets and start the app with nodemon:
npm run start:dev
npm run lint
npm run test
For local running, start a test db, redis, and wiremock instance by:
docker-compose -f docker-compose-test.yml up
Then run the server in test mode by:
npm run start-feature (or npm run start-feature:dev to run with nodemon)
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
The template project has implemented some scheduled checks to ensure that key dependencies are kept up to date.
If these are not desired in the cloned project, remove references to check_outdated job from .circleci/config.yml
Features can be toggled by setting the relevant environment variable.
| Name | Default Value | Type | Description |
|---|---|---|---|
| SOME_TOGGLE_ENABLED | false | Boolean | Example feature toggle, for demonstration purposes. |