Offender Management Allocation Manager

A Ruby On Rails application for allocating Prisoners to Prisoner Offender Managers (POMs).

Dependencies

Versions

See .ruby-version file for the current Ruby version.

Use asdf or similar to manage your ruby environment and sets of dependencies.

Required

direnv - for managing environment variables and storing credentials
Firefox - for specs
geckodriver - for specs
Postgres - for persisting data
Ruby - for running app

Optional

Nomis Elite2 - API for accessing prison, offender and staff information from the National Offender Management Integration System
Nomis Oauth2 Server - for logging into the application

Installing Ruby

The app uses Ruby 3+. Installation is a little tricky on M1 Macs:

Install libyaml: brew install libyaml

Use Brew's libffi, not the system's one: export LDFLAGS="-L/opt/homebrew/opt/libffi/lib" CPPFLAGS="-I/opt/homebrew/opt/libffi/include"

Install with your Ruby version manager: rbenv install 3.y.z

Running The Application

Install Bundler

$ gem install bundler:2.2.28

Install gems locally

$  bundle install

Load govuk and MoJ styles (see package.json)

yarn install

Create a .env file in the root of the folder and add any necessary environment variables (or copy from .env.example). Load your environment variables into your current session ...
Create and seed database

$ bundle exec rails db:setup

Start application

$ bundle exec rails s

Check application status

Visit localhost:3000

Running The Specs

The first time you run the specs you'll need to record the VCR cassettes:

VCR=1 bundle exec rspec

Secrets

Secrets are stored in the secret/allocation-manager-secrets item in each K8s namespace.

So for example, for production, one would do:

kubectl -n offender-management-production get secrets allocation-manager-secrets

These are all managed manually using kubectl. See here for more info

Deploying to preprod and test/test2

preprod and test are deployed environments that can be used as part of the development process. Their purposes are:

preprod - Contains a copy of live data, updated via a script. Only security-cleared personnel can look at it. Deploy here when you need to check WIP code against real data.
test/test2 - Points to the same database as the dev/staging environment, but does not need code to be mainlined to be deployed to. Just like dev/staging, contains synthetic data so does not require SC to access. Deploy here when you need to check WIP code that requires valid NOMIS data.

The method to deploy to these envs is the same. Commit any code to be deployed locally, and run:

# Test environment
git push --force origin HEAD:test

# Test2 environment
git push --force origin HEAD:test2

# Preprod environment
git push --force origin HEAD:preprod

Environment Variables

Several environment variables are required for the operation of this service. Not all are required to run the service locally

Required

Env var	Description
KEYWORKER_API_HOST	The URL where the keyworker API is hosted
HMPPS_OAUTH_CLIENT_ID	The client ID of the application in OAUTH
NOMIS_OAUTH_HOST	This is the full URL of the OAUTH host where access is granted to users using the service
HMPPS_API_CLIENT_ID	This is the full URL of the API host where access is granted to read from the relevant APIs
NOMIS_OAUTH_PUBLIC_KEY	This is the base64 encoded public key for decoding Tokens provided by the OAUTH server
PROMETHEUS_METRICS	If set to 'on' then will enable the generation of prometheus metrics
ASSESS_RISKS_AND_NEEDS_API_HOST	The URL where the Assess Risks and Needs API is hosted

Extra variables not required locally

Env var	Description
DIGITAL_PRISON_SERVICE_HOST	The host where New NOMIS is hosted
NOMIS_OAUTH_AUTHORISATION	Oauth authorisation string (base64 encoded)
SENTRY_DSN	The URL of a sentry installation. If no installation is available, then this should be present but an empty string ( "" )

Git Hooks

Run make setup to install git pre-commit hooks that:

lint changed files using govuk rubocop

To test that the pre-commit hook is set up correctly, make an anti-rubocop change in app/models/offender.rb and try to commit - it should stop you doing so. (If it succeeds, undo the commit).

If there are problems with Rubocop running (e.g. during a rebase session where the commits change Gemfile/Gemfile.lock) then disable the hook first: chmod -x .git/hooks/pre-commit

Deployment files

Kubernetes files in deploy/ manage deployment. Modify these to manage deployment.

Templating System

A simple custom templating system has been built to manage these files. For now it is used to manage production cron jobs.

Modify the relevant template in deploy/templates/, add the file to generate to the relevant job in lib/tasks/deployment.rake, and run the rake task.

It should not be made any more complex - if more complexity is required, stop requiring it. Simplicity is genius.

CircleCI

CircleCI is used for testing of branches and deploying.

It runs tests in parallel and skips flaky specs.

Mark specs as flaky by adding the flaky: true flag to them.

To disable parallel testing in CircleCI, set the environment variable PARALLEL_TEST_PROCESSORS=1 in the CircleCI project settings. Delete it from project settings to go back to the default of parallel testing.