Skip to content
Inside Government: how the UK Government works, what it's doing, and how you can get involved.
Ruby HTML CSS JavaScript Cucumber Shell
Find file
Latest commit 64ce34c @binaryberry binaryberry Merge pull request #2466 from alphagov/switch-topical-event-about-pag…

Change topical event about page rendering app
Failed to load latest commit information.
app Change topical event about page rendering app
bin Remove spring.
carrierwave-tmp Add explicit carrierwave-tmp dir
config Correctly republish editions
db Republish topical event about pages
docs Add note to docs
features Delete take part page controller
lib Use constants for rendering_app values
log Quite literally the initial commit.
public Amended comment from 404 to 403
script Remove old code for deduping stats announcements
test Change topical event about page rendering app
vendor/assets/stylesheets Revert "Revert "Merge pull request #571 from alphagov/rails-upgrade""
.gitignore Use latest shared_mustache
.ruby-version Upgrade Ruby to 2.2.3
.yardopts Cope with search bots adding [] to param keys Replace Travis guidance with Jenkins
Gemfile Bump Plek
Gemfile.lock Downgrade rack-cache to non-yanked 1.5.1
LICENCE Fix the copyright notice
Procfile Add Foreman worker to run Sidekiq Replace preview with integration in README
Rakefile Bring back basic logging for tests Add Raindrops to Rack configuration Remove detailed guide categories from database Better context message for contract tests Use gds-ruby-styleguide to provide Rubocop Don't override passed in STATIC_DEV env var in

Code Climate

Whitehall App

"Whitehall" is the code name for the Inside Government project, which aims to bring Government departments online in a consistent and user-friendly manner. Documentation can be found on rdoc.

Contributing guide.

Getting set-up locally


  • Xcode (for the Command Line Tools xcode-select --install)
  • Ruby 2.2.3
  • Rubygems and Bundler
  • Mysql
  • Imagemagick and Ghostscript (for generating thumbnails of uploaded PDFs)
  • xpdf (first download XQuartz)
  • PhantomJS (for running the Javascript tests)

If you use Homebrew you can run the following:

brew install ruby-build rbenv mysql phantomjs imagemagick ghostscript xpdf

Creating the mysql user

The database.yml for this project is checked into source control so you'll need a local user with credentials that match those in database.yml.

mysql> grant all on `whitehall\_%`.* to whitehall@localhost identified by 'whitehall';

Preparing the app

$ cd /path/to/whitehall
$ rbenv install
$ gem install bundler
$ bundle install

If you running on OSX Yosemite or later you might come across an installation failure:

An error occurred while installing eventmachine (1.0.4), and Bundler cannot continue.
Make sure that `gem install eventmachine -v '1.0.4'` succeeds before bundling.

To solve the problem make sure you have openssl under /usr/local/opt/openssl/include and run the following:

$ gem install eventmachine -v '1.0.4' -- --with-cppflags=-I/usr/local/opt/openssl/include

Set up the database

If you wish to use a sanitized export of the production data (recommended for internal staff) then see the alphagov/development repo for the replication script. Once that is imported upgrade your import to the latest schema version with

$ bundle exec rake db:setup

Running tests locally

The test suite relies on the presence of the govuk-content-schemas repository. This should either be present at the same directory level as the Whitehall repository, or the location must be specified explicitly via the GOVUK_CONTENT_SCHEMAS_PATH environment variable.

Two other environment variables can also be (optionally) set up, typically:

Then run

$ bundle exec rake

Alternatively run

$ govuk_setenv whitehall env RAILS_ENV=test bundle exec rake

Note that using bowler or foreman will automatically use the govuk_setenv method for you.

Running tests in parallel

The test suite can be run in parallel like so:

rake test:in_parallel

This will automatically prepare your test database for parallel work.

Running javascript unit tests

Javascript unit tests can be run together:

rake test:javascript

To run individual tests or when debugging:


And go to http://localhost:3100/test/qunit in the browser

Shared mustache templates

The shared mustache templates must be compiled for javascript unit and functional tests to pass.

rake shared_mustache:compile
rake shared_mustache:clean

Shared mustache templates are generated and stored in app/assets/javascripts/templates.js.

In absence of this generated template, shared mustache inlines mustache templates in <script> blocks on the page, which enables developers to see changes to mustache without compiling. If this generated template is checked-in, shared mustache uses this file instead of inlining templates. Hence, we don't check-in this file.

Running the server locally

$ bundle exec rails s

Note that the app itself will respond to requests on the root URL / with a routing error: to check the app works, try visiting /government/admin.


GOV.UK shares assets (eg stylesheets and JavaScript) across apps using the slimmer gem and the static app. Ideally, you will have a copy of static running locally (at by default) and that will be used to serve shared assets. This is how things will work by default if you are running the GOV.UK development VM with foreman or bowler.

