hmpps-electronic-monitoring-datastore-api

Contents

• About this project
• Get started
  • Using IntelliJ IDEA
• Usage
  • Running the application locally
    • Calling endpoints
      • Generate a token for a HMPPS Auth client
    • Running the application locally with the UI

About this project

An API used by the Electronic Monitoring datastore UI, a service that allows users to interrogate the electronic monitoring datastore hosted in the HMPPS Modernisation Platform.

It is built using Spring Boot and Kotlin as well as the following technologies for its infrastructure:

• AWS - Services utilise AWS features through Cloud Platform.
• CircleCI - Used for our build platform, responsible for executing workflows to build, validate, test and deploy our project.
• Cloud Platform - Ministry of Justice's (MOJ) cloud hosting platform built on top of AWS which offers numerous tools such as logging, monitoring and alerting for our services.
• Docker - The API is built into docker images which are deployed to our containers.
• Kubernetes - Creates 'pods' to host our environment. Manages auto-scaling, load balancing and networking to our application.

Get started

Using IntelliJ IDEA

When using an IDE like IntelliJ IDEA, getting started is very simple as it will handle installing the required Java SDK and Gradle versions. The following are the steps for using IntelliJ but other IDEs will prove similar.

1. Clone the repo with the following command;

git clone [email protected]:ministryofjustice/hmpps-electronic-monitoring-datastore-api.git

2. Launch IntelliJ and open the hmpps-electronic-monitoring-datastore-api project by navigating to the location of the repository.

Upon opening the project, IntelliJ will begin downloading and installing necessary dependencies which may take a few minutes.

3. Enable pre-commit hooks for formatting and linting code with the following command;

./gradlew addKtlintFormatGitPreCommitHook addKtlintCheckGitPreCommitHook

Usage

Running the application locally from the CLI

The application comes with a dev spring profile that includes default settings for running locally. This is not necessary when deploying to kubernetes as these values are included in the helm configuration templates - e.g. values-dev.yaml.

Checking the app has started successfully:

If using docker, your app is probably exposed at localhost:8080.
Call http://localhost:8080/health with a browser to get app health info.

Running with Docker

There is also a docker-compose.yml that can be used to run a local instance of the template in docker and also an instance of HMPPS Auth (required if your service calls out to other services using a token).

docker compose pull && docker compose up

will build the application and run it and HMPPS Auth within a local docker instance.

Running the application locally using Intellij

1. Run docker compose pull && docker compose up --scale hmpps-electronic-monitoring-datastore-api=0 , which will just start a docker instance of the database and HMPPS Auth.

2. Click the drop-down button for the HmppsElectronicMonitoringDatastoreApi run configuration file in the top right corner, and select Edit Configurations.

   • For the 'Active Profiles' field, put 'local'
   • You may also need to set the JDK to openjdk-23 or openjdk-21
   • Apply these changes

3. Click the run button.

Or, to run the application using the command line:

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Then visit http://localhost:8080/health.

Vulnerability analysis

Gradle includes OWASP dependency checking. Run this locally using:

1. ./gradlew dependencyCheckUpdate --info to update the definitions file
2. ./gradlew dependencyCheckAnalyze --info to run the check. The results will be found in ./build/reports/dependency-check-report.html

To run trivy analysis on the built image locally, run:

1. docker compose build to build the image
2. brew install aquasecurity/trivy/trivy to install trivy
3. trivy image <your image uid> to scan.

Code coverage

This project has Jacoco integrated, and this will run after each test run. The generated report can be found here and can be opened in your browser.

Deployment

Force-push your code to branch deploy-dev to deploy it to dev.
This cannot deploy past dev, but is otherwise the same as the main deployment pipeline.

This is configured in .circleci/config.yml in the hmpps/deploy_env: action for dev.

• main is deployed via CircleCI
• Kubernetes logs can be found on Kibana

Note on remaining TODOs and Examples from template app

We have tried to provide some examples of best practice in the application - so there are lots of TODOs in the code where changes are required to meet your requirements. There is an ExampleResource that includes best practice and also serve as spring security examples. The template typescript project has a demonstration that calls this endpoint as well.

For the demonstration, rather than introducing a dependency on a different service, this application calls out to itself. This is only to show a service calling out to another service and is certainly not recommended!