Rails 5 Boilerplate

A MVP ready boilerplate for Rails 5 apps.

Everything used in this repo is open source, free, or optional.

This repo focuses on getting your project setup ASAP with all the tooling to start deploying from your first commit.

✨ Features

User Accounts & Authentication: Devise
Feature Switching with a UI: flipper
Admin Dashboard UI: ActiveAdmin
Secrets Management: dotenv
Livereload for Development: Guard
Upgraded Testing Suite: RSpec, faker, factory_bot
Static Analyses: Brakeman, Rubopcop
Continuous Integration: CircleCI, CodeClimate
Code Coverage Reporting with a UI: simplecov

📝 Guides

📦 Getting Started

To setup the repo locally start by cloning it locally:

git clone https://github.com/TristanToye/rails-5-boilerplate.git
cd rails-5-boilerplate

🔧 Local Setup

Next you need to install all the dependiencies:

ruby 2.5.1
rails 5.2
postgres

To accomplish this I recommend the following:

install homebrew
install RVM
install ruby 2.5.1
install rails 5.2
install postgres 10

This guide walks you through it in details: http://railsapps.github.io/installrubyonrails-mac.html

The only issue you might run into is setting up Postgres. If you use the recommend Postgres app (do this). When installing the pg gem you will need to run the following:

gem install pg -- --with-pg-config=/Applications/Postgres.app/Contents/Versions/10/bin/pg_config

Or you can add the app's config to your ~./bash_profile:

export PATH="/Applications/Postgres.app/Contents/MacOS/bin:$PATH"

Once you have everything installed, run bundler to get our gems setup:

$ bundle install

🔒 Setup Secrets

For most credentials we want to use the new Rails 5.2 credential management. This article explains it well with examples: https://medium.com/cedarcode/rails-5-2-credentials-9b3324851336

To get started here go delete my credentials located at /config/credentials.yml.enc.

We will start by adding a secret_key_base to this file:

$ rake secrect
840f20e6084666b7aabe9d94...
$ EDITOR="code --wait" rails credentials:edit

# In the credentials file add the following
secret_key_base=840f20e6084666b7aabe9d94...

We also likely want to handle some environment variables locally. We use a git-ignored file to load them when the app starts.

Create a new file .env in the root of the repo. This will load any environment variables you might need to set in the future.

🗃 Generate Local Database

Makes sure postgres is running and setup your database:

$ rails db:setup db:migrate

Now you should be able to start your rails app and load it in your browser at http://localhost:3000:

# to start with spring and all the goodies
$ guard

# OR to start just the rails server
$ rails s

🐬 Feature Switches

This app uses the lovely Flipper gem to manage features.

It is protected with a basic auth. Add the following to your credentials:

$ EDITOR="code --wait" rails credentials:edit

# In the file
flipper:
  user_name: YOUR_USERNAME
  password: YOUR_PASSWORD

Then navigate to http://localhost:3000/flipper/features & enter your credentials.

Add the feature show_auth and enable it for everyone. This should show the login/signup links on the index of the app.

🔑 Admin Dashboard

This app uses the ActiveAdmin gem to generate an admin UI.

This is already up and running as part of your app! You just need to create an admin user to access it.

Signup on your app and try navigate to http://localhost:3000/admin - you should be unable to access it yet.

You need to set the boolean column admin on your user account to true.

This is pretty fast to do from the rails console:

$ rails c
> User.find_by(email: 'YOUR_ACCOUNTS_EMAIL').update(admin: true)

Now navigate to http://localhost:3000/admin and you should see the blank admin UI.

You will need to read the docs to find out how to extend this for your own purposes.

✅ Testing

You can start your app, and run your livereloading test suite with one command: $ guard

Once guard is running, simply push return to run all tests & static checks. For more info check the Guard related gems in the Gemfile.

To run the test suite on its own: $ rspec

For more info check the RSpec related gems in the Gemfile.

🔧 Code Coverage

Code coverage is setup with simplecov.

Run your test suite: $ rspec

In your apps directory open ./coverage/index.html in a browser to view a UI for the code coverage of your app.

If you start the app with the $ guard command the code coverage will update coverage on each saved change.

🚨 Static Analysis

There are multiple gems integrated in this app for static analysis.

These all run as part of the $ guard command during development.

Rubocop: ruby style guide, read more here. To use run: $ rubocop.

Brakeman: security analysis, read more here. To use run: $ brakeman.

🚀 Deployment

We are going to deloy this Heroku

Create an account and create your first app. Add to your app the free tier of Heroku Postgres & Papertrail.

Next install the CLI locally & login: https://devcenter.heroku.com/articles/heroku-cli

Add your .env variables to the settings tab on your Heroku app.

You will also need to add the contents of your config/master.key file to Heroku as RAILS_MASTER_KEY in the same setting location to allow Heroku to use your credentials.

Deploy your repo from the deploy tab by connecting your github account and selecting the repo OR follow the linked guide below to deloy directly from your machine.

Finally, run the following to setup you database on the Heroku Postgres instance:

heroku run rails db:migrate -a APP_NAME`

Heroku has a great set of documentation on how to get setup: https://devcenter.heroku.com/articles/getting-started-with-rails5

👷 Continuous Integration

This section could be expanded, but out of ther box there are some basic tools in place.

CircleCi

Use this for CI with Heroku to ensure all your tests pass before deploying a new version, before merging your latest PRs etc.

You get one free linux bos to run tests on: https://circleci.com

Connect your github account and select the repo to start running tests.

By default this is configured to push code coverage to CodeClimate (see below).

If you don't want to use CodeClimate comment out lines 94-96 from .circleci/config.yml:

      - send-code-coverage:
          requires:
            - build-rails

Once setup and you have your tests passing you can enable the option on Heroku to Wait for CI to pass before deploy from the Deploy tab of you app.

CodeClimate

Use this for tracking issues, code coverage etc.

Free for open source: https://codeclimate.com/

Add this environment variable to CirclCi: CC_TEST_REPORTER_ID

I highly recommend installing the browser extension as we: https://chrome.google.com/webstore/detail/code-climate/phgahogocbnfilkegjdpohgkkjgahjgk

✉️ Mailer Setup

GMail SMTP Free Sending

If you have a gmail account this is a simple solution. You might want to create a new Gmail just for this app.

Add to your credentials the following:

$ EDITOR="code --wait" rails credentials:edit

# In the file opened add
email:
  host: smtp.gmail.com
  user_name: YOUR_GMAIL_EMAIL
  password: YOUR_GMAIL_PASSWORD

Mail Service

You will require a real domain that you own to send email from.

Verify your domain with them.

Select SMTP sending and get their config.