If you are running whitehall with bundle exec rails server and don't want to run a local copy of static, you can tell the app to use assets served directly from the Integration environment by setting STATIC_DEV:

STATIC_DEV= bundle exec rails server

If you are only working on the Whitehall admin interface, you don't need the assets available.

Creating new users in Production

New users will need a sign-on-o-tron account before they can access whitehall in production. You can create new sign-on-o-tron accounts with the capistrano task in alphagov-deployment/sign-on-o-tron. This will email the new user and prompt them to create their account.

Getting search running locally

The Whitehall app relies on Rummager for document indexing, and the GOV.UK frontend application to serve results.

Rebuilding whitehall search index

The easiest way to get a search index is to replicate it from the Integration environment. This will not contain local changes to your content, but will be enough for many tests. To fetch the replica, use the "replicate-data-local" script from the development project (as documented in that project's README). If you need to have local changes in your dev environment copied into the search index, you will actually need to rebuild the search index.

The whitehall search index is called 'government'. Rebuilding of the whitehall search index can now be done with a bulk data dump. This also supports construction of a new detached index and seamless switchover from the existing to the new index. There are two parts to this process, a rummager_export.rb script in whitehall which dumps the whitehall data to STDOUT, and a bulk_load script in rummager which accepts that data on STDIN and loads it into rummager.

The bulk_load script also takes care of constructing the new offline index, locking the index for writes (so that index write workers queue up waiting for the new index to come online during indexing, avoiding data loss during reindex), and seamlessly switching to the new index on completion.


  1. Make sure you have created the rummager indices by running the following task from the rummager repo:

    RUMMAGER_INDEX=government bundle exec rake rummager:migrate_index

  2. Run the bulk export and load:

    bundle exec ./script/rummager_export.rb > government.dump bundle exec ./script/rummager_export.rb --detailed > detailed.dump


(cd ../rummager && bundle exec ./bin/bulk_load government) < government.dump
(cd ../rummager && bundle exec ./bin/bulk_load detailed) < detailed.dump

Search indexing paths

There are currently two paths for whitehall searchable classes to be indexed. For a list of searchable classes, please refer to Whitehall.edition_classes (in lib/whitehall.rb).

Indexing for searchable classes that inherit from Edition is triggered via the ServiceListeners::SearchIndexer listening to the force_publish and publish events. Since Edition sets the index_after key in its searchable options hash to [], classes inheriting from it don't trigger indexing when saved.

To trigger indexing for an instance of these classes in unit/integration tests, create an instance in a valid publishing state ('submitted', 'rejected') and call!.

Indexing for additional searchable classes is triggered by save. This behaviour is defined in Searchable.searchable_options, where the index_after is set to :save as a default.

To trigger indexing for an instance of these classes in unit/integration tests, create an instance in a valid publishing state ('submitted', 'rejected') and call save! on it.

Specifying a different endpoint for the GDS Content API

Whitehall uses the GDS Content API to serve categorisation for Detailed Guidance. In tests, this is stubbed out, see config/initializers/content_api.rb.

Generating the documentation

We use YARD for the documentation. You can generate a local copy with:

yard server --reload

You can also read the docs on

Meaning of timestamps


  • point in time the edition became visible to the public on the website. Updated for major changes
  • used to sort documents in the atom feed
  • for building change_history on a document
  • used when comparing edition published dates in scopes on Edition (e.g. published_before(date))
  • set to first_public_at or major_change_published_at on every save


  • signifies when the document was 'first published', which may be before the public timestamp. E.g. transitioned content, etc.
  • Either user supplied on the form, or set during publishing to the major_change_published_at timestamp


  • first_published_at on Edition
  • opening_at on Consultation


  • date of the last major change. Major changes require change notes. This is decided by the user.


This is mostly standard Rails i18n - Translations are stored in config/locales/, with a .yml file per locale.

If translation value is missing from a locale file then the EN value will be used instead.

Changing an existing translation key

Edit the value of EN locale, you should then manually edit all other locales to set the altered translated value to be blank.

Adding a new translation key

Manually create the key in en.yml, with the english text.

Run a task to add that key to all other language files:

bundle exec rake translation:regenerate

Pluralised translations

For terms that are translatable in both singular and plural forms (e.g. document.type.publication), include "one" and "other" keys for the singular and plural translation of the term.

Note: pluralised translation terms should only ever contain these two plural form keys in en.yml, otherwise the code that regenerates the other translation locale files will not recognise them as being plural translations and will not generate the correct pluralisation keys for the different locales.

Updating the locales files

There are rake tasks to export and import a CSV file of translations and keys (provided by the rails_translation_manager gem. These CSV files are exported, edited and then imported back as .yml files.

There's no timeline for how frequently this is done, so you can expect many translation values to be missing in non EN locales.

Something went wrong with that request. Please try again.