Bootstrap 3 / Foundation 5 + CoffeeScript + Sass + Devise + everything else you need to get into production, fast.
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 — Bootstrap 3
Email Template Preview — with inline CSS via Premailer
-
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
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
-
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
-
RailsAdmin — admin interface for app data
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
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
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.
Need to initialize postgres user and db
If you want to use slim instead of haml, remove the entries for haml in Gemfile and use
gem "slim-rails"
then, install ‘haml2slim` to convert
If you see error:
Gem::LoadError: You have already activated rake 10.4.2, but your Gemfile requires rake 10.3.2. Prepending `bundle exec` to your command may solve this.
delete Gemfile.lock and run
bundle install
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
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
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.
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.)
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]
-
IE 8+ unless additional shims are added
-
See app/assets/stylesheets/icons_social.scss
-
There are three hard coded auth flows:
-
signup — new user registration flow
-
login — returning user authentication flow
-
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.
Start at /a/signup
OAuth
-
RegistrationsController#after_auth
-
If user.valid? redirect to origin or user_root_path
-
If user.invalid? show intermediate page so user can add additional info
-
Post to RegistrationsController#create
If user already had an account via the OAuth provider, he/she is simply logged in.
Username/Password
-
Post to RegistrationsController#create
-
Show intermediate page if additional info is needed
-
Redirect to origin or user_root_path
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…
-
RegistrationsController#after_auth if additional account info is needed
-
Origin page if specified
-
user_root_path
Username/Password
Same as OAuth flow above.
Rails 4.1 introduced mailer previews. Starter Kit now has two ways to preview emails:
-
localhost:3000/rails/mailers – Rails 4.1 built-in method
-
0.0.0.0:3000/p/email?premail=true&layout=email – Starter Kit method with query param configs
Mail previews are only available in development by default. To make Starter Kit previews available in other environments, set the ALLOW_EMAIL_PREVIEW=‘1’.
-
Add code comments for rdoc
-
Add examples for adding User#username field
-
Setup Rack::Cache devcenter.heroku.com/articles/rack-cache-memcached-rails31
-
Install Devise Security Extension github.com/phatworx/devise_security_extension
-
Review config/initializers/devise.rb in detail
-
Convert to lazy registration github.com/mwlang/lazy_registration_demos
-
Use decorators github.com/drapergem/draper
-
Make sure rspecs follow best practices: betterspecs.org/
-
Run should_clean -d spec/