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.2.x project.

See the rails-7.1 branch for Rails 7.1.x

Usage

For a new Rails project

Install the gem:

$ gem install rails_template_18f

Decide whether to install Rails with Hotwire

Hotwire is a framework for client-side interactivity using JavaScript that stops short of a full Single Page Application (SPA) framework like React or Vue.

It is a good choice if you need a bit of client-side interactivity. Do not use Hotwire if you either will have almost no Javascript at all, or if you are going to use a full SPA.

Review the defaults and decide if you want to override any of them

Default configuration

--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-docker           # Don't include Dockerfile meant for production use
--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
--skip-rubocop          # Skip rubocop integration in favor of Standard Ruby
--skip-ci               # Skip github actions in favor of our CI generators

If you are using Hotwire, then --skip-hotwire and --skip-action-cable are automatically removed from this list, as they are required for the Hotwire functionality.

Add the following options at the end of your rails_template_18f new command to overwrite any of those defaults.

Option	Description
--no-skip-<framework>	Each of the skipped frameworks listed above (also in railsrc) can be overridden on the command line. For example: --no-skip-active-storage will include support for ActiveStorage document uploads
--javascript=esbuild	Use esbuild instead of webpack for JavaScript bundling. Note that maintaining IE11 support with esbuild may be tricky.

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

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

Create your application

If you are using Hotwire, run:

$ rails_template_18f new <project name> --hotwire ADDITIONAL_CONFIG_OPTIONS

If you are not using Hotwire, run:

$ rails_template_18f new <project name> ADDITIONAL_CONFIG_OPTIONS

Answer the setup questions that the template asks

The template asks questions to ensure your new application is set up for your use case.

Set up docker-trestle integration for Compliance-as-Code?

Answer y to integrate with docker-trestle for creating compliance documents in markdown and OSCAL.

Follow up questions if you answer y:

• "Set up compliance documents as a git submodule?" Answer y if you want compliance documents to be stored in a separate git repository and linked to your app as a submodule. Answer n to have documents checked directly into your code repo.
  • If you answer y, you'll need to provide the address of the compliance repository.
• "Run compliance checks with auditree?" Answer y if you want to integrate with auditree for automated compliance checks.

Create terraform files for cloud.gov services?

Answer y to run the terraform generator. This includes a /terraform folder defining services and infrastructure within cloud.gov as well as support for deploying that infrastructure in your chosen CI/CD pipeline.

Cloud.gov organization and space names

Provide your cloud.gov organization and space names for use in terraform and deploy scripts.

Create GitHub Actions?

Answer y to create Github Actions workflows for running tests, scans, and deploys. Also configures Dependabot.

Create CircleCI config?

Answer y to create a CircleCI workflow for running tests, scans, and deploys.

Create FEDRAMP New Relic config files?

Answer y to create a default New Relic config that can speak to the Government-flavored New Relic instance, including updating Content Security Policy headers so that browser metrics can be collected.

If this will be a public site, should we include Digital Analytics Program code?

Answer y to set up an integration with DAP.

Supported locales

Answer y for any languages that should be supported out of the box. Translations are supplied for the usa-banner. You will still be responsible for translating any application content.

Run db setup steps?

Answer y to run rake db:create && rake db:migrate as part of the app setup. PostgreSQL must be running or this will fail.

For an existing Rails project

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:

$ bin/rails generate | grep 18f

Run bin/rails generate rails_template_18f:GENERATOR --help for information on each generator.

Features

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/docker-trestle
26. Optionally integrate with https://github.com/GSA-TTS/auditree-devtools
27. Optionally create GitHub Actions workflows for testing and cloud.gov deploy
28. Optionally create terraform modules supporting staging & production cloud.gov spaces
29. Optionally create CircleCI workflows for testing and cloud.gov deploy
30. Optionally create a New Relic config with FEDRAMP-specific host
31. Optionally configure DAP (Digital Analytics Program)
32. Optionally add base translation files and routes for Spanish, French, and Simplified Chinese (es.yml, fr.yml, and zh.yml)
33. Create Architecture Decision Records for above setup
34. Commit the resulting project with git (unless --skip-git is passed)

Developing this gem

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/gsa-tts/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.

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.