Skip to main content
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:

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:

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.