Home

Awesome

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 :shrug:. 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.

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:

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:

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 :heart:.