Skip to content

Application template for Rails 7 projects; preloaded with best practices for TDD, security, deployment, and developer productivity.

License

Notifications You must be signed in to change notification settings

ackama/rails-template

Repository files navigation

Ackama Rails Template

Rails Template CI

This is a template you can use to create new Rails applications.

Background

This template is the set of things we (the Ackama Ruby team) want in every Rails application we create, based on 10+ years of creating new Rails applications, numerous pen-tests and then maintaining those applications for years.

Some of these choices are objectively good ideas, some of them are subjective opinions 🤷. We are delighted when other teams find this template useful as either the starting point for their apps, or as the starting point for creating their own in-house template.

Features

Where possible we stick to Rails defaults.

  • General
    • puma as application server
    • Yarn for managing JS packages
    • PostgreSQL as database. This template only supports PostgreSQL.
    • A much-improved bin/setup script
    • Install dotenv
    • Create a doc/ directory for docs
    • Add a middleware to implement HTTP Basic Auth by setting environment variables. We use this regularly for pre-production envs.
    • Use okcomputer for health check endpoints. Configured in ./variants/backend-base/config/initializers/health_checks.rb
    • Install lograge for better logs in production.
    • Create app/services as the place to hold our plain ol' Ruby objects wherein we put most of our business logic.
    • Override the default ActiveStorage base controller to force the team to make a decision about whether ActiveStorage files must be behind authentication or not. The default Rails behaviour here can be a security gotcha.
  • Security
  • Error reporting
    • Setup Sentry for error reporting
  • Code style
  • General testing
    • RSpec for tests
    • Install webdrivers
    • Install Simplecov for test coverage. Configures it with our defaults.
    • Debug system specs using a visible browser (not headless) by adding HEADFUL=1 environment variable to your command line
  • Accessibility testing - sets up automated accessibility testing.
    • Install axe and lighthouse to provide comprehensive coverage.
      • Axe Matchers is a gem that provides cucumber steps and rspec matchers that will check the accessibility compliance of your views. We require a default standard of wcag2a and wcag2aa.
      • We recommend that your tests all live in a spec/features/accessibility, to allow for running them separately. Using the shared examples found at variants/accessibility/spec/support/shared_examples/an_accessible_page.rb for your base tests avoids duplication and misconfiguration.
    • Install our lighthouse matchers gem which provide RSpec matchers to assess the accessibility compliance of your application.
      • We recommend setting your passing score threshold to 100 for new projects. As with Axe, you can keep your test suite tidy by placing these tests in spec/features/accessibility.
  • Front-end
    • Rename app/javascript to app/frontend
    • Setup Shakapacker (the maintained fork of Webpacker).
    • Note We are trialing the new JS packaging options that Rails 7+ provides. For now our default is still Shakapacker because it provides us the most flexibility.

    • Initializes Ackama's linting and code formatting settings, see Code linting and formatting
  • Performance testing
    • Add configuration and specs to use to perform a lighthouse performance audit, requiring a score of at least 95.
  • N+1 queries
    • Install & configure bullet to help prevent N+1 queries
  • Devise (optional)
    • Install devise and tweak the configuration. if enabled in the configuration file.
    • Configure devise to destroy session cookies on log out (this comes up regularly in penetration tests)
  • Bootstrap (optional)
    • Installs and configures Bootstrap if enabled in the configuration file.
  • React (optional)
  • Typescript (optional)
    • Install and configure Typescript including linting
  • Sidekiq (optional)
    • Install and configure Sidekiq

Other templates

Some functionality which isn't something we need on every app is available in our other templates:

Requirements

Before running this template, you must have the following installed on your machine:

  • Yarn v1.21.0 or later
  • Rails 7.1.x

The following are not strictly required to run the template but you will need it to start the Rails app that this template creates:

How do I use this?

This template requires a YAML configuration file to to configure options. It will use a file called ackama_rails_template.config.yml in your current working directory if it exists. Otherwise you can specify a path using the CONFIG_PATH environment variable.

ackama_rails_template.config.yml is a documented configuration example that you can copy.

You must also have Postgres running on port 5432.

To generate a Rails application using this template, pass the --template option to rails new, like this:

# Ensure you have the latest version of Rails
$ gem install rails

# Example 1
# #########

# Create a config file using the example
$ wget https://raw.githubusercontent.com/ackama/rails-template/main/ackama_rails_template.config.yml

# Tweak the config file as you see fit

# Create a new app using the template. Template options will be taken from
# ./ackama_rails_template.config.yml
$ rails new my_app --no-rc --database=postgresql --skip-javascript --skip-docker --template=https://raw.githubusercontent.com/ackama/rails-template/main/template.rb

# Example 2
# #########

# Create a custom config YAML file, saving as ./my_custom_config.yml

# Template options will be taken from ../my_custom_config.yml (relative to the new app directory)
$ CONFIG_PATH=../my_custom_config.yml rails new my_app --no-rc --database=postgresql --skip-javascript --skip-docker --template=https://raw.githubusercontent.com/ackama/rails-template/main/template.rb

Here are some additional options you can add to this command. We don't prescribe these, but you may find that many Ackama projects are started with some or all of these options:

  • --skip-action-mailbox skips the setup of ActionMailbox, which you don't need unless you are receiving emails in your application.
  • --skip-active-storage skips the setup of ActiveStorage. If you don't need support for file attachments, this can be skipped.
  • --skip-action-cable - if you're not doing things with Websockets, you may want to consider skipping this one to avoid having an open websocket connection without knowing about it.

How do I use this template for every Rails app I create?

The rails command will pull options from a .railsrc file in your home directory. These options will be applied as arguments each time you run rails new (unless you pass the --no-rc option).

To make this the default Rails application template on your system, create a ~/.railsrc file with these contents:

# ~/.railsrc
-d postgresql
--skip-javascript
--skip-docker
-m https://raw.githubusercontent.com/ackama/rails-template/main/template.rb

Once you've installed this template as your default, then all you have to do is run:

$ rails new my-awesome-app

Contributing

This project works by hooking into the standard Rails application templates system, with some caveats. The entry point is the template.rb file in the root of this repository.

Normally, Rails only allows a single file to be specified as an application template (i.e. using the -m <URL> option). To work around this limitation, the first step this template performs is a git clone of the ackama/rails-template repository to a local temporary directory.

This temporary directory is then added to the source_paths of the Rails generator system, allowing all of its ERb templates and files to be referenced when the application template script is evaluated.

Rails generators are very lightly documented; what you'll find is that most of the heavy lifting is done by Thor. Thor is a tool that allows you to easily perform command line utilities. The most common methods used by this template are Thor's copy_file, template, and gsub_file. You can dig into the well-organized and well-documented Thor source code to learn more. If any file finishes with .tt, Thor considers it to be a template and places it in the destination without the extension .tt.

# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as
# configuration
$ CONFIG_PATH="ci/configs/react.yml" APP_NAME="enterprise" ./ci/bin/build-and-test

# or do it manually:
#
# CONFIG_PATH must be relative to the dir that the rails app is created in
# because the template is run by `rails new` which uses the rails app dir as
# it's working dir, hence the `../` at the start.
#
$ rm -rf mydemoapp && CONFIG_PATH="../ci/configs/react.yml" rails new mydemoapp -d postgresql --skip-javascript --skip-docker -m ./template.rb

Rubocop is configured for this repo and is run as part of CI. Run rubocop locally via the usual method:

$ bundle install
$ bundle exec rubocop # optionally adding -A for autofixes

Updating this template to a new Rails version

  1. Change the Rails and Ruby versions in ./target_versions.yml as per the instructions in that file.
  2. Update the template as required to support the new Rails version

Credits

This repo was forked from mattbrictson/rails-template via @joshmcarthur. Many thanks to @mattbrictson upon whose foundation we are building.

Beyond the folks in the contributor graph, the ideas and choices in this template have been shaped by all the Ackama Ruby team, past and present ❤️.

About

Application template for Rails 7 projects; preloaded with best practices for TDD, security, deployment, and developer productivity.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published