Application: government-frontend

Serves government pages on GOV.UK

GitHub: government-frontend
Ownership: #govuk-platform-health
Hosting: AWS, on the draft_frontend machine class
Continuously deployed?: Yes
Rake tasks: Integration, Staging or ⚠️ Production ⚠️
Links: Sentry (error tracking)

Puppet configuration

Deploy scripts

Deployment dashboard

Publishing E2E scenarios (warning: not all apps have E2E tests)

Component guide

Relevant manual pages

Add an organisation’s brand colour

Imported documents

Webchat Component

Example pages published by government-frontend

Example pages rendered by government-frontend

README

Government Frontend is a public-facing app to display the majority of documents on the /government part of GOV.UK. It is a replacement for the public-facing parts of the Whitehall application.

Screenshots

A Case Study

Schemas

Not all schemas that this app can handle are rendered by it in production.

Schema	Live example	Production status
Answer	View on GOV.UK	Migrated
Case study	View on GOV.UK	Migrated
Coming soon		Migrated
Consultation	View on GOV.UK	Migrated
Contacts	View on GOV.UK	Migrated
Corporate information page	View on GOV.UK	Migrated
Detailed guide	View on GOV.UK	Migrated
Document collection	View on GOV.UK	Migrated
Fatality notice	View on GOV.UK	Migrated
Help page	View on GOV.UK	Migrated
HTML Publication	View on GOV.UK	Migrated
News Article	View on GOV.UK	Migrated
Publication	View on GOV.UK	Migrated
Specialist document	View on GOV.UK	Migrated
Statistics announcement	View on GOV.UK	Migrated
Statistical data set	View on GOV.UK	Migrated
Speech	View on GOV.UK	Migrated
Take part	View on GOV.UK	Migrated
Topical event about page	View on GOV.UK	Migrated
Travel advice	View on GOV.UK	Migrated
Unpublishing		Rendered by Whitehall, might not be migrated
World Location News Article	View on GOV.UK	Migrated
Working group	View on GOV.UK	Migrated

Components

Pages are rendered using components. Components can be specific to government-frontend or shared between applications.

Shared components are provided by govuk_publishing_components and are documented in the component guide.

Components specific to government-frontend are within the application and follow rules set out by the govuk_publishing_components gem. They are documented in the government-frontend component guide.

When running government-frontend locally the component guide is available at: http://government-frontend.dev.gov.uk/component-guide

Configuration for the navigation links shown on the B variant of the ContentPagesNav A/B test is covered separately

Technical documentation

This is a Ruby on Rails application that fetches documents from content-store and displays them.

Dependencies

content-store - provides documents
static - provides shared GOV.UK assets and templates.
phantomjs Used by poltergeist for integration testing
ImageMagick Used by Wraith for visual regression testing

Running the application

./startup.sh

The app should start on http://localhost:3090 or http://government-frontend.dev.gov.uk on GOV.UK development machines.

./startup.sh --live

This will run the app and point it at the production GOV.UK content-store and static instances.

./startup.sh --dummy

This will run the app and point it at the dummy content store, which serves the content schema examples and random content.

Running the test suite

The test suite relies on the presence of the govuk-content-schemas repository. If it is present at the same directory level as the government-frontend repository then run the tests with:

bundle exec rake

Or to specify the location explicitly:

GOVUK_CONTENT_SCHEMAS_PATH=/some/dir/govuk-content-schemas bundle exec rake

Debugging Integration tests

If you want to see the page that is being tested in our integration tests, you can use save_and_open_page to see what’s rendered. This is helpful when a page is mostly comprised of GOV.UK Publishing Components

Visual regression tests

Use Wraith (“A responsive screenshot comparison tool”) to generate a visual diff to compare rendering changes in this application.

Compare with production

Compare development with production:

bundle exec wraith capture test/wraith/config.yaml

Compare staging with production:

bundle exec wraith capture test/wraith/config-staging-vs-production.yaml

This will generate image diffs comparing the two runs, including a browsable gallery of the output, located at shots/gallery.html.

Compare examples on master with examples on branch

Examples are referencing https://github.com/alphagov/govuk-content-schemas

With government-frontend running master on the development VM and while pointing at the dummy content store, create a set of historical screenshots using:

cd test/wraith
bundle exec wraith history test/wraith/config-examples.yaml

Then switch to your branch and create a set of screenshots to compare against using:

bundle exec wraith latest test/wraith/config-examples.yaml

Compare a document_type

A rake task has been made to make this easy, given a document_type of about

bundle exec rake wraith:document_type[about]

this will run against the 10 most popular pages as defined by the search api

Compare all document_types

bundle exec rake wraith:all_document_types[:sample_size]

This will run against the 10 (can be overidden with :sample_size) most popular pages as defined by the search api, for each known document_type in the app (see: Generate a config for known document_types and example pages).

Note: If you wish to have your own local wip configs, wip* is in the .gitignore, so as an example wip-kittens.yaml will be ignored

Generate a config for known document_types and example pages

Running the rake task below will retrieve the document_types where rendering_app = government-frontend from the search api. It will then generate test/wraith/wip-config-all-document-types.yaml, this is a wraith config file containing the top 10 (can be overidden with :sample_size) example pages for each type.

The yaml file contains a custom key of :document_types not used by wraith but can be used to quickly scan and see which types the search api believes government-frontend is responsible for.

bundle exec rake wraith:update_document_types[:sample_size]

Webchat

How to add a new webchat provider

Open to lib/webchat.yaml
Append new entry:

- base_path: /government/contact/my-amazing-service
  open_url: https://www.my-amazing-webchat.com/007/open-chat
  availability_url: https://www.my-amazing-webchat.com/007/check-availability

Deploy changes
Go to https://www.gov.uk/government/contact/my-amazing-service
Finished

CORS considerations

To avoid CORS and CSP issues a new provider would need to be added to the Content Security Policy

Required configuration

Base path

This is the base path of a contact page, for example, /government/organisations/hm-revenue-customs/contact/child-benefit. This path should always be a contact page, any other content page type will result in the webchat component not being loaded.

Availability URL

This URL is used to check the availability of agents at regular intervals.

Function	Required
Request Method	GET
Response Format	JSON/JSONP (Default to JSONP)
Request Example	{“status”:“success”,“response”:“BUSY”}
Valid statuses	[“BUSY”, “UNAVAILABLE”, “AVAILABLE”,“ONLINE”, “OFFLINE”, “ERROR”]

Open URL

This url is used to start a webchat session. This url should not include session ids or require anything specific parameters to be generated.

Optional Configuration options

Browser window behaviour

By default the chat session would open in an a separate browser window. An additional value can be added to the yaml entry that will allow the web chat to remain in the current browser window.

  open_url_redirect: true

Payload format

The default response from the api as used by HMRC webchat provider is JSONP. To add a provider that responds using JSON the following entry needs to be added.

  availability_payload_format: json

Licence

MIT License