BOPS

Back-Office Planning System (BOPS)

This README is aimed at developers wishing to work on this project or learn more about the code base in this repository. If you need technical guidance for getting set up on BOPS, contact us here.

Getting started

Using Docker

The easiest way to run the application is with Docker. First cd into the bops-applicants folder and run:

git submodule update --init --recursive

This links the main repo to the BOPS applicants project.

Then build and launch the images:

docker-compose up

Once the containers are running, use the Makefile to get a prompt and set up the database:

make prompt

root@232515c34d14:/app# bin/rails db:setup

It may also be necessary to install yarn and precompile the Rails assets:

make prompt

yarn install

bin/rails assets:precompile

Building production docker

Create production docker

docker build -t bops -f Dockerfile.production .

Run production docker

docker run --rm -it -p 3000:3000 -e DATABASE_URL=postgres://postgres@host.docker.internal:5432/bops_development -e RAILS_SERVE_STATIC_FILES=true -e RAILS_ENV=production -e RAILS_LOG_TO_STDOUT=true bops:latest bundle exec rails s

Run production docker bash

docker run --rm -it -e DATABASE_URL=postgres://postgres@host.docker.internal:5432/bops_development -e RAILS_SERVE_STATIC_FILES=true -e RAILS_ENV=production -e RAILS_LOG_TO_STDOUT=true bops:latest /bin/bash

Run BOPS locally

Install the project's dependencies:

$ bundle install
$ yarn install
$ brew install chromedriver  # as an admin user

It is necessary to have PostgreSQL installed and the PostGIS extension enabled.

Enable the PostGIS extension:

If enabling PostGIS natively, please review the installation guide.

Create the databases

$ rails db:setup

Start the server:

$ bin/dev

Subdomains

Because of the local authority being inferred on the request's subdomain, options to get the application working locally include using Docker or using the bops.localhost domain which points back to localhost:

http://southwark.bops.localhost:3000/
http://lambeth.bops.localhost:3000/
http://buckinghamshire.bops.localhost:3000/

This should happen automatically but may require adding the hosts to /etc/hosts if a specific system/browser config doesn't work.

GOV.UK Notify

The staging and production environments need keys generated by GOV.UK Notify, which is a government service that enables the bulk secure sending of emails, SMS and letters. To run the application locally, set an environment variable NOTIFY_API_KEY which should contain a mock value.

2FA

To enable 2FA in development, set the keys for OTP_SECRET_ENCRYPTION_KEY and NOTIFY_API_KEY, and set otp_required_for_login to true on the user. This can be found in 1password and within your GOV.UK Notify Notify account

These keys are set within github actions for our testing and CI builds

Versions 5+ of the devise-two-factor gem uses a single Rails 7+ encrypted attribute named otp_secret to store the OTP secret in the database table

See the BOPS Terraform repo for more information about BOPS infrastructure.

OS maps

To utilise all the map functionality, set an OS_VECTOR_TILES_API_KEY in .env This value can be found in the AWS Parameter Store

BOPS Applicants

BOPS allows planning officers to request changes to an application; these requests are presented to applicants through a separate app called BOPS Applicants. Applicants receive an email containing a special URL that will be opened in BOPS applicants and contain the right parameters for it to query back at BOPS.

If the application is running with Docker, bops-applicants is already part of the Compose group and should be running on port 3001. If not, clone/setup/boot the application manually and set the applicants_url column on the local authority record.

Note that because of the limitations of Docker network aliases (which can't accept wildcards, we will add a small DNS service eventually), BOPS Applicants has to operate against the Southwark local authority (i.e southwark.localhost) for now.

API

Creating data through the API

Once the application is running, planning applications can be submitted through the API.

API documentation is available at /api/docs/index.html.

Do this through the provided Swagger documentation at /api/docs/index.html

Click Authorize and fill in the API key (both v1 and v2 are scoped per user and thus to local authority)
POST /api/v1/planning_applications > Try it out > Choose 'Full' example > Click Execute.

Creating a new local authority using a rake take

The following parameters are required and a validation error will be raised if they are not provided:

subdomain: the subdomain to run the service
council_code: should be matched with planning data's code
council_name: the council's name
short_name: the council's short name
applicants_url: match to council's applicants url

There is also the following optional parameter:

admin_email

rake local_authority:create -- --subdomain 'lambeth' \
  --council_code 'LBH' \
  --council_name 'Lambeth Council' \
  --short_name 'Lambeth' \
  --applicants_url 'https://planningapplications.lambeth.gov.uk' \
  --admin_email 'admin@lambeth.gov.uk'

Working with API documentation: aggregate Swagger files

To keep the code easy to maintain, there are multiple files that are compiled into a single OpenAPI file:

public/api/docs/v1/swagger_doc.yaml

So to create a new API endpoint, create the yaml doc inside swagger/v1 and reference it in:

swagger/v1/swagger_doc.yaml

like so:

  $ref: "./your_new_file_name.yaml"

Make changes to the new file and aggregate them into a single file by installing this package locally:

npm install -g swagger-cli

and running:

swagger-cli bundle swagger/v1/swagger_doc.yaml --outfile public/api/docs/v1/swagger_doc.yaml --type yaml --dereference

Maps

We are using an open-source npm package by OSL to render all of our maps
This is an OpenLayers-powered Web Component map for tasks related to planning permission in the UK.

JavaScript

We are using Stimulus to handle our minimal JavaScript requirements.

After adding a new Stimulus controller run ./bin/rails stimulus:manifest:update. Alternatively create the controller with ./bin/rails generate stimulus controllerName.

Front-end components

As much as possible, we follow the GOV.UK Design System. The HTML components can be found here here. For help with forms we use the GOV.UK Ruby on Rails Form Builder gem. See here for a simple example of implementation.

unboxed/bops