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.
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
docker build -t bops -f Dockerfile.production .
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
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
$ bundle install
$ yarn install
$ brew install chromedriver # as an admin user
It is necessary to have PostgreSQL installed and the PostGIS extension enabled.
If enabling PostGIS natively, please review the installation guide.
$ rails db:setup
$ bin/dev
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.
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.
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.
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 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.
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.
The following parameters are required and a validation error will be raised if they are not provided:
subdomain
: the subdomain to run the servicecouncil_code
: should be matched with planning data's codecouncil_name
: the council's nameshort_name
: the council's short nameapplicants_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'
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
- 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.
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
.
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.