Flood risk engine

A Ruby on Rails engine delivering the complete public-facing functionality of the Flood risk activity exemptions service.

It is mounted in a thin Flood Risk Front Office Rails application host in order to be deployed. It can also be mounted within an administration application.

Getting started

The engine is un-styled when run stand-alone. To see the fully-styled service, follow the instructions in the Front office readme.

Prerequisites

Please make sure the following are installed:

• Ruby 3.2.2 installed for example via RVM or Rbenv
• Bundler
• git
• Postgresql
• Phantomjs

Installation

Clone the repository and install its gem dependencies:

git clone https://github.com/EnvironmentAgency/flood-risk-engine.git
cd flood-risk-engine
bundle

.env

The project uses the dotenv gem to load environment variables when the app starts. Dotenv expects to find a .env file in the project root. As this is an engine, the .env file must be in the root of the dummy app at spec/dummy.

Rename spec/dummy/.env.example to spec/dummy/.env, and update the values where necessary (some have defaults).

Database

The engine uses PostgreSQL. To create, schema:load and seed the database

bundle exec rake db:setup

Geospatial Queries

The engine uses PostGIS and rgeo for geospatial queries. The activerecord-postgis-adapter gem adds geospatial datatypes to PotgreSQL and supports geospatial queries. The adapter is enabled by defining the database adapter as postgis instead of postgresql in database.yml:

adapter: postgis

Note that postgis is also required when running automated unit tests within GitHub CI. To support this, ci.yml specifies the use of a docker image which runs PostgreSQL with the postgis adapter:

image: postgis/postgis:10-2.5

Running the app

Because this is an engine, you need to start the app in ./spec/dummy:

bundle exec ./spec/dummy/bin/rails s

Open http://localhost:3000 in a browser.

Tests

The RSpec test suite focuses on unit and controller tests rather than integration and acceptance tests (see Flood risk acceptance tests) for those.

To run Rubocop followed by the test suite

bundle exec rake

To run just the tests

bundle exec rake test

Error reporting

The engine includes the airbrake gem, and will try to post production errors to an Errbit server which must be configured via the ENV variables

AIRBRAKE_HOST = "https://airbrake_or_errbit_server"
AIRBRAKE_PROJECT_KEY ="<api key>"

Example usage

This engine is a self-contained service but is designed to be mounted in a host application which will provide contextual styling.

For example in a host rails application

# In the Gemfile
gem "flood_risk_engine",
    git: "https://github.com/EnvironmentAgency/flood-risk-engine",
    tag: "v1.0.0"

# In routes.rb
mount FloodRiskEngine::Engine => "/"

Engine design

The service comprises a number of sequential forms, or steps, the customer must complete and submit if they wish to apply for a flood risk activity exemption.

A state machine defines and enforces the order of the steps (or states). See the separate state machines readme.

Folder structure

The app folder departs from a vanilla Rails app in the following regards

• app
  • forms has form objects to encapsulate step-specific validation and data persistence
  • jobs has ActiveJob jobs that are background jobs currently implemented using threads and the Suckerpunch gem
  • presenters has presenter classes used to aggregate and format data from several models for display on certain forms and pages
  • services Service objects encapsulate an activity
  • state_machines See our state machines readme
  • views
    • pages the High_voltage gem serves these as static pages

Contributing to this project

If you have an idea you'd like to contribute please log an issue.

All contributions should be submitted via a pull request.

License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.