Residential locations

This application is a front-end application used by staff in HMPPS prisons to view and maintain incident reports.

It is backed by hmpps-locations-inside-prison-api.

Running locally

The application needs a suite of services to work.

Requirements

This application is built for Node.js and docker will be needed to run it locally. nvm or fnm can be used to install appropriate node versions, e.g.:

nvm use
# or
fnm use

Additional tools are required to manage deployment: kubectl and helm.

Using services in dev environment

This is the easiest way to run and develop on your machine: by hooking into services that already exist in the dev environment.

Run the application in development mode:

• in separate shell sessions, for local development
  • This will automatically restart it if server code or front-end assets are modified.

cp .env.sample .env
docker compose -f docker-compose.yml up
npm run start:dev

• all in one, for preview:

docker compose -f docker-compose.yml --profile include-frontend up --build

Dev logins

username	password	roles
LOCATION_RO	password123456	VIEW_INTERNAL_LOCATION
LOCATION_CAP	password123456	VIEW_INTERNAL_LOCATION MANAGE_RES_LOCATIONS_OP_CAP
LOCATION_MAINTAIN	password123456	VIEW_INTERNAL_LOCATION MANAGE_RES_LOCATIONS_OP_CAP MANAGE_RESIDENTIAL_LOCATIONS

Updating dependencies

It’s prudent to periodically update npm dependencies; continuous integration will occasionally warn when it’s needed. Renovate (similar to dependabot) is set up to try to upgrade npm packages, base docker images, helm charts and CircleCI orbs by raising pull requests.

Testing

Continuous integration on CircleCI will always perform the full suite of tests on pull requests and branches pushed to github, but they can be run locally too.

Unit tests

Run unit tests using:

npm test

…optionally passing a file path pattern to only run a subset:

npm test -- authorisationMiddleware

Integration tests

Run the full set of headless integration tests, in separate shell sessions:

docker compose -f docker-compose-test.yml up
npm run start-feature
npm run int-test

Integration tests can also be run in development mode with a UI so that assets are rebuilt when modified and tests will re-run:

docker compose -f docker-compose-test.yml up
npm run start-feature
npm run int-test-ui

Code style tests

Type-checking is performed with:

npm run typecheck

Prettier should automatically correct many stylistic errors when changes are committed, but the linter can also be run manually:

npm run lint

Security tests

Continuous integration will regularly perform security checks using nm security audit, trivy and veracode.

The npm audit can be run manually:

npx audit-ci --config audit-ci.json

Hosting

This application is hosted on Cloud Platform in three environments: dev (continuously deployed and experimental; for general testing), preprod (largely matches the live service; for pre-release testing) and prod (the live service).

The environments are distinct namespaces defined using a combination of kubernetes resources and terraform templates:

• dev
• preprod
• prod

A shared HMPPS helm chart forms the basis of releases, setting up a deployment, service, ingress and associated policies and monitoring rules.

See /helm_deploy/.

Deployment

When the main branch is updated (e.g. when a pull request is merged), a new version of the application is released to dev automatically by CircleCI. This release can be promoted to preprod and prod using the CircleCI interface.

See /helm_deploy/README.md for manual deployment steps.

Monitoring

There is a suite of tools used for monitoring deployed applications:

• Kibana – logging
• Azure Application Insights – application profiling and introspection
• Prometheus – application and request metrics
• Alertmanager – alerts based on metrics

References

The code in this repository uses the MIT licence.

• MoJ security guidance
• MoJ technical guidance