rails_new

A thoughtfully designed template for building modern Rails apps 🔥

Get started on your new app within minutes instead of hours 🚗💨

• rails_new
  • Getting started
  • Optional configuration options
  • Environment variables
  • Contents
    • Base system
    • General
    • Frontend
    • Development
    • Test
    • Production
  • Removed
  • Notes
    • Account vs User
    • Heroku Buildpacks
    • React
    • TypeScript
    • Hot Module Replacement (HMR)
    • JavaScript/TypeScript Tests
    • Polyfills
    • Custom classes
    • Gemfile.dev / Gemfile.dev.lock
    • Rack::RejectTrace middleware
    • Favicons
  • Docker
    • Usage examples:
  • TODO
  • License

Getting started

To get going clone this repository and perform the following steps:

1. Run rails credentials:edit to re-generate config/master.key and create config/credentials.yml.enc.
2. If your application requires ActiveStorage, run rails active_storage:install to generate a migration that creates the necessary tables. Use rails db:migrate to run the migration.
3. You can now run bin/configure, which will help you in configuring the template.

As an alternative to running the script you can perform all of the following steps manually.

1. Change application name in config/application.rb.
2. Update database.yml to reflect the new application name.
3. Update TODO items in config/environments/production.rb.
4. If you plan on using Figaro, copy config/application.yml.example to config/application.yml.
5. ESLint is preconfigured for modern JS with React support (using Prettier). If you want to use it install packages with npm install / yarn [install], otherwise remove .eslintrc and package.json.
6. If you don't plan on tracking the template, you can remove the remote, otherwise rename it and add your new remote as appropriate.:

   $ git remote rename origin rails_new
   $ git remote add origin ...

Optional configuration options

• If you want to use Sentry, you'll need to:
  1. Create two projects under your organization on Sentry. This way you can keep frontend and backend errors separate.
  2. Set SENTRY_DSN_BACKEND and SENTRY_DSN_FRONTEND environment variables. Both are optional - errors will only be reported if the respective variable is set.
• New Relic is pre configured in config/newrelic.yml, but you need to comment in the environment variables for it work on Heroku (lines 10 and 17).
• The app is preconfigured for Google Analytics, just add GOOGLE_ANALYTICS_ID to the environment.
• We prefer to use vanilla Sidekiq for worker/queue management. If you prefer to use ActiveJob please see the configuration/options that were removed in 59cf38d.

Environment variables

Variable	Comment
SENTRY_DSN_BACKEND	Used to report backend errors to Sentry.
SENTRY_DSN_FRONTEND	Used to report frontend errors to Sentry.
BLOCK_HTTP_TRACE	Disables HTTP TRACE method if set to true/t/1
BUNDLE_GEMFILE	Useful when using a Gemfile.dev
DATABASE_URL	Used for production env, automatically set by Heroku
GOOGLE_ANALYTICS_ID	Will be added to the main application layout if set
HOST	Your base URI, e.g. https://myapp.herokuapp.com
NEW_RELIC_APP_NAME	Used in config/newrelic.yml
NEW_RELIC_LICENSE_KEY	Used in config/newrelic.yml
PORT	Port Puma will listen on, defaults to 3000
RACK_TIMEOUT_SERVICE_TIMEOUT	Limit for Rack::Timeout, defaults to 15 seconds
RAILS_LOG_TO_STDOUT	Set by Heroku Ruby buildpack, set manually on other platforms if needed
RAILS_MAX_THREADS	Number of Puma threads, defaults to 5
REDIS_URL	Used in config/cable.yml
WEB_CONCURRENCY	Number of Puma workers. We default to threads only, no workers

Contents

All of the following have been installed and pre-configured:

Base system

• Ruby
• Ruby on Rails
• PostgreSQL >= 9.2
• pg for ActiveRecord
• NodeJS

NOTE: We recommend that you install and manage these system dependencies using a combination of Homebrew (Postgres), asdf-vm (Ruby, NodeJS) and Bundler (Ruby on Rails). If you are starting fresh on a new system you may want to manage these package managers with a script like the thoughtbot laptop script with the option to add your own opinionated extensions, e.g. this. Your code base should be under version control, why not your system toolkit and configuration as well?

General

• devise
• figaro
• foreman
• fast_jsonapi
• pundit
• sidekiq

Frontend

All of these are managed by yarn.

• bootstrap4
• jquery
• jquery-ujs
• popper.js

Development

• Brakeman
• bullet
• letter_opener
• memory_profiler
• newrelic_rpm
• nullalign
• pry
• pry-byebug
• pry-doc
• rack-mini-profiler
• RuboCop

Test

Rspec has been preconfigured for Rails 5.1+ system tests.

• No need to require 'rails_helper, we do it in .rspec
• bundler-audit (runs on CircleCI)
• capybara
• factory_bot_rails
• shoulda-matchers
• webmock

Production

• sentry-ruby
• heroku-deflater
• lograge
• rails_12factor
• rack-timeout: Configured via env variables, see documentation
• secureheaders

Removed

The following default Rails gems have been removed:

• coffee-rails
• jbuilder

Notes

Account vs User

Authentication concerns (your typical Devise configuration) are handled by the Account model. To connect this to one of several potential user roles the polymorphic authenticatable relationship is used.

Heroku Buildpacks

Note that for everything to work properly on Heroku you need to set up your buildpacks like this:

heroku buildpacks:clear
heroku buildpacks:add heroku/metrics
heroku buildpacks:set heroku/nodejs
heroku buildpacks:add heroku/ruby

React

React support has been preconfigured together with react-rails.

When creating a new component you want to mount in the view, place it under the views folder. react-rails will perform module lookup relative to that folder and automatically require it under the hood so it gets included in the application pack. For example, calling the following helper in your view file:

react_component("dashboard/properties_list")

will require views/dashboard/properties_list and mount it in place of the helper element. See the docs for details about working with react-rails.

TypeScript

TypeScript is supported out of the box.

It is important to note that TypeScript code is loaded by babel-loader. Because of that, you need to perform type checking in a separate process. This could either be your editor, or running yarn types-watch in your terminal to compile your code in watch mode.

This will not interfere with HMR (see below) as TypeScript compiler is instructed only to type-check your code, not to emit compiled modules.

For extra safety, there is a CI build step that runs tsc to make sure TypeScript code compiles

Hot Module Replacement (HMR)

HMR is also supported out of the box. All you need to do is hot-export your module, like so:

import React from "react";
import { hot } from "react-hot-loader/root";

class Welcome extends React.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

export default hot(Welcome);

This will allow you to continue working on your JS code without losing application state in the browser.

JavaScript/TypeScript Tests

The repo comes pre-configured with jest. You can write your tests in JavaScript or TypeScript.

We're following the convention of placing tests next to the file they're testing. They will be run as long as they have test, (e.g. MyComponent.test.ts) in the name.

You are encouraged to place your testing utility files under app/javascript/test.

To run your tests, run:

yarn test

Polyfills

Polyfills are included automatically thanks to @babel/preset-env. See babel.config.js for configuration options.

Custom classes

• ApplicationDecorator: lightweight alternative to Draper or similar gems.
• ApplicationForm: Minimal form class based on ActiveModel.
• ApplicationPresenter: a subclass of ApplicationDecorator for presenters, includes tag helpers.

All custom classes are fully documented with yard and come with generators.

Use yard doc to generate documentation and yard server --reload or yard server --gems to start a local documentation server.

Gemfile.dev / Gemfile.dev.lock

If you want to add specific gems for development that may not be interesting for other developers, you can add a Gemfile.dev (ignored by our .gitignore). Gems listed there can be installed with bundle install --gemfile Gemfile.dev and the resulting lock file is gitignored too.

Example Gemfile.dev:

source 'https://rubygems.org'

eval_gemfile 'Gemfile'

gem 'awesome_print'

The eval_gemfile line will ensure that all gems from your regular Gemfile will be included too. The BUNDLE_GEMFILE variable can be used to let Bundler now which gemfile to use:

BUNDLE_GEMFILE=Gemfile.dev rails c

Rack::RejectTrace middleware

There's a custom middleware (Rack::RejectTrace) for completely disabling the HTTP TRACE method as required by certain security audits. It can be enabled via the BLOCK_HTTP_TRACE environment variable.

Favicons

Favicons were generated with Real Favicon Generator, consider using the same tool when replacing them for your project.

Docker

For those wishing to use Docker for development the whole app has been dockerized and the setup is fairly well-documented. Features:

• Images use Alpine Linux to keep their size small.
• docker-compose.yml sets up and starts Postgres, Redis, Sidekiq, Rails and the Webpack dev server.
• Uses a persistent bundle cache, so there's no need to rebuild the image to add gems.
• Persistent volumes for Postgres and Redis.
• No exposed ports except for Rails (mapped to port 3000 by default)

The following files relate to our Docker setup:

• Dockerfile: main setup for the app container
• docker-compose.yml: Ties Postgres, Redis and app together
• docker-entrypoint.sh: Custom entry point to facilitate bundle caching
• Procfile.docker: Used by the entrypoint script to bring up services
• .dockerignore: similar to .gitignore, specifies files we don't want copied into the container

Usage examples:

Start the environment and build the images if necessary:

$ docker-compose up --build
Building app
[Step 1/12 : FROM ruby:2-alpine
 ---> 8302cc790fbf
Step 2/12 : RUN apk update && apk add --update --no-cache   build-base   chromium   chromium-chromedriver   git   imagemagick   libxml2-dev   libxslt-dev   nodejs   tzdata   postgresql-dev
 ---> Using cache
 ---> 9d1d0b398c26
Step 3/12 : RUN bundle config build.nokogiri --use-system-libraries
 ---> Using cache
 ---> 0a5ca06d7700
Step 4/12 : WORKDIR /app
 ---> Using cache
 ---> c61498ba7e64
[...]

Start the environment without (re-)building images (add -d to daemonize):

$ docker-compose up
Starting rails_new_postgres_1 ... done
Starting rails_new_redis_1    ... done
Starting rails_new_app_1      ... done
Attaching to rails_new_postgres_1, rails_new_redis_1, rails_new_app_1
[...]

Stop the environment but keep the containers:

$ docker-compose stop
Stopping rails_new_app_1      ... done
Stopping rails_new_postgres_1 ... done
Stopping rails_new_redis_1    ... done

Stop the environment and remove the containers:

$ docker-compose down
Stopping rails_new_app_1      ... done
Stopping rails_new_postgres_1 ... done
Stopping rails_new_redis_1    ... done
Removing rails_new_app_1      ... done
Removing rails_new_postgres_1 ... done
Removing rails_new_redis_1    ... done
Removing network rails_new_default

Execute a command inside the app container:

$ docker-compose exec app ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-musl]

Execute a command inside the app container that needs env variables:

$ docker-compose exec --env RAILS_ENV=test app rails db:setup
Created database 'rails_new_test'
-- enable_extension("plpgsql")
   -> 0.0251s
-- create_table("users", {:force=>:cascade})
   -> 0.0366s

Adding a new gem (does not require image rebuild):

# update Gemfile
$ docker-compose exec app bundle

Running specs:

$ docker-compose exec app rspec
....................

Finished in 0.47352 seconds (files took 16.36 seconds to load)
20 examples, 0 failures

TODO

Nothing right now.

License

This project is MIT licensed, see LICENSE.