navapbc / template-application-rails

Ruby on Rails with USWDS template, including CI/CD, for teams building web applications

Template Ruby on Rails application

This is a template repository for a Ruby on Rails application.

See navapbc/platform for other template repos.

Features

• U.S. Web Design System (USWDS) for themeable styling and a set of common components
  • Custom USWDS form builder
• Integration with AWS services, including:
  • Database integration with AWS RDS Postgresql using UUIDs
  • Active Storage configuration with AWS S3
  • Action Mailer configuration with AWS SES
  • Authentication with devise and AWS Cognito
• Internationalization (i18n)
• Authorization using pundit
• Linting and code formatting using rubocop
• Testing using rspec

Repo structure

├── .github                       # GitHub workflows and repo templates
├── docs                          # Project docs and decision records
├── app-rails                     # Web application
├── template-only-bin             # Scripts for managing this template; not copied into your project
├── template-only-docs            # Documentation for this template; not copied into your project

Installation

To get started using the template application on your project:

1. Run the download and install script in your project's root directory.

   curl https://raw.githubusercontent.com/navapbc/template-application-rails/main/template-only-bin/download-and-install-template | bash -s

   This script will:

   1. Clone the template repository
   2. Copy the template files into your project directory
   3. Ignore any files specific to the template repository, like this README.

   You can optionally pass in a branch, commit hash, or release that you want to install. For example:

   curl https://raw.githubusercontent.com/navapbc/template-application-rails/main/template-only-bin/download-and-install-template | bash -s -- <commit_hash>

2. Follow the steps in app-rails/README.md to set up the application locally.

3. Optional, if using the Platform infrastructure template: Follow the steps in the template-infra README to set up the various pieces of your infrastructure.

Updates

If you have previously installed this template and would like to update your project to use a newer version of this application:

1. Run the update script in your project's root directory and pass in the branch, commit hash, or release that you want to update to, followed by the name of your application directory (e.g. app-rails).

   curl https://raw.githubusercontent.com/navapbc/template-application-rails/main/template-only-bin/update-template | bash -s -- <commit_hash> <app_name>

   This script will:

   1. Clone the template repository
   2. Copy the template files into your project directory
   3. Ignore any files specific to the template repository, like this README.

⚠️ Warning! This will modify existing files. Review all changes carefully after executing the script by running git diff.