README

== Welcome to the SaaS Rails Kit

This kit will help you get a quick start on building new web
applications that need a recurring billing component and have
multiple plan levels that are charged at varying rates. Typical
examples of this kind of Rails application are the services
offered by 37signals: Basecamp, Backpack, etc.

The kit comes configured to allow customers to paid accounts with
a 1 month free trial without collecting payment information.
Emails are sent to remind customers when a trial account is about
to expire, when the plan level gets changed, when payment is made,
and when an account is canceled.

Though there is an active? method in Account, the method is not
used anywhere in the application. It's up to you to decide what to
do for accounts that are no longer active due to an expired trial
or a failed credit card charge. In my Catch the Best application,
I simply call that method in a before filter and render a template
directing the user to the enter billing information if that method
returns false.

== Getting Started

This code provides a complete, running Rails application. There are
a few things you need to do to get started, though. First, you
should create your database using 'rake db:create' (by default the
app is configured to use MySQL). Then, you need to create the
database tables and load some initial data, which can be done with
the following rake command on the command line:

rake db:bootstrap

Once that's done, you are ready to go. Start up the app and browse
to it in your web browser. Log in with the login test and the
password test, and you'll be logged in as the admin user for a
test customer account.

== Deploying to a Production Server

This kit is designed to be served by a web server configured for
name-based virtual hosting. In my deployments, I point the
"default" configuration at the app so that traffic to any domain
name not explicitly set in my other virtual host sections gets
directed to the application.

For the "public" web site, where one typically has a welcome page,
tour, etc., create a separate virtual host for www.yourdomain.com
or yourdomain.com, and forward all urls that begin with /signup to
the Rails application. You'll notice in config/routes.rb that the
pricing grid, account creation page, and sign-up thank-you page
are all served with urls that start with /signup. If the layout
for your public site will differ from the layout of the
application, add a new layout to app/views/layouts and edit
app/controllers/accounts_controller.rb to change the new, plans,
and thanks actions to use that layout.

The application is written to allow all admins to update their
payment information while logged in to an account, which means
that SSL connections will be attempted for all the subdomains of
your base domain. Unless you want SSL certificate warnings for
your customers, then, you'll need to get a wildcard SSL
certificate. I use GoDaddy to purchase mine: currently $200 per
year. Of course you could rewrite the billing action in
app/controllers/accounts_controller.rb to redirect to a specific
subdomain to avoid the cost of a wildcard SSL cert... feel free to
do so. :)

Make sure you set up a cron job to run script/daily_mailer on a
daily basis. This script does the charging for account renewals
and sends notices of expiring trials.

== PayPal

PayPal payments are handled via PayPal's recurring payment profiles,
which are a part of the Website Payments Standard plan. You don't
need to sign up for Website Payments Pro or PayFlow -- just the
basic business plan. There are a couple of caveats when using PayPal
in addition to or in place of a standard credit card gateway:
 - If you require payment information to create a trial account
   (not the default) you can't currently use PayPal as a payment
   option for that. Currently (and this is just a limitation of
   the Kit at present), PayPal info can only be collected for an
   existing account when changing billing information. If you
   allow trial accounts without collecting payment info first,
   this isn't an issue, since as soon as the account is created
   the user can then supply the billing info via PayPal.
 - You will need to enable API access in both your sandbox and
   live paypal accounts.
 - Your customers will be redirected to PayPal to collect billing
   information (of course), but they will also be redirected to
   PayPal when changing to a paid plan.  This is because a new
   recurring payment profile needs to be created with PayPal.  If a
   customer switches from a paid plan to a free plan, no redirect
   happens, as the existing recurring payment profile is simply
   destroyed behind the scenes.
 
== Known Issues

Rail's development mode behavior of reloading the classes with
every request does not play well with the procs used in Account
and Subscription for doing limit checks. This will be apparent if
you test the plan changing functionality with your browser in
development mode. This is not an issue in production mode, where
class reloading is turned off.
 
== Contents

Hopefully you're familiar enough with the basics of Rails that I
don't have to explain what every file in this archive does. If
not, go read some books like Agile Web Development with Rails and
then come back here. With that out of the way, here are some of
the files you'll want to check out:

app/
  controllers/
    users_controller.rb - Here's an example of how you can use
    limits in your application. Notice the before filter to
    enforce the limit, and the include to pull in generic RESTful
    methods. Also notice the scoper method, which is used to scope
    all the finds to the current account (the current_account
    method is defined in ApplicationController). Use this pattern
    throughout your application to make sure users only see the
    data associated with their account.
    
  models/
    account.rb - Near the top of the file you'll notice the Limits
    constant, which is used to set up the various limits you'll be
    checking for plan eligibility and for being able to do various
    things in your app. For example, the user_limit entry in the
    hash checks the count of associated users, and is used to
    create the reached_user_limit? convenience method (right after
    the definition of Limits).
    
    subscription.rb - The Limits constant at the top of this file
    contains the checks that will be executed when an account
    holder attempts to change plans. If the account would exceed
    the limits based on the account's usage, the subscription
    fails validation and its error messages are populated by the
    right-hand side of this hash.
    
    The store_card method is used to authorize and store the
    credit card info with BrainTree. If the account is still in
    the trial period, or is otherwise still current (been charged
    within the last month), the card will just be stored, and the
    next renewal date will be unchanged. Otherwise, the card will
    be charged for the amount that's currently due, and the next
    renewal date will be set to a month in the future.
    
    The charge method is used by the daily_mailer script to bill
    for the subscriptions on the renewal date.
    
  views/
    subscription_notifier/ - All the content for emails sent to
    account owners is here.

config/
  gateway.yml - Login info for credit card gateway.
  
  config.yml - Some settings for the application, fairly
  self-explanatory.
  
  paypal.yml - Login info for PayPal API.
  
lib/
  authenticated_system.rb - This file, from the
  restful_authentication plugin, has been modified to scope logins
  to the account loaded by the hostname.

  model_controller_methods.rb - Shared controller methods that
  come in handy for RESTful controllers.
  
  subscription_system.rb - Included from ApplicationController, this
  module defines the current_account method, critical to scoping
  all queries to the Account loaded from the database based on the
  hostname.
  
script/
  daily_mailer - Charges the credit cards for accounts that need
  to be charged and sends emails to owners of trial accounts a
  week before the trial is set to expire.

== Testing

If you'd like to run the included test suite, install the mocha, rspec, and rspec-rails gems, and then run rake spec.