Opal Fines Service

Getting Started

Prerequisites

• JDK 21
• Docker

Building and deploying the application

Running the application

Environment variables

The following environment variables are required to run the service.

AAD_CLIENT_ID= <Ask Team Memebers>
AAD_CLIENT_SECRET=<Ask Team Memebers>
AAD_TENANT_ID=<Ask Team Memebers>
OPAL_TEST_USER_PASSWORD=<Ask Team Memebers>

LAUNCH_DARKLY_SDK_KEY=<Ask Team Memebers>

You can also create a shared .env.shred file with these variables you can use the create_env.sh script from opal-shared-infrastructure: But these will only get picked up when running the application with docker. So for local development, you will need to set these environment variables in your IDE run configuration or terminal session.

../opal-shared-infrastructure/bin/create_env.sh

Caching

Redis has been configured as the default caching provider. When running docker-compose with the local configuration a Redis container will be started.

If starting the opal-fines-service from Intellij or the command line you have the following options: Follow instructions under 'Running the application locally'

In local env by default opal-fines-service uses simple cache instead of Redis cache. This can be enabled by setting this env variable:

OPAL_REDIS_ENABLED=true

Alternatively the opal-fines-service can be run using a simple in-memory cache by starting the application with the profile in-memory-caching.

To view the cache - when running against local Redis - Intellij has a free plugin called Redis Helper. However, if you want to view the cache in staging the plugin doesn't support SSL. Instead, install:

brew install --cask another-redis-desktop-manager
sudo xattr -rd com.apple.quarantine /Applications/Another\ Redis\ Desktop\ Manager.app

You can also run redis container in local docker: (Not required if using Approach 4 as this spins up all your dependencies) Bash:

  docker-compose up redis

Zsh:

  docker compose up redis

WARNING - As of 10/02/2026 the recommended docker approach is "Approach 4: Docker with external dependencies"

Approach 1: Dev Application (No existing dependencies)

The simplest way to run the application is using the bootTestRun Gradle task:

  ./gradlew bootTestRun

This task has no dependencies and starts up a Postgres database in Docker using Testcontainers. The database is available on jdbc:postgresql://localhost:5432/opal-fines-db with username and password opal-fines.

To persist the database between application restarts set the environment variable TESTCONTAINERS_REUSE_ENABLE to true. Note this does not persist data if the Docker container is manually stopped, or through laptop restarts).

Approach 2: Dev Application (With existing dependencies)

Use the standard Spring Boot run Gradle task:

  ./gradlew run

This approach can be used if a database is already running and may be preferred if the lack of long-term data persistence from the previous approach is an issue for development.

Approach 3: Docker

Create the image of the application by executing the following command:

  ./gradlew assemble

Create docker image:

Bash:

  docker-compose build

Zsh:

  docker compose build

Run the distribution (created in build/install/opal-fines-service directory) by executing the following command:

Bash:

  docker-compose up

Zsh:

  docker compose up

To skip all the setting up and building with Docker, just execute the following command:

./bin/run-in-docker.sh

For more information:

./bin/run-in-docker.sh -h

Script includes bare minimum environment variables necessary to start api instance. Whenever any variable is changed or any other script regarding docker image/container build, the suggested way to ensure all is cleaned up properly is by this command:

Bash:

docker-compose rm

Zsh:

docker compose rm

It clears stopped containers correctly. Might consider removing clutter of images too, especially the ones fiddled with:

docker images

docker image rm <image-id>

There is no need to remove postgres and java or similar core images.

Approach 4: Docker with external dependencies (e.g. Redis, postgres, azure service bus, user service, logging service, etc) - Recommended approach for development

Ensure you have pulled opal-shared-infrasturcutre as this contains scripts to support docker.

First you will need to ensure you have all repositories downloaded in the same parent direcotry. To do this automatically you can run the following command from the opal-shared-infrastructure directory:

../opal-shared-infrastructure/bin/pull_all_repos.sh

Secondly you will need to ensure you have the required environment variables set up in a .env.shared file in the opal-shared-infrastructure/docker-files/ directory. You can use the following command to create this file with the required variables:

../opal-shared-infrastructure/bin/create_env.sh

Finally to run the application with all external dependencies using docker you can run the following command from the opal-shared-infrastructure directory:

../opal-shared-infrastructure/docker-files/scripts/opalBuild.sh -lb

Full details of this script and the arguments can be found within the opal-shared-infrastructure repository

• Link to file on Github
• Link to file locally

Verifying application startup

Regardless of approach followed for starting the application, in order to test if the application is up, you can call its health endpoint:

  curl http://localhost:4550/health

You should get a response similar to this:

  {"status":"UP","diskSpace":{"status":"UP","total":249644974080,"free":137188298752,"threshold":10485760}}

Building the application

The project uses Gradle as a build tool. It already contains ./gradlew wrapper script, so there's no need to install gradle.

To build the project execute the following command:

  ./gradlew build

Manual api testing (Postman)

Within the project's postman directory is an importable script to set up api tests in the Postman app. Current tests cover the following apis:

PUT http://localhost:4550/api/defendant-account Create a new or update an existing Defendant Account in OPAL

GET http://localhost:4550/api/defendant-account?businessUnitId=${Short}&accountNumber=${String} Get an existing Defendant Account by business Unit ID and Account Number.

OpenAPI

The OpenAPI specification is available publicly (see badge at top of README) and when running the application at /swagger-ui/index.html. When running locally this is available at http://localhost:4550/swagger-ui/index.html.

Style rules

This project we use a common set of styles rules to ensure all changes follow the same structure. These rules are outlined in the project's style file located at .idea/codeStyles/Project.xml

To ensure we are following the same styles you will need to enable this project style on your IDE to do this following the below instructions.

Step 1: To to your InteliJ Settings

Step 2: Go to the 'Code Styles' tab

Step 3: Ensure the global scheme is set to 'Project' under the 'Stored in Project' heading.

Azure Service Bus emulator

Some functionality of the application depends on Azure Service Bus. To run and test this functionality locally, you can use an emulator for Azure Service Bus. This is already bundled with the docker-compose setup.

To view any messages sent to the queues/topics you can use a tool like 'Azure Service Bus Explorer'. Or you can use the PeekSbEmulator class that is setup in test/java/uk/gov/hmcts/opal/support/PeekSbEmulator.java to do this simply call the main method of this class you can add a argument to specify which queue/topic you want to peek messages from.

License

This project is licensed under the MIT License - see the LICENSE file for details