18F Rails Template

The 18F Rails template starts or upgrades Rails projects so that they're more secure, follow compliance rules, and are nearly ready to deploy onto cloud.gov. This gem sets up security checks and compliance diagrams, adds the U.S. Web Design System (USWDS), and much much more — see the full list of features.

This template will create a new Rails 7.0.x project.

See the rails-6 branch for Rails 6.1.x

1. Install the gem:

$ gem install rails_template_18f

2. Decide whether to install Rails with Hotwire, a framework for client-side interactivity using JavaScript

• For entirely server-side rendered applications, without any Javascript:
  • Use the default configuration (rails_template_18f new <project name> --no-hotwire)
• For applications that need a bit of client-side interactivity, but not a full single page application like React or Vue:
  • Use Hotwire (rails_template_18f new <project name> --hotwire)
• For single-page applications where most of the interaction will take place via JavaScript, and which will use a framework like React or Vue:
  • Use the default configuration (rails_template_18f new <project name> --no-hotwire)

The --hotwire flag means that Hotwire and ActionCable are installed. ActionCable is included to enable the Turbo Streams functionality of Hotwire.

Before installing, you may want to consider the other application configuration options in the next section.

There are a variety of options that customize your Rails application.

Important: Do not use flags --skip-bundle or --skip-javascript, or various parts of this template will break.

--skip-active-storage   # Don't include ActiveStorage for document upload
--skip-action-text      # Don't include ActionText libraries for WYSIWYG editing
--skip-action-cable     # Don't include ActionCable websocket implementation
--skip-action-mailbox   # Don't include inbound email
--skip-hotwire          # Don't include Hotwire JS library
--skip-test             # Skip built-in test framework. (We include RSpec)
--javascript=webpack    # Use webpack for JS bundling
--css=postcss           # Use the PostCSS framework for bundling CSS
--template=template.rb  # Add additional configuration from template.rb
--database=postgresql   # Use a PostgreSQL database

You probably won't want to customize the template — that defeats the purpose of using this gem!

TODO: Documentation on whether you can override the css and database options.

Installing this gem in a new Rails project will TODO: say how it will help

Add this line to your application's Gemfile:

gem "rails_template_18f", group: :development

And then run:

$ bundle install

For a list of commands this gem can perform, run:

$ rails generate | grep 18f

TODO: Add documentation on each option.

This template does a lot! The template completes the following to-do list to make your application more secure, closer to standards-compliant, and nearly production-ready.

1. Create a better default README
2. Copy CONTRIBUTING.md and LICENSE.md from the 18F Open Source Policy repo
3. Create a "near-production" ci Rails environment, used for running a11y and security scans
4. Create a "near-production" staging Rails environment, used for cloud.gov staging environment, with a "TEST SITE" warning banner
5. Create a .nvmrc file for specifying the NodeJS version in use
6. Set up pa11y-ci for a11y scanning
7. Set up OWASP ZAP dynamic security scanning
8. Include secure_headers gem and configure CSP header to get OWASP passing by default
9. Install and configure brakeman for static security scanning
10. Install bundler-audit and set up bundle:audit rake task for Ruby dependency security scans
11. Set up yarn:audit rake task for JavaScript dependency security scans
12. Install Standard Ruby for Ruby linting
13. Install rspec for unit testing
14. Install dotenv for local configuration
15. Setup Rails credential diffing
16. Create a separate production credentials file.
17. Create a pre-commit hook that can be used to automatically run ruby linter & terraform format
18. Setup USWDS via postcss
19. Setup webpack with .browserslistrc from USWDS
20. Update app/views/layouts/application.html.erb to pass the pa11y-ci scan and include the USWDS Banner
21. Create a PagesController and root route
22. Create boundary and logical data model compliance diagrams
23. Create manifest.yml and variable files for cloud.gov deployment
24. Optionally run the rake db:create and rake db:migrate setup steps
25. Optionally integrate with https://github.com/GSA-TTS/compliance-template
26. Optionally create GitHub Actions workflows for testing and cloud.gov deploy
27. Optionally create terraform modules supporting staging & production cloud.gov spaces
28. Optionally create CircleCI workflows for testing and cloud.gov deploy
29. Optionally create a New Relic config with FEDRAMP-specific host
30. Optionally configure DAP (Digital Analytics Program)
31. Optionally add base translation files and routes for Spanish, French, and Simplified Chinese (es.yml, fr.yml, and zh.yml)
32. Create Architecture Decision Records for above setup
33. Commit the resulting project with git (unless --skip-git is passed)

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/18f/rails-template. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Everyone interacting in the 18F Rails Template project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.