{"id":13878659,"url":"https://github.com/ackama/rails-template","last_synced_at":"2025-05-16T03:03:51.794Z","repository":{"id":37104626,"uuid":"123519312","full_name":"ackama/rails-template","owner":"ackama","description":"Application template for Rails 7 projects; preloaded with best practices for TDD, security, deployment, and developer productivity.","archived":false,"fork":false,"pushed_at":"2025-05-11T19:29:01.000Z","size":1459,"stargazers_count":350,"open_issues_count":42,"forks_count":19,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-11T20:26:06.695Z","etag":null,"topics":["ackama","rails","rails-template","ruby","template","tooling"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ackama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-02T02:27:56.000Z","updated_at":"2025-05-11T19:29:04.000Z","dependencies_parsed_at":"2023-12-14T20:47:45.013Z","dependency_job_id":"c93acbd1-14d9-4b64-9b8f-6179a79d88b3","html_url":"https://github.com/ackama/rails-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Frails-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Frails-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Frails-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ackama%2Frails-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ackama","download_url":"https://codeload.github.com/ackama/rails-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459084,"owners_count":22074604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ackama","rails","rails-template","ruby","template","tooling"],"created_at":"2024-08-06T08:01:55.928Z","updated_at":"2025-05-16T03:03:46.785Z","avatar_url":"https://github.com/ackama.png","language":"Ruby","funding_links":[],"categories":["Rails Templates 👷 (open source)","Ruby","Starters/Boilerplates"],"sub_categories":["Articles"],"readme":"# Ackama Rails Template\n\n[![Rails Template CI](https://github.com/ackama/rails-template/actions/workflows/ci.yml/badge.svg)](https://github.com/ackama/rails-template/actions/workflows/ci.yml)\n\nThis is a template you can use to create new Rails applications.\n\n- [Ackama Rails Template](#ackama-rails-template)\n  - [Background](#background)\n  - [Features](#features)\n  - [Other templates](#other-templates)\n  - [Requirements](#requirements)\n  - [How do I use this?](#how-do-i-use-this)\n  - [How do I use this template for every Rails app I create?](#how-do-i-use-this-template-for-every-rails-app-i-create)\n  - [Contributing](#contributing)\n    - [Updating this template to a new Rails version](#updating-this-template-to-a-new-rails-version)\n  - [Credits](#credits)\n\n## Background\n\nThis template is the set of things we (the Ackama Ruby team) want in **every**\nRails application we create, based on 10+ years of creating new Rails\napplications, numerous pen-tests and then maintaining those applications for\nyears.\n\nSome of these choices are objectively good ideas, some of them are subjective\nopinions :shrug:. We are delighted when other teams find this template useful as\neither the starting point for their apps, or as the starting point for creating\ntheir own in-house template.\n\n## Features\n\nWhere possible we stick to Rails defaults.\n\n- General\n  - [puma](https://github.com/puma/puma) as application server\n  - [Yarn](https://yarnpkg.com/) for managing JS packages\n  - PostgreSQL as database. This template only supports PostgreSQL.\n  - A much-improved `bin/setup` script\n  - Install [dotenv](https://github.com/bkeepers/dotenv)\n  - Create a `doc/` directory for docs\n  - Add a middleware to implement HTTP Basic Auth by setting environment\n    variables. We use this regularly for pre-production envs.\n  - Use [okcomputer](https://github.com/sportngin/okcomputer) for health check\n    endpoints. Configured in\n    [./variants/backend-base/config/initializers/health_checks.rb](./variants/backend-base/config/initializers/health_checks.rb)\n  - Install [lograge](https://github.com/roidrage/lograge) for better logs in\n    production.\n  - Create `app/services` as the place to hold our plain ol' Ruby objects\n    wherein we put most of our business logic.\n  - Override the default ActiveStorage base controller to force the team to make\n    a decision about whether ActiveStorage files must be behind authentication\n    or not. The default Rails behaviour here can be a security gotcha.\n- Security\n  - Configure [`osv-detector`](https://github.com/G-Rath/osv-detector) to run in\n    CI\n  - Install and configure [brakeman](https://github.com/presidentbeef/brakeman)\n  - Create `.well-known/security.txt`\n  - Add a well documented\n    [Content Security Policy initializer](./variants/backend-base/config/initializers/content_security_policy.rb)\n    with secure defaults.\n  - Install [pundit](https://github.com/varvet/pundit) as our preferred\n    authorization gem\n- Error reporting\n  - Setup Sentry for error reporting\n- Code style\n  - Add [EditorConfig](https://editorconfig.org/) config file\n    ([.editorconfig](./editorconfig))\n  - JS/HTML/CSS: [Prettier](https://prettier.io/), Set up with an\n    [Ackama prettier config](https://github.com/ackama/prettier-config-ackama)\n    and a variety of other prettier plugins, see the full list in\n    [variants/frontend-base/template.rb](./variants/frontend-base/template.rb)\n  - JavaScript: [ESlint](https://eslint.org/), Ackama uses the rules found at\n    [eslint-config-ackama](https://github.com/ackama/eslint-config-ackama)\n    Styles: [stylelint](https://github.com/stylelint/stylelint)\n  - Ruby: [Rubocop](https://github.com/rubocop-hq/rubocop), with\n    [ackama rubocop settings](./rubocop.yml.tt)\n  - Install [Overcommit](https://github.com/sds/overcommit) for managing custom\n    git hooks. Configure it with our default settings:\n    [overcommit.yml](./overcommit.yml)\n  - Use [erb_lint](https://github.com/Shopify/erb-lint) to lint HTML in ERB and\n    run Rubocop on Ruby snippets within ERB\n- General testing\n  - RSpec for tests\n  - Install [webdrivers](https://github.com/titusfortner/webdrivers)\n  - Install [Simplecov](https://github.com/simplecov-ruby/simplecov) for test\n    coverage. Configures it with our defaults.\n  - Debug system specs using a visible browser (not headless) by adding\n    `HEADFUL=1` environment variable to your command line\n- Accessibility testing - sets up automated accessibility testing.\n  - Install [axe](https://www.deque.com/axe/) and\n    [lighthouse](https://developers.google.com/web/tools/lighthouse) to provide\n    comprehensive coverage.\n    - Axe Matchers is a gem that provides cucumber steps and rspec matchers that\n      will check the accessibility compliance of your views. We require a\n      default standard of wcag2a and wcag2aa.\n    - We recommend that your tests all live in a `spec/features/accessibility`,\n      to allow for running them separately. Using the shared examples found at\n      `variants/accessibility/spec/support/shared_examples/an_accessible_page.rb`\n      for your base tests avoids duplication and misconfiguration.\n  - Install our\n    [lighthouse matchers](https://github.com/ackama/lighthouse-matchers) gem\n    which provide RSpec matchers to assess the accessibility compliance of your\n    application.\n    - We recommend setting your passing score threshold to 100 for new projects.\n      As with Axe, you can keep your test suite tidy by placing these tests in\n      `spec/features/accessibility`.\n- Front-end\n  - Rename `app/javascript` to `app/frontend`\n  - Setup Shakapacker (the maintained fork of Webpacker).\n  - \u003e **Note** We are trialing the new JS packaging options that Rails 7+\n    \u003e provides. For now our default is still Shakapacker because it provides us\n    \u003e the most flexibility.\n  - Initializes Ackama's linting and code formatting settings, see\n    [Code linting and formatting](#code-linting-and-formatting)\n- Performance testing\n  - Add configuration and specs to use to perform a\n    [lighthouse performance](https://web.dev/performance-scoring/) audit,\n    requiring a score of at least 95.\n- N+1 queries\n  - Install \u0026 configure [bullet](https://github.com/flyerhzm/bullet) to help\n    prevent N+1 queries\n- Devise (optional)\n  - Install devise and tweak the configuration. if enabled in the configuration\n    file.\n  - Configure devise to destroy session cookies on log out (this comes up\n    regularly in penetration tests)\n- Bootstrap (optional)\n  - Installs and configures\n    [Bootstrap](https://getbootstrap.com/docs/5.0/getting-started/introduction/)\n    if enabled in the configuration file.\n- React (optional)\n  - Add configuration and example components if enabled in the configuration\n    file.\n  - Based on [rails-react](https://github.com/reactjs/react-rails)\n  - The relevant config files are found in `variants/frontend-react`.\n  - An example react test using\n    [react-testing-library](https://testing-library.com/docs/react-testing-library/intro/)\n    is provided. Before you start adding more tests, it is recommended you read\n    [common-mistakes-with-react-testing-library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)\n- Typescript (optional)\n  - Install and configure Typescript including linting\n- Sidekiq (optional)\n  - Install and configure Sidekiq\n\n## Other templates\n\nSome functionality which isn't something we need on every app is available in\nour other templates:\n\n- [Rails template to enable SSL/TLS for local development](https://github.com/ackama/rails-template-ssl-local-dev)\n- [Rails template to render PDFs using Puppeteer and Chrome](https://github.com/ackama/rails-template-pdf-rendering)\n\n## Requirements\n\nBefore running this template, you must have the following installed on your\nmachine:\n\n- Yarn v1.21.0 or later\n- Rails 7.1.x\n\nThe following are not strictly required to run the template but you will need it\nto start the Rails app that this template creates:\n\n- [PostgreSQL](https://www.postgresql.org/)\n- [Chromedriver](https://chromedriver.chromium.org/)\n\n## How do I use this?\n\nThis template requires a YAML configuration file to to configure options. It\nwill use a file called `ackama_rails_template.config.yml` in your current\nworking directory if it exists. Otherwise you can specify a path using the\n`CONFIG_PATH` environment variable.\n\n[ackama_rails_template.config.yml](./ackama_rails_template.config.yml) is a\ndocumented configuration example that you can copy.\n\nYou must also have Postgres running on port 5432.\n\nTo generate a Rails application using this template, pass the `--template`\noption to `rails new`, like this:\n\n```bash\n# Ensure you have the latest version of Rails\n$ gem install rails\n\n# Example 1\n# #########\n\n# Create a config file using the example\n$ wget https://raw.githubusercontent.com/ackama/rails-template/main/ackama_rails_template.config.yml\n\n# Tweak the config file as you see fit\n\n# Create a new app using the template. Template options will be taken from\n# ./ackama_rails_template.config.yml\n$ rails new my_app --no-rc --database=postgresql --skip-javascript --skip-docker --template=https://raw.githubusercontent.com/ackama/rails-template/main/template.rb\n\n# Example 2\n# #########\n\n# Create a custom config YAML file, saving as ./my_custom_config.yml\n\n# Template options will be taken from ../my_custom_config.yml (relative to the new app directory)\n$ 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\n```\n\nHere are some additional options you can add to this command. We don't\n_prescribe_ these, but you may find that many Ackama projects are started with\nsome or all of these options:\n\n- `--skip-action-mailbox` skips the setup of ActionMailbox, which you don't need\n  unless you are receiving emails in your application.\n- `--skip-active-storage` skips the setup of ActiveStorage. If you don't need\n  support for file attachments, this can be skipped.\n- `--skip-action-cable` - if you're not doing things with Websockets, you may\n  want to consider skipping this one to avoid having an open websocket\n  connection without knowing about it.\n\n## How do I use this template for every Rails app I create?\n\nThe `rails` command will pull options from a `.railsrc` file in your home\ndirectory. These options will be applied as arguments each time you run\n`rails new` (unless you pass the `--no-rc` option).\n\nTo make this the default Rails application template on your system, create a\n`~/.railsrc` file with these contents:\n\n```\n# ~/.railsrc\n-d postgresql\n--skip-javascript\n--skip-docker\n-m https://raw.githubusercontent.com/ackama/rails-template/main/template.rb\n```\n\nOnce you've installed this template as your default, then all you have to do is\nrun:\n\n```bash\n$ rails new my-awesome-app\n```\n\n## Contributing\n\nThis project works by hooking into the standard Rails\n[application templates](https://guides.rubyonrails.org/rails_application_templates.html)\nsystem, with some caveats. The entry point is the\n[template.rb](https://github.com/ackama/rails-template/blob/main/template.rb)\nfile in the root of this repository.\n\nNormally, Rails only allows a single file to be specified as an application\ntemplate (i.e. using the `-m \u003cURL\u003e` option). To work around this limitation, the\nfirst step this template performs is a `git clone` of the\n`ackama/rails-template` repository to a local temporary directory.\n\nThis temporary directory is then added to the `source_paths` of the Rails\ngenerator system, allowing all of its ERb templates and files to be referenced\nwhen the application template script is evaluated.\n\nRails generators are very lightly documented; what you'll find is that most of\nthe heavy lifting is done by [Thor](http://whatisthor.com/). Thor is a tool that\nallows you to easily perform command line utilities. The most common methods\nused by this template are Thor's `copy_file`, `template`, and `gsub_file`. You\ncan dig into the well-organized and well-documented\n[Thor source code](https://github.com/erikhuda/thor) to learn more. If any file\nfinishes with `.tt`, Thor considers it to be a template and places it in the\ndestination without the extension `.tt`.\n\n```bash\n# create new rails app in tmp/builds/enterprise using ci/configs/react.yml as\n# configuration\n$ CONFIG_PATH=\"ci/configs/react.yml\" APP_NAME=\"enterprise\" ./ci/bin/build-and-test\n\n# or do it manually:\n#\n# CONFIG_PATH must be relative to the dir that the rails app is created in\n# because the template is run by `rails new` which uses the rails app dir as\n# it's working dir, hence the `../` at the start.\n#\n$ rm -rf mydemoapp \u0026\u0026 CONFIG_PATH=\"../ci/configs/react.yml\" rails new mydemoapp -d postgresql --skip-javascript --skip-docker -m ./template.rb\n```\n\nRubocop is configured for this repo and is run as part of CI. Run rubocop\nlocally via the usual method:\n\n```\n$ bundle install\n$ bundle exec rubocop # optionally adding -A for autofixes\n```\n\n### Updating this template to a new Rails version\n\n1. Change the Rails and Ruby versions in\n   [./target_versions.yml](./target_versions.yml) as per the instructions in\n   that file.\n2. Update the template as required to support the new Rails version\n\n## Credits\n\nThis repo was forked from\n[mattbrictson/rails-template](https://github.com/mattbrictson/rails-template)\nvia [@joshmcarthur](https://github.com/joshmcarthur). Many thanks to\n[@mattbrictson](https://github.com/mattbrictson) upon whose foundation we are\nbuilding.\n\nBeyond the folks in the contributor graph, the ideas and choices in this\ntemplate have been shaped by all the Ackama Ruby team, past and present :heart:.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Frails-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fackama%2Frails-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fackama%2Frails-template/lists"}