Skip to content

Latest commit

 

History

History
355 lines (223 loc) · 11.8 KB

README.rdoc

File metadata and controls

355 lines (223 loc) · 11.8 KB
Raw

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 — Bootstrap 3

Email Template Preview — with inline CSS via Premailer

Status ↑

  • Configuration: excellent — all configuration keys are in one file and overridable with ENV vars

  • Development: good — support for Zeus and Spring

  • Test: fair — 65% code coverage; auth flows need more tests

  • Production: good — used in several production apps

Features ↑

UI/UX

  • Turbolinks — fast page rendering; configured to play nice with HeadJS, AJAX, etc.

  • HeadJS — fast and flexible JavaScript loading

  • NProgress — mobile app style loading indicator for AJAX requests

  • Fully baked authentication flows

    • Devise + Omniauth — password and OAuth logins

    • Intelligent handling of login, sign up and connect account flows

    • Pre-filling of registration forms from social data

    • Extracted from several years of production apps and real world UX testing

    • Stubbed out code for merging accounts; common social login UX problem

Configuration

  • All app settings are in config/application.yml with automatic overriding by ENV vars

  • Development secrets are checked into git for convenience

  • Production secrets are configured via server ENV vars

BDD/TDD

  • Spring / Zeus — fast development and testing startup; Spring is enabled by default

  • Rspec — tests, somewhat following BetterSpecs

  • SimpleCov — code coverage

  • Guard — automatically run tests on code change

Admin

Background Jobs

  • Sidekiq — fast, memory efficient background jobs

Error Reporting

Maintainable CSS

  • Bootstrap3 enabled — master branch

  • Foundation5 enabled — foundation branch

  • BEM class names — prevents class name collision

  • SASS @extend — keeps Bootstrap specific class names out of the views, making it easier to switch CSS frameworks

Emails

  • Ink — Zurb’s email templates for maximum email client compatibility

  • Premailer — automatically inlines CSS styles, making it easy to customize email templates without sacrificing compatibility

  • Previewable — easily preview emails in development

  • Scalable — User and Devise are configured to send emails via background jobs

Databases

  • PostgreSQL — app data; switchable to MySQL, MongoDB, etc.

  • Redis — background job queues

  • Memcached — session data

Production Ready

  • Heroku ready — git clone, configure, git push heroku master and you’re done

  • Free hosting — configured to run web and job processes in single Heroku dyno to get started

  • Unicorn — web server

Requirements ↑

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

  • PostgreSQL — app data; switchable to MySQL, MongoDB, etc.

  • Redis — background job queues

  • Memcached — session data

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: 0.0.0.0:3000

Running ‘rails server` will start WEBrick. To run unicorn in development, use `unicorn -c config/unicorn.rb` or foreman.

Twitter and Facebook demo app credentials use callback urls for 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: 0.0.0.0:3000/admin/sidekiq/jobs/retries

Testing ↑

<img src=“https://travis-ci.org/starterkits/rails4-starterkit.png?branch=master” alt=“Build Status” />

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

  • split worker and web processes into separate servers or dynos

  • add SSL with CloudFlare, Heroku SSL, or similar

  • add Pingdom or other monitoring service with HTML parsing to analyze page content

  • setup Errbit or Airbrake and configure StarterKit to track errors

  • send syslogs to a central logger that supports searching and filtering

  • use a security service to analyze site for common security holes (XSS, etc.)

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 ↑

  • IE 8+ unless additional shims are added

    • See app/assets/stylesheets/icons_social.scss

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

  4. 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 ↑