submit-social-housing-lettings-and-sales-data/README.md

Data Collection App

This is the codebase for the Ruby on Rails app that will handle the submission of Lettings and Sales of Social Housing in England data.

Required Setup

Pre-requisites:

• Ruby
• Rails
• Postgres

Quick start

1. Copy the .env.example to .env and replace the database credentials with your local postgres user credentials.

2. Install the dependencies:
   bundle install

3. Create the database:
   rake db:create

4. Run the database migrations:
   rake db:migrate

5. Install the frontend depenencies:
   yarn install

6. Start the Rails server:
   bundle exec rails s

The Rails server will start on http://localhost:3000.

Using Docker

docker-compose build
docker-compose run --rm app rails db:create
docker-compose up

The Rails server will start on http://localhost:8080.

Note docker-compose runs the production docker image (RAILS_ENV=production) as the Dockerfile doesn’t include development gems to keep the image size down.

Infrastructure

This application is running on GOV.UK PaaS. To deploy you need to:

1. Contact your organisation manager to get an account in dluhc-core organization and in the relevant spaces (sandbox/production).

2. Install the Cloud Foundry CLI

3. Login:
   cf login -a api.london.cloud.service.gov.uk -u <your_username>

4. Set your deployment target (sandbox/production):
   cf target -o dluhc-core -s <deploy_environment>

5. Deploy:
   cf push dluhc-core --strategy rolling. This will use the manifest file

Once the app is deployed:

1. Get a Rails console:
   cf ssh dluhc-core -t -c "/tmp/lifecycle/launcher /home/vcap/app 'rails console' ''"

2. Check logs:
   cf logs dluhc-core --recent

CI/CD

When a commit is made to main the following GitHub action jobs are triggered:

1. Test: RSpec runs our test suite
2. Deploy: If the Test stage passes, this job will deploy the app to our GOV.UK PaaS account using the Cloud Foundry CLI

When a pull request is opened to main only the Test stage runs.

Single log submission

The form for this is driven by a JSON file in /config/forms/{start_year}_{end_year}.json

The JSON should follow the structure:

{
  "form_type": "lettings" / "sales",
  "start_year": Integer, // i.e. 2020
  "end_year": Integer, // i.e. 2021
  "sections": {
    "[snake_case_section_name_string]": {
      "label": String,
      "subsections": {
        "[snake_case_subsection_name_string]": {
          "label": String,
          "pages": {
            "[snake_case_page_name_string]": {
              "header": String,
              "description": String,
              "questions": {
                "[snake_case_question_name_string]": {
                  "header": String,
                  "hint_text": String,
                  "type": "text" / "numeric" / "radio" / "checkbox" / "date",
                  "min": Integer, // numeric only
                  "max": Integer, // numeric only
                  "step": Integer, // numeric only
                  "answer_options": { // checkbox and radio only
                    "0": String,
                    "1": String
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Assumptions made by the format:

• All forms have at least 1 section
• All sections have at least 1 subsection
• All subsections have at least 1 page
• All pages have at least 1 question
• The ActiveRecord case log model has a field for each question name (must match)
• Text not required by a page/question such as a header or hint text should be passed as an empty string

Useful documentation (external dependencies)

GOV.UK Design System Form Builder for Rails

• Examples
• Technical docs
• GitHub repository

GOV.UK Frontend

• GitHub repository

Hotwire (Turbo/Stimulus)

• Docs