Last updated: 12 Jul 2021

Set up a new Rails application

Before you start

Before you create a Ruby on Rails (“Rails”) app, you must complete all steps in the GOV.UK developer get started documentation.

You should:

• develop your Rails app in line with the conventions for Rails applications
• name your Rails app in line with the conventions for naming apps

Create a new Rails app

1. To create a Rails app on your local machine, run the following in the command line:

   rails new myapp --skip-javascript --skip-test --skip-bundle --skip-spring --skip-action-cable --skip-action-mailer --skip-active-storage
   

   The --skip commands exclude unneeded Rails components.

2. Include the gems you need for your app in Gemfile. For example:

   source "https://rubygems.org"
   
   gem "rails", "6.0.3.4"
   
   gem "bootsnap",
   gem "gds-api-adapters"
   gem "gds-sso"
   gem "govuk_app_config"
   gem "govuk_publishing_components"
   gem "pg"
   gem "plek"
   gem "uglifier"
   
   group :development do
     gem "listen"
   end
   
   group :test do
     gem "simplecov"
   end
   
   group :development, :test do
     gem "byebug"
     gem "govuk_test"
     gem "rspec-rails"
     gem "rubocop-govuk"
   end
   

3. Run bundle && rails g rspec:install to install all the gems you included in Gemfile and generate files you can use to test your app.

4. Run rm spec/rails_helper.rb to delete spec/rails_helper.rb.

5. Replace the contents of spec/spec_helper.rb with the following:

   ENV["RAILS_ENV"] ||= "test"
   
   require "simplecov"
   SimpleCov.start "rails"
   
   require File.expand_path("../../config/environment", __FILE__)
   require "rspec/rails"
   
   Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }
   GovukTest.configure
   
   RSpec.configure do |config|
     config.expose_dsl_globally = false
     config.infer_spec_type_from_file_location!
     config.use_transactional_fixtures = true
   end
   

6. If your Rails app has a database, replace the content of config/database.yml with the following:

   default: &default
     adapter: postgresql
     encoding: unicode
     pool: 12
     template: template0
   
   development:
     <<: *default
     database: <APP-NAME>_development
     url: <%= ENV["DATABASE_URL"]%>
   
   test:
     <<: *default
     database: <APP-NAME>_test
     url: <%= ENV["TEST_DATABASE_URL"] %>
   
   production:
     <<: *default
     database: <APP-NAME>_production
     url: <%= ENV["DATABASE_URL"]%>
   

   where <APP-NAME> is the name of your Rails app.

7. Delete the config/credentials.yml.env and config/master.key files, and create a config/secrets.yml file that contains the following:

   development:
     secret_key_base: secret
   
   test:
     secret_key_base: secret
   
   production:
     secret_key_base: <%= ENV['SECRET_KEY_BASE'] %>
   

8. Replace the content of config/routes.rb with the following:

   Rails.application.routes.draw do
     get "/healthcheck/live", to: proc { [200, {}, %w[OK]] }
     get "/healthcheck/ready", to: GovukHealthcheck.rack_response
   end
   

9. Configure linting for your Rails app to make sure the app’s code is consistent with other GOV.UK apps. Find out more information about configuring linting.

Set up a Unicorn web server

1. If your Rails app’s Gemfile includes gem "puma", open Gemfile and delete gem "puma".

2. Create a Procfile in your app’s root directory that contains the following:

   web: bundle exec unicorn -c ./config/unicorn.rb -p ${PORT:-3000}
   

3. Create a config/unicorn.rb file that contains the following code:

   require "govuk_app_config/govuk_unicorn"
   GovukUnicorn.configure(self)
   

Add your Rails app to GOV.UK Docker

Add your Rails app to GOV.UK Docker so you can run the app locally. See an example GOV.UK Docker pull request.

Set up a GitHub repo for your Rails app

When you’ve finished developing your Rails app, you can set up a GitHub repo for your Rails app.

You must add a description to the About section in the GitHub repo, or the GOV.UK developer documentation build will break when it tries to build the list of apps.

Add a software licence

You must add a LICENCE file to your project’s root folder that specifies the software licence. You should usually use the following MIT License text. Replace with the current year.

The MIT License (MIT)

Copyright (c) <YEAR> Crown Copyright (Government Digital Service)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Replace the default README.md

Change the default README.md file to have the following structure:

# App name

One or more paragraphs describing the app:

- What it's used for.
- Any unusual dependencies it has.

## Live examples

(Only applies to frontend apps.)

A list of links to example pages rendered by the app.

## Nomenclature

A list of definitions for unusual terms in the code.

## Technical documentation

What goes here depends on the type of app.

See the links below for example content to put here.

### Running the test suite

Give one command to run all the tests, linting, etc.

You can also add other commands e.g. to run JS tests.

### Further documentation

A list of links to key files in docs/.

You can also just link to the docs/ directory itself.

## Licence

Link to your LICENCE file.

Examples READMEs that follow the above structure:

• Frontend app: Collections

• General app: Email Alert API

Write API documentation

If your app is an API, you should create a docs/api.md file.

Guidance on writing API reference documentation on GOV.UK.

Prepare your Rails app to run in production

Configure your Rails app for Jenkins

1. Create a Jenkinsfile in your repo with the following content.

   #!/usr/bin/env groovy
   
   library("govuk")
   
   node {
     govuk.buildProject()
   }
   

2. Add a Jenkins integration to the repo on GitHub. Find out more about automatically configuring a GitHub repo.

Add your Rails app to GOV.UK

Find out how to add your Rails app to GOV.UK using govuk-puppet.

Configure your Rails app’s deployment

To configure your app’s deployment, see the GOV.UK application deployment scripts.

Enable external DNS

If you need to enable external DNS, find out how to make changes to publishing.service.gov.uk.

Add your app to the GOV.UK developer documentation

Open a pull request to add your Rails app to the GOV.UK developer documentation data/applications.yml file.

Ask GOV.UK 2nd line to update Sentry

After you’ve added your Rails app to the GOV.UK developer documentation, ask GOV.UK 2nd line support to run the update-project task in GOV.UK SaaS Config to update Sentry.

Add your Rails app to Release app

Add your Rails app to the Release app and select Create.

Run the Deploy_App job

Run the Deploy_App job.

Use the with_migrations option if your Rails app has a database.

More in the Applications section

Learn

• Architectural deep-dive of GOV.UK
• Architecture overview of GOV.UK applications
• Configure linting
• Conventions for Rails applications
• Node classes without redundancy

How to...

• Add authentication to an application
• Create a Local Transaction
• Name a new application or gem
• Retire an application