search

starterkits / rails4-starterkit

Rails 4.1 starter app with production ready performance, security, and authentication.
MIT License
388 stars 103 forks source link

readme

= Rails 4.1 Starter Kit

Bootstrap 3 / Foundation 5 + CoffeeScript + Sass + Devise + everything else you need to get into production, fast.

= Overview

Rails 4.1 Starter Kit is a starter app with production ready performance, security, and authentication.

This project was extracted from several apps running in production over the past couple of years and upgraded to Rails 4.1.

Unlike most starter apps that focus on kick starting development, Rails 4.1 Starter Kit is opinionated and production ready. It combines the best gems, best practices, and optimized configuration to minimize common mistakes and repetitious framework setup.

Beyond configuration and tests, the bulk of Rails 4.1 Starter Kit code is the authentication flows. The app provides well designed UX flows for social logins (Facebook, Twitter, etc.) as well as connecting additional accounts after sign up.

== Demo

{Demo}[https://rails4-starterkit.herokuapp.com] — Bootstrap 3

{Email Template Preview}[https://rails4-starterkit.herokuapp.com/p/email?premail=true&layout=email] — with inline CSS via Premailer

== Status

== Features

UI/UX

Configuration

BDD/TDD

Admin

Background Jobs

Error Reporting

Maintainable CSS

Emails

Databases

Production Ready

= Requirements

The following services need to be running on localhost in order for rails server to start without modifying config files.

= Installation

Gemfile is configured for OSX development. See comments in Gemfile for Linux.

git clone https://github.com/starterkits/rails4-starterkit.git cd rails4-starterkit

For Bootstrap 3, stay in master branch

For Foundation 5, check out foundation branch

git checkout foundation

bundle install

Make sure postgres, memcached and redis are running locally

On OSX with brew...

/usr/local/opt/memcached/bin/memcached redis-server /usr/local/etc/redis.conf postgres -D /usr/local/var/postgres

Setup the db

rake db:setup

Modify vars in config/application.yml. Generate new secret tokens or your app will be hackable!

Modify config/locales/en.yml. Replace references to StarterKit.

Modify config/application.rb. Replace references to StarterKit.

= Development

Spring is enabled by default. To use Zeus, comment out spring gems in Gemfile and uncomment zeus.

Spring

rails server bundle exec guard

Zeus

zeus start zeus server bundle exec guard

Open in browser: http://0.0.0.0:3000

Running rails server will start WEBrick. To run unicorn in development, use unicorn -c config/unicorn.rb or foreman[https://github.com/ddollar/foreman].

Twitter and Facebook demo app credentials use callback urls for http://0.0.0.0:3000

= Debugging

Ruby 2.0+ uses byebug instead of debugger. Starter Kit is configured to use pry or byebug.

Add pry or byebug to code

binding.pry byebug

To debug a background worker, start the rails server and sidekiq in separate processes.

rails server bundle exec sidekiq -C config/sidekiq.yml

Add byebug to worker code to debug

Use Sidekiq's web UI to restart jobs if needed: http://0.0.0.0:3000/admin/sidekiq/jobs/retries

= Testing

{Build Status}[https://travis-ci.org/starterkits/rails4-starterkit]

For BDD/TDD, just keep guard running in the background. The relevant tests will automatically run when code is added or modified.

To run the full test suite without guard...

Spring

rspec spec

Without Spring

DISABLE_SPRING=true rspec spec

Zeus

zeus test spec

Note that Sidekiq does not process jobs in tests.

= Production

Setup Heroku

heroku create [app name]

Copy and paste

heroku addons:add heroku-postgresql heroku addons:add memcachier heroku addons:add newrelic heroku addons:add pgbackups heroku addons:add redistogo heroku addons:add sendgrid heroku config:add DEVISE_SECRET_KEY="$(bundle exec rake secret)" heroku config:add DEVISE_PEPPER="$(bundle exec rake secret)" heroku config:add SECRET_KEY_BASE="$(bundle exec rake secret)" heroku config:set REDIS_URL=heroku config:get REDISTOGO_URL

Needs customization

heroku config:add MAIL_HOST=[YOUR APP URL]

git push heroku master

heroku run rake db:migrate heroku open

Be sure to configure social login keys to get Facebook/Twitter/etc. login to work.

Install Errbit

Starter Kit is setup to use Airbrake or Errbit for error tracking and reporting. Errbit is an open source alternative to Airbrake that can be hosted for free on Heroku.

See https://github.com/errbit/errbit for installation.

After setting up Airbrake or Errbit, update your server ENV vars.

In rails4-starterkit dir

heroku config:add AIRBRAKE_API_KEY=[YOUR KEY] heroku config:add AIRBRAKE_HOST=[YOUR-ERRBIT-APP.herokuapp.com]

Send test

rake airbrake:test

Additional Steps

StarterKit is pre-configured to make it easy to deploy apps into production environments. However, it's a good idea to consider the following steps to make your app production ready:

= Updating

Starter Kit Gemfile does not specify gem versions in order to make upgrading easier.

bundle update

To merge changes from Starter Kit

git remote add upstream https://github.com/starterkits/rails4-starterkit.git

Fetch latest upstream changes

git fetch upstream

git merge upstream/master

or

git cherry-pick [COMMIT REF]

= Compatibility

= Auth Flows

There are three hard coded auth flows:

  1. signup — new user registration flow
  2. login — returning user authentication flow
  3. connect — authenticated user social account connection flow

In each flow, the user is returned to the page he/she was on at the beginning of the flow if appropriate.

Signup and login flows have an intermediate step (RegistrationsController#after_auth) that prompts the user for any missing required information. This is useful when new required fields are added to User, terms of service updates, etc. It's also useful for minimizing input fields on the first sign up page. For instance, the app might just ask for the user's desired username on the first page and then use the intermediate page to get first name, email, etc.

== Sign Up

Start at /a/signup

OAuth

  1. RegistrationsController#after_auth
  2. If user.valid? redirect to origin or user_root_path
  3. If user.invalid? show intermediate page so user can add additional info
    1. Post to RegistrationsController#create

If user already had an account via the OAuth provider, he/she is simply logged in.

Username/Password

  1. Post to RegistrationsController#create
  2. Show intermediate page if additional info is needed
  3. Redirect to origin or user_root_path

== Login

OAuth

If user does not already have an account via the OAuth provider, redirect to sign up page.

Otherwise, login user and redirect to either...

  1. RegistrationsController#after_auth if additional account info is needed
  2. Origin page if specified
  3. user_root_path

Username/Password

Same as OAuth flow above.

= Mail Previews

Rails 4.1 introduced mailer previews. Starter Kit now has two ways to preview emails:

Mail previews are only available in development by default. To make Starter Kit previews available in other environments, set the ALLOW_EMAIL_PREVIEW='1'.

= TODO