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
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.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
Run
bundle && rails g rspec:install
to install all the gems you included inGemfile
and generate files you can use to test your app.Run
rm spec/rails_helper.rb
to deletespec/rails_helper.rb
.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
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.Delete the
config/credentials.yml.env
andconfig/master.key
files, and create aconfig/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'] %>
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
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.
Setting up a Puma web server
Puma is already included in the govuk_app_config gem.
Create a config/puma.rb
file that contains the following code:
require "govuk_app_config/govuk_puma"
GovukPuma.configure_rails(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 contract tests for your app
If your app provides an internal API, it should have contract tests.
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
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 match the standard README template.
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
Find out how to set up an app in Jenkins.
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/repos.yml
file.
Create the application in Sentry
After you’ve added your Rails app to the GOV.UK developer documentation, run the update_project
rake task in GOV.UK SaaS Config to update Sentry.
From the sentry
directory, run:
SENTRY_AUTH_TOKEN="token_value" bundle exec rake update_project[APP_NAME]
You’ll need to create a Sentry auth token first. Make sure it has the project:write
scope. You can delete the token once you’ve successfully run the rake task.
The rake task will create a ‘project’ for the app under the team name denoted by the app’s team
in the Developer Docs. If the team does not exist in Sentry yet, you can manually create it in the Sentry UI. If the Sentry team name does not match the Slack channel team
name used in the Developer Docs, you can temporarily rename it so that it matches what the rake task expects, and then change it back later.
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.