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
--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
$ rails_template_18f new <project name> --hotwire ADDITIONAL_CONFIG_OPTIONS
$ 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.
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. Answern
to have documents checked directly into your code repo.- If you answer
y
, you'll need to provide the address of the compliance repository.
- If you answer
- "Run compliance checks with auditree?" Answer
y
if you want to integrate with auditree for automated compliance checks.
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.
Provide your cloud.gov organization and space names for use in terraform and deploy scripts.
Answer y
to create Github Actions workflows for running tests, scans, and deploys. Also configures Dependabot.
Answer y
to create a CircleCI workflow for running tests, scans, and deploys.
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.
Answer y
to set up an integration with DAP.
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.
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
- Create a better default
README
- Copy
CONTRIBUTING.md
andLICENSE.md
from the 18F Open Source Policy repo - Create a "near-production"
ci
Rails environment, used for running a11y and security scans - Create a "near-production"
staging
Rails environment, used for cloud.gov staging environment, with a "TEST SITE" warning banner - Create a
.nvmrc
file for specifying the NodeJS version in use - Set up
pa11y-ci
for a11y scanning - Set up
OWASP ZAP
dynamic security scanning - Include
secure_headers
gem and configure CSP header to get OWASP passing by default - Install and configure brakeman for static security scanning
- Install
bundler-audit
and set upbundle:audit
rake task for Ruby dependency security scans - Set up
yarn:audit
rake task for JavaScript dependency security scans - Install Standard Ruby for Ruby linting
- Install rspec for unit testing
- Install dotenv for local configuration
- Setup Rails credential diffing
- Create a separate production credentials file.
- Create a
pre-commit
hook that can be used to automatically run ruby linter & terraform format - Setup USWDS via postcss
- Setup webpack with
.browserslistrc
from USWDS - Update
app/views/layouts/application.html.erb
to pass thepa11y-ci
scan and include the USWDS Banner - Create a
PagesController
and root route - Create boundary and logical data model compliance diagrams
- Create
manifest.yml
and variable files for cloud.gov deployment - Optionally run the
rake db:create
andrake db:migrate
setup steps - Optionally integrate with https://github.com/GSA-TTS/docker-trestle
- Optionally integrate with https://github.com/GSA-TTS/auditree-devtools
- Optionally create GitHub Actions workflows for testing and cloud.gov deploy
- Optionally create terraform modules supporting staging & production cloud.gov spaces
- Optionally create CircleCI workflows for testing and cloud.gov deploy
- Optionally create a New Relic config with FEDRAMP-specific host
- Optionally configure DAP (Digital Analytics Program)
- Optionally add base translation files and routes for Spanish, French, and Simplified Chinese (es.yml, fr.yml, and zh.yml)
- Create Architecture Decision Records for above setup
- 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.