milia 0.3.38 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bbee764da49ec653dec3714f567a518a160d5e42
+  data.tar.gz: e4835d8ffd9cf753e2cff72fa09798f1af1011e7
+SHA512:
+  metadata.gz: b324efa804d1bd08fd7e49818019fd7bbe8fd924106b22cee933073a8346a7e35a6e5f0d48809db9d393708a13c923708f68aaffc23ba79ce853e70bbfe55bdc
+  data.tar.gz: 04cffd9a266f822467ee296a72a7cf319eecbeb5e61e19cc3d2f1d257c45e313fb50fdea4494461c24f6a48f061eaf11032c54e271e1bd739a2b4e5585a0f11d

data/.gitignore

@@ -0,0 +1,94 @@
+#####################################################################################
+# Rails
+.bundle
+test/db/*.sqlite3
+test/db/*.sqlite3-journal
+log/
+tmp/
+*.log
+tmp/**/*
+.tmp*
+
+# Documentation
+doc/api
+doc/app
+.yardoc
+.yardopts
+rdoc/
+
+# Public Uploads
+public/system/*
+public/themes/*
+
+# Public Cache
+public/javascripts/cache
+public/stylesheets/cache
+
+# Vendor Cache
+vendor/cache
+
+# Acts as Indexed
+index/**/*
+
+# Refinery Specific
+*.tmproj
+*.autobackupbyrefinery.*
+/refinerycms-*.gem
+.autotest
+
+# Mac
+.DS_Store
+
+# Windows
+Thumbs.db
+
+# NetBeans
+nbproject
+
+# Eclipse
+.project
+
+# Redcar
+.redcar
+
+# Rubinius
+*.rbc
+
+# Vim
+*.swp
+*.swo
+*~
+
+# RubyMine
+.idea
+
+# Backup
+*~
+
+# Capybara Bug
+capybara-*html
+
+# sass
+.sass-cache
+.sass-cache/*
+
+#rvm
+.rvmrc
+.rvmrc.*
+
+#gem
+pkg/
+*.gem
+
+# other
+.loadpath
+all.js
+all.css
+temp*.txt
+config/database.yml
+*.dump
+.bashrc
+
+#git
+*.keep
+*.gitkeep

data/.ruby-gemset

@@ -0,0 +1 @@
+milia2

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0

data/Gemfile

@@ -1,17 +1,4 @@
-source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
+source 'https://rubygems.org'
 
-  gem 'rails', '3.2.13'
-  gem 'devise', "2.1.2"
-
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development, :test do
-  gem 'pg'
-  gem "shoulda", "3.5.0"
-  gem "jeweler", "~> 1.6.4"
-  gem 'rdoc'
-  gem 'turn', :require => false
-end
+# Specify your gem's dependencies in milia.gemspec
+gemspec

data/README.md

@@ -1,15 +1,19 @@
 # milia
 
-Milia is a multi-tenanting gem for hosted Rails 3.1 applications which uses
-the devise gem for user authentication.
+Milia is a multi-tenanting gem for hosted Rails 4.0.x applications which use
+the devise gem for user authentication and registrations. Milia comes with 
+tailoring for common use cases needing multi-tenanting with user authentication.
 
-## Basic concepts
+## Basic concepts for the milia multi-tenanting gem
+
+### multi-tenanting highlights
 
 * should be transparent to the main application code
 * should be symbiotic with user authentication
 * should raise exceptions upon attempted illegal access
 * should force tenanting (not allow sloppy access to all tenant records)
-* should allow application flexibility upon new tenant sign-up, usage of eula information, etc
+* should allow application flexibility upon new tenant sign-up, 
+  usage of eula information, etc
 * should be as non-invasive (as possible) to Rails code
 * row-based tenanting is used
 * default_scope is used to enforce tenanting
@@ -21,6 +25,8 @@ performance hit, was seriously time-consuming to backup and restore, was invasiv
 into the Rails code structure (monkey patching), was complex to implement, and
 couldn't use Rails migration tools as-is.
 
+### tenants/users vs organizations/members
+
 A tenant == an organization; users == members of the organization. 
 Only organizations sign up for new tenants, not members (users).  
 The very first user of an organization, let's call him the Organizer, 
@@ -29,174 +35,518 @@ The Organizer becomes the first member (user) of the organization (tenant).
 Thereafter, other members only obtain entry to the organization (tenant) 
 by invitation. New tenants are not created for every new user.
 
+## Version
+
+milia v1.0.0 is the release version for Rails 4.0.x and is now available for usage.
+
+The last previous release version for Rails 3.2.x can be found in the git branch 'v0.3', but
+it is essentially obsolete. Go with v1.0.x
+
+## What's changed?
+
+* Rails 4.0.x adapted (changes to terms, strong_parameters, default_scope, etc)
+* Devise 3.2.x adapted
+* All the changes which version 0.3.x advised to be inserted in applications_controller.rb are now automatically loaded into ActionController by milia.
+* that includes authenticate_tenant!
+* so if you've been using an older version of milia, you'll need to remove that stuff from applications_controller!
+* generators for easy install of basic rails/milia/devise
+* callback after successful authenticate_tenant!
+* debug & info logging and trace for troubleshooting
+* improved invite_member support
+* revised README instructions
+
+## Sample app and documentation
+
+There were numerous requests for me to provide a complete sample web application
+which uses milia and devise. I have done this. This README will have a brief section
+on creating and installing the sample application. Further details about this process
+can be found via the sources listed below:
+
+* see doc/sample.sh for easy generator usage for setting up and creating a working app.
+  Although all the same information is here in this README, it's perhaps clearer, and
+  presented better, as a step-by-step instruction manual. This README must perforce be
+  more as a reference manual.
+* the sample app uses web-theme-app to provide some pleasantly formatted views for your testing pleasure.
+* see doc/manual_sample.sh for complete step-by-step instructions for manually setting up and creating a working app.
+* if you want to know exactly everything the generators are doing, see the manual_sample.sh
+  - instructions are very detailed and loaded with comments (600 lines!).
+  - Stage one: with simple devise and no milia, 
+  - Stage two: installing milia for complete tenanting,
+  - Stage three: adding in invite_member capability
+* the entire sample is also fully available on github, if you wish to check your work. diff can be your friend.
+  this sample on github, however, will always be for the latest release or latest beta (whichever is most recent).
+* find it at: https://github.com/dsaronin/sample-milia-app
+
+### Available docmentation resources for milia
+
+* doc/sample.sh -- this document will ALWAYS be the most recent
+    (for example in the edge branch: "newdev")
+* doc/manual_sample.sh -- non-generator-based instructions for manually editing files.
+    (this may no longer be the most recent since further work will focus on the generators)
+* doc/gemfile_addition.txt -- the additions to Gemfile needed for setting up the sample-milia-app
+    
+* github.com/milia/wiki/sample-milia-app-tutorial
+    this should be the same as the manual_sample.sh doc for the current
+    stable release (or last beta version); but markdown formatted
+    https://github.com/dsaronin/milia/wiki/sample-milia-app-tutorial
+* milia README (this document):
+    - this will be the knowledgable programmer's digest of the essentials
+    - and thus it won't cover some of the intricacies of actually
+      implementing milia: either the tutorial or sample.sh will do that
+    - if you're a first time milia implementer, please use both the 
+      README and either of the two above documents for assistance: it will save you time.
+
+## converting an existing app to multi-tenanted
+
+It is doable, but you'll need to first understand how milia basically is installed. I'd still recommend 
+bringing up the sample-milia-app, getting it working, and then figuring out how to either graft it onto your app.
+Or (recommended), grafting your app onto it. I prefer to work that way because it's based off of a pure Rails 4.0
+and devise 3.2 install.
+
+## Dependency requirements
+
+* Rails 4.0.x
+* Devise 3.2.x
+
+## this readme is for v1.0.0  (fka v1.0.0-beta-7)
+* changes in beta-7: model & controller testing is almost complete; 
+  minor bug fixed;  mixed-in controller methods are now public, not
+  private.
+
+* changes in beta-6: user_params added to Tenant.create_new_tenant;
+  ability to add additional whitelist parameters during config
+
+* changes in beta-5: logging, callback, bug fixes
+
+* changes in beta-4: 
+  corrections to README for Gemfile requirements
+  generator tests for requirements
+
+* changes in beta-3: improved generators getting a new app started
+
+* changes in beta-2: invite_member capability
+
+### edge branch: "newdev"
+
+If I'm actively developing, this can be in a state of flux. Use at your own risk.
+
+## Authorized Roles
+
+Milia doesn't have any requirements re roles for users. But you will probably need
+something in your app to support different roles levels. Devise recommends cancan, but
+I have not used it and do not know how it might affect milia. In my app, I used to use
+ACL9 before it encountered version issues with Rails. Rather than debugging it, I spun
+off my own simplified version which I use now with great success. The gem I wrote is
+open sourced. It is called _kibali_ and is available at github: https://github.com/dsaronin/kibali. 
+Kibali is a simple replacement for ACL9, a role-based authentication gem. 
+I prefer the non-obstrusive nature of kibali and the clear-cut way it deliniates
+roles for actions at the start of each controller. This simplicity was also in ACL9.
+Kibali is primarily oriented for functioning as a before_action role authentication scheme for Rails controllers.
+
 ## Structure
 
 * necessary models: user, tenant
 * necessary migrations: user, tenant, tenants_users (join table)
 
-## Dependency requirements
+You must understand which of your apps models will be tenanted ( <i>acts_as_tenant</i> ) 
+and which will be universal ( <i>cts_as_universal</i>). Universal data NEVER has critical user/company
+information in the table. It is usually only for system-wide constants. For example, if you've put
+too much user information in the users table, you'll need to seperate it out. by definition, the devise 
+user table MUST be universal and should only contain email, encrypted password, and devise-required data.
+ALL OTHER USER DATA (name, phone, address, etc) should be broken out into a tenanted table (say called member_data)
+which belongs_to :user, and in the User model, has_one :member_data. Ditto for organization (account or company)
+information.
+
+Most of your tables (except for pure join tables, users, and tenants) SHOULD BE tenanted. You should rarely have
+universal tables, even for things you consider to be system settings. At some time in the future, your accounts
+(organizations) will want to tailor/customize this data. So might as well start off correctly by making the
+table tenanted. It costs you nothing to do so now at the beginning. It does mean that you will need to seed 
+these tables whenever a new tenant (organizational account) is created.
+
+Finally: 
+
+* tenants = organizational accounts and are created via sign up, a one-time event. this also creates the 
+first MEMBER of that account in your app who is usually the organizing admin. This person can then issue
+invitations (below) to bring other members into the account on the app.
+* members = members WITHIN a tenant and are created by invitation only; they do NOT sign up. An invitation is
+sent to them, they click on an activate or confirm link, and then they become a member of a tenanted group.
+* The invitation process involves creating both a new user (within the current_tenant) and its corresponding
+member_data records.
+* ALL models (whether tenanted or universal) are expected to have a field in the table labelled: tenant_id.
+* YOUR CODE SHOULD NEVER EVER TRY TO CHANGE OR SET THE tenant_id OF A RECORD. milia will not allow it, milia
+will check for deviance; milia will raise exceptions if it's wrong; and milia will override it to maintain integrity.
+* Tenanted records will have tenant_id set to the appropriate tenant automagically by milia.
+* Universal records will have tenant_id always set to nil, automagically by milia; and references to any
+universal table will ALWAYS expect this field to be nil.
+* Pure join tables (has_and_belongs_to_many HABTM associations) get neither designation (tenant nor universal).
+The way that rails accesses these ensures that it will validate the tenant of joined member. A pure HABTM join
+table is created with generation such as follows:
 
-* Rails 3.1 or higher
-* Devise 1.4.8 or higher
+```
+  rails g migration CreateModel1sModel2sJoinTable model1s model2s
+```
 
 ## Installation
 
-Either install the gem manually:
+This README describes two different ways to install:
+* use of a milia generator to install itself and automate those
+  tweaks for most use cases (recommended method)
+* a bare minimum manual setup which requires many minor tweaks;
+  those tweaks will be described in a later section.
+
+Later sections of the README will enumerate:
+* how to create a simple working sample rails/devise/milia application
+* all the expected tweaks which the generator performed automatically
+* advice on advanced usage of milia (from rake tasks, console)
+* specifics about the milia API
+
+  
+## Creating and Installing a Rails/Milia/Devise Sample Application
+
+### Getting started for the sample application
+
+Multi-tenanting, much like user authentication, exists within the large scheme of
+an application. I recommend first creating and installing the following complete, but simple,
+reference Rails application so that you can validate a working setup on your
+system, and have a reference point for making changes to your own application.
+
+### Environment setup
+
+I put these in .bashrc for an Ubuntu system.
 
 ```
-  $ gem install milia
+export PORT=3000
+export RACK_ENV=development
+export SMTP_ENTRY=<my smtp password>
+# OPTIONAL: recaptcha keys
+export RECAPTCHA_PUBLIC_KEY=6LeYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKpT
+export RECAPTCHA_PRIVATE_KEY=6LeBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBgQBv
 ```
 
-Or in the Gemfile:
+### Rails setup
+
+This example shows getting starting a new rails project in an rvm environment and using
+git (github) as the SCM, and expecting to use heroku (eventually) as the PaaS 
+(Platform as a Service) provider. Note: foreman is available when you set up the
+heroku toolbelt (see doc/sample.sh for more details).
+
+This example will set everything up for milia AND devise (you won't need to do devise).
+It assumes you won't use airbrake, you will use recaptcha for new account sign-ups,
+and you will use invite_member capability. Skeleton user, tenant, and member models
+will be created. Before you run db:migrate, you can add any additional fields to the
+tenant and member models. User model really is primarily only used by devise, and so
+you shouldn't add anything to this model as it's a universal model. Member is a tenanted
+model and so this is where all the information for a member should be kept.
 
 ```ruby
-  gem 'milia'
+  $ cd projectspace   # if not there already
+
+  $ rails new sample-milia-app --skip-bundle
+  $ echo "sample-milia-app" > sample-milia-app/.ruby-gemset
+  $ echo "2.0.0" > sample-milia-app/.ruby-version
+  $ echo "web: bundle exec thin start -R config.ru -p \$PORT -e \$RACK_ENV" > sample-milia-app/Procfile
+  $ rvm gemset create sample-milia-app
 ```
-  
-## Getting started
 
-### Rails setup
+Change .gitignore to match your development environment.
+I just copy my standard .gitignore from another project
+but you can copy mine from sample-milia-app on github.
 
-Milia expects a user session, so please set one up
+```
+  $ cd sample-milia-app
+  $ cp ../<an existing project>/.gitignore .
+
+  $ git init
+  $ git add --all .
+  $ git commit -am 'initial commit'
+  $ git remote add origin git@github.com:<git-user>/sample-milia-app.git
+  $ git push -u origin master
+```
+
+### milia and devise setup
+
+This sample web application depends on my updates to the web-app-theme, as
+well as several other gems for the application, which need to be added 
+to the Gemfile, before running the installer.  
+You can directly import these into your Gemfile
+by getting them from <i>doc/gemfile_addition.txt.</i>
+After adding this addition to the Gemfile, please make sure the correct
+milia branch is being designated (it sometimes points to edge branch).
 
 ```
-  $ rails g session_migration
-      invoke  active_record
-      create    db/migrate/20111012060818_add_sessions_table.rb
+   $ vim Gemfile
+     G
+     :r <path to milia gem>/doc/gemfile_addition.txt
+     ZZ
+   $ bundle install
 ```
-  
+
+### WARNING: don't go commando and try to change everything at once! Don't be a perfectionist and try to bring up a fully written app at once!
+
+Just follow the instructions for creating the sample, exactly, step-by-step. 
+Get the basics working. Then change, adapt, and spice to taste.
+Please?! Because I'm more inclined to help you solve problems if you've started out by 
+getting the sample working exactly as described! If you've tried to go off into the jungle on your own, you are, well, on
+your own. And as they say, _"get out the way you got in!"_
+
+
+#### complete generating the sample application
+
+Running the generator below will completely install milia, devise, and a sample app. You will not
+need to run the "milia:install" given above. You'll need to do the following:
+
+```
+  $ rails g milia:install --org_email='<your smtp email for dev work>'
+  $ rails g web_app_theme:milia
+```
+
+NOTE: The above generator has an option to specify an email address to 
+be used for sending emails for confirmation and account activation.
+
+The generator set up basic information for
+being able to send the confirmation & activation emails.
+But, you might need to complete entering in your email and smtp
+information in the following places:
+
+*   _config/environments/development.rb_
+*   _config/environments/production.rb_
+
+#### create the database and migration
+```
+  $ rake db:create
+  $ rake db:migrate
+```
+
+#### test by starting server:
+```
+  $ foreman start
+```
+
+#### open your browser to http://localhost:3000
+
+And that's all you have to do!
+
+## Milia Basic Installation (not needed if you used the generator above)
+
+### Getting started for the Bare minimum setup
+
+This is the mininum necessary for using milia with a Rails application. If you're new to Rails
+(or Devise and Milia), then I'd recommend you skip this section and instead follow the instructions
+(previous section above) for Creating and Installing a Rails/Milia/Devise Sample Application. 
+
+<strong>In any case, do NOT do both installations.</strong>
+
+If you'll be using the recaptcha option, then milia will generate expecting the following
+environment variables (put them in .bashrc, with the correct keys):
+
+```
+export RECAPTCHA_PUBLIC_KEY=6LeYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKpT
+export RECAPTCHA_PRIVATE_KEY=6LeBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBgQBv
+```
+
+### Steps for Bare minimum
+Add to your Gemfile:
+
+```ruby
+  gem 'devise', '~>3.2'
+  gem 'milia', '~>1.0'
+```
+
+If you'll be working with any beta or leading edge version, specify as follows:
+
+```
+   gem 'milia', :git => 'git://github.com/dsaronin/milia.git', :branch => 'v1.0.0-beta-7'
+```
+
+Then,
+```
+  $ bundle install
+  $ rails g milia:install --org_email='<your smtp email for dev work>'
+```
+
+Note: The milia generator has an option to specify an email address to be used for sending emails for 
+confirmation and account activation. Also note that the milia generator runs two
+devise generators.
+
+Make any changes required to the generated migrations, then:
+```
+  $ rake db:create
+  $ rake db:migrate
+```
+
+---------------------------------------------------------------------
+
+## Installation Reference Manual
+
+This information is for reference only. The two generators automatically perform
+these changes when installing the sample application. Do NOT repeat these steps
+if you followed the automatic installation of the sample application.
+
+#### information and expectations
+
+**The above generator did everthing that's required. This section
+will explain why the generator did what it did. You won't need
+to do any of these steps unless you decide to customize or adapt.**
+
+#### User session required
+
+Rails 4 now handles this with a gem:
+
+```
+  gem 'activerecord-session_store', github: 'rails/activerecord-session_store'
+```
+
+#### Generate a session migration
+
+``` 
+  $ rails g active_record:session_migration
+```
+
 ### Devise setup
 
 * See https://github.com/plataformatec/devise for how to set up devise.
 * The current version of milia requires that devise use a *User* model.
 
-### Milia setup
+```
+  $ rails g devise:install
+  $ rails g devise user
+```
 
-#### migrations
+Add the following in <i>config/routes.rb</i> to the existing devise_for :users  :
 
-*ALL* models require a tenanting field, whether they are to be universal or to
-be tenanted. So make sure the following is added to each migration
+```
+  as :user do   #   *MUST* come *BEFORE* devise's definitions (below)
+    match '/user/confirmation' => 'milia/confirmations#update', :via => :put, :as => :update_user_confirmation
+  end
 
-<i>db/migrate</i>
+  devise_for :users, :controllers => { 
+    :registrations => "milia/registrations",
+    :confirmations => "milia/confirmations",
+    :sessions => "milia/sessions", 
+    :passwords => "milia/passwords", 
+  }
 
-```ruby
-  t.references :tenant
 ```
 
-Tenanted models will also require indexes for the tenant field:
+Add the appropriate line below to <i>config/environments/</i>_ 
+files <i>development.rb, production.rb, test.rb</i>_ (respectively below, editing hosts as appropriate for your app).
+Make sure you've also correctly set up the ActionMailer::Base.smtp_settings. If you're unclear as to how to 
+do that, refer to the sample-milia-app.
 
-```ruby
-  add_index :TABLE, :tenant_id
+```
+  config.action_mailer.default_url_options = { :host => 'localhost:3000' }
+  config.action_mailer.default_url_options = { :host => 'secure.simple-milia-app.com', :protocol => 'https' }
+  config.action_mailer.default_url_options = { :host => "www.example.com" }
 ```
 
-Also create a tenants_users join table:
+EDIT: <i>db/migrate/xxxxxxx_devise_create_users.rb</i>
+and uncomment the confirmable section, it will then look as follows:
 
-<i>db/migrate/20111008081639_create_tenants_users.rb</i>
+```
+      ## Confirmable
+      t.string   :confirmation_token
+      t.datetime :confirmed_at
+      t.datetime :confirmation_sent_at
+      t.string   :unconfirmed_email # Only if using reconfirmable
+```
 
-```ruby
-  class CreateTenantsUsers < ActiveRecord::Migration
-    def change
-      create_table :tenants_users, :id => false  do |t|
-        t.references   :tenant
-        t.references   :user
-      end
-      add_index :tenants_users, :tenant_id
-      add_index :tenants_users, :user_id
-    end
-  end
+and uncomment the confirmation_token index line to look as follows
+
+```
+    add_index :users, :confirmation_token,   :unique => true
 ```
 
-#### application controller
+and add above the t.timestamps line:
 
-add the following line AFTER the devise-required filter for authentications:
+```
+      # milia member_invitable
+      t.boolean    :skip_confirm_change_password, :default => false
 
-<i>app/controllers/application_controller.rb</i>
+      t.references :tenant
+```
 
-```ruby
-  before_filter :authenticate_tenant!   # authenticate user and setup tenant
+edit <i>config/initializers/devise.rb</i> 
+and change mailer_sender to be your from: email address
 
-# ------------------------------------------------------------------------------
-# authenticate_tenant! -- authorization & tenant setup
-# -- authenticates user
-# -- sets current tenant
-# -- sets up app environment for this user
-# ------------------------------------------------------------------------------
-  def authenticate_tenant!()
+```
+  config.mailer_sender = "my-email@simple-milia-app.com"
+```
 
-    unless authenticate_user!
-      email = ( params.nil? || params[:user].nil?  ?  ""  : " as: " + params[:user][:email] )
+OPTIONAL (not required for milia): 
+in the same initializer file, locate and uncomment the following lines:
 
-      flash[:notice] = "cannot sign you in#{email}; check email/password and try again"
-      
-      return false  # abort the before_filter chain
-    end
+```
+  config.pepper = '46f2....'
+  config.confirmation_keys = [ :email ]
+  config.email_regexp = /\A[^@]+@[^@]+\z/
+```
+
+### Milia setup
 
-    # user_signed_in? == true also means current_user returns valid user
-    raise SecurityError,"*** invalid sign-in  ***" unless user_signed_in?
+#### migrations
 
-    set_current_tenant   # relies on current_user being non-nil
-    
-    # any application-specific environment set up goes here
-    
-    true  # allows before filter chain to continue
-  end
+*ALL* models require a tenanting field, whether they are to be universal or to
+be tenanted. So make sure the following is added to each migration:
+
+<i>db/migrate/xxxxxxx_create_modelXYZ.rb</i>
 
+```
+  t.references :tenant
 ```
 
+Tenanted models will also require indexes for the tenant field.
 
-catch any exceptions with the following (be sure to also add the designated methods!)
+```
+  add_index :<tablename>, :tenant_id
+```
+
+BUT: Do not add any <i>belongs_to  :tenant</i> statements into any of your
+models. milia will do that for all. I do recommend, however, that you add
+into your <i>app/models/tenant.rb</i> file, one line per tenanted model such
+as the following (replacing <model> with your model's name):
 
-```ruby
-  rescue_from ::Milia::Control::MaxTenantExceeded, :with => :max_tenants
-  rescue_from ::Milia::Control::InvalidTenantAccess, :with => :invalid_tenant
+```
+  has_many  :<model>s, :dependency => destroy
 ```
 
-You'll need to place prep_signup_view method in application_controller.rb; it sets up any attributes required by your signup form. below is the example from my application.
+The reason for this is that if you wish to have a master destroy tenant action,
+it will also remove all related tenanted tables and records.
 
-```ruby
-# ------------------------------------------------------------------------------
-  # klass_option_obj -- returns a (new?) object of a given klass
-  # purpose is to handle the variety of ways to prepare for a view
-  # args:
-  #   klass -- class of object to be returned
-  #   option_obj -- any one of the following
-  #       -- nil -- will return klass.new
-  #       -- object -- will return the object itself
-  #       -- hash   -- will return klass.new( hash ) for parameters
-# ------------------------------------------------------------------------------
-  def klass_option_obj(klass, option_obj)
-    return option_obj if option_obj.instance_of?(klass)
-    option_obj ||= {}  # if nil, makes it empty hash
-    return klass.send( :new, option_obj )
-  end  
+Generate the tenant migration
 
-# ------------------------------------------------------------------------------
-  # prep_signup_view -- prepares for the signup view
-  # args:
-  #   tenant: either existing tenant obj or params for tenant
-  #   user:   either existing user obj or params for user
-# ------------------------------------------------------------------------------
-  def prep_signup_view(tenant=nil, user=nil, coupon='')
-    @user   = klass_option_obj( User, user )
-    @tenant = klass_option_obj( Tenant, tenant )
-    @coupon = coupon
-    @eula   = Eula.get_latest.first
- end
+```
+  $ rails g model tenant tenant:references name:string:index
 ```
 
-My signup form has fields for user's email, organization's name (tenant model), coupon code, and current EULA version.
+Generate the tenants_users join table migration
 
+```
+  $ rails g migration CreateTenantsUsersJoinTable tenants users
+```
 
-#### routes
+EDIT: <i>db/migrate/20131119092046_create_tenants_users_join_table.rb</i>
+then uncomment the first index line as follows:
 
-Add the following line into the devise_for :users block
+```
+   t.index [:tenant_id, :user_id]
+```
+
+#### application controller
+
+<i>app/controllers/application_controller.rb</i>
+add the following line IMMEDIATELY AFTER line 4 protect_from_forgery
 
-<i>config/routes.rb</i>
 
-```ruby
-  devise_for :users, :controllers => { :registrations => "milia/registrations" }
 ```
-  
+  before_action :authenticate_tenant!   # authenticate user and sets up tenant
+
+  rescue_from ::Milia::Control::MaxTenantExceeded, :with => :max_tenants
+  rescue_from ::Milia::Control::InvalidTenantAccess, :with => :invalid_tenant
+
+# milia defines a default max_tenants, invalid_tenant exception handling
+# but you can override if you wish to handle directly
+```
+
 ### Designate which model determines account
 
 Add the following acts_as_... to designate which model will be used as the key
@@ -230,38 +580,24 @@ Only designate one model in this manner.
   end  # class Tenant
 ```
 
-### Designate universal models
+### Clean up any generated belongs_to tenant references in all models
 
-Add the following acts_as_universal to *ALL* models which are to be universal and
-remove any superfluous
-  
-```ruby
-  belongs_to  :tenant
-```
-  
-which the generator might have generated ( acts_as_tenant will specify that ).
+which the generator might have generated 
+( both <i>acts_as_tenant</i> and <i>acts_as_universal</i> will specify these ).
+
+### Designate universal models
 
-<i>app/models/eula.rb</i>
+Add the following acts_as_universal to *ALL* models which are to be universal.
 
 ```ruby
-  class Eula < ActiveRecord::Base
-    
     acts_as_universal
-  
-  end  # class Eula
 ```
 
 ### Designate tenanted models
 
-Add the following acts_as_tenant to *ALL* models which are to be tenanted and
-remove any superfluous
+Add the following acts_as_tenant to *ALL* models which are to be tenanted.
+Example for a ficticous Post model:
   
-```ruby
-  belongs_to  :tenant
-```
-  
-which the generator might have generated ( acts_as_tenant will specify that ).
-
 <i>app/models/post.rb</i>
 
 ```ruby
@@ -272,7 +608,6 @@ which the generator might have generated ( acts_as_tenant will specify that ).
   end  # class Post
 ```
 
-
 ### Exceptions raised
 
 ```ruby
@@ -280,12 +615,29 @@ which the generator might have generated ( acts_as_tenant will specify that ).
   Milia::Control::MaxTenantExceeded
 ```
 
+### post authenticate_tenant! callback [optional]
+
+In some applications, you will want to set up commonly used
+variables used throughout your application, after a user and a 
+tenant have been established. This is optional and if the
+callback is missing, nothing will happen.
+
+<i>app/controllers/application_controller.rb</i>
+
+```ruby
+  def callback_authenticate_tenant
+    # set_environment or whatever else you need for each valid session
+  end
+```
+
+
+
 ### Tenant pre-processing hooks
 
 #### Milia expects a tenant pre-processing & setup hook:
 
 ```ruby
-  Tenant.create_new_tenant(params)   # see sample code below
+  Tenant.create_new_tenant(tenant_params, coupon_params)   # see sample code below
 ```
   
 where the sign-up params are passed, the new tenant must be validated, created,
@@ -297,19 +649,28 @@ immediately after the new tenant has been created).
 <i>app/models/tenant.rb</i>
 
 ```ruby
-  def self.create_new_tenant(params)
-    
-    tenant # Tenant.new(:cname => params[:user][:email], :company => params[:tenant][:company])
+  def self.create_new_tenant(tenant_params, user_params, coupon_params)
+
+    tenant = Tenant.new(:name => tenant_params[:name])
+
+    if new_signups_not_permitted?(coupon_params)
 
-    if new_signups_not_permitted?(params)
-      
       raise ::Milia::Control::MaxTenantExceeded, "Sorry, new accounts not permitted at this time" 
-      
+
     else 
       tenant.save    # create the tenant
     end
     return tenant
   end
+
+  # ------------------------------------------------------------------------
+  # new_signups_not_permitted? -- returns true if no further signups allowed
+  # args: params from user input; might contain a special 'coupon' code
+  #       used to determine whether or not to allow another signup
+  # ------------------------------------------------------------------------
+  def self.new_signups_not_permitted?(params)
+    return false
+  end
 ```
 
 #### Milia expects a tenant post-processing hook:
@@ -337,10 +698,77 @@ work in setting things up for a new tenant.
 #   other  -- any other parameter string from initial request
 # ------------------------------------------------------------------------
   def self.tenant_signup(user, tenant, other = nil)
-    StartupJob.queue_startup( tenant, user, other )
+      #  StartupJob.queue_startup( tenant, user, other )
+      # any special seeding required for a new organizational tenant
+
+      Member.create_org_admin(user)  # sample if using Member as tenanted member information model
   end
 ```
 
+### View for Organizer sign ups
+
+This example shows how to display a signup form together with recaptcha.
+It also shows usage of an optional coupon field
+for whatever reason you might need. If you're not familiar with haml, leading spaces are significant
+and are used to indicate logical blocks. Otherwise, it's kinda like erb without all the syntactical cruff.
+Leading "." indicate div class; "#" indicates a div ID. The example here is
+taken from sample-milia-app.
+
+<i>app/views/devise/registrations/new.html.haml</i>
+
+```ruby
+%h1 Simple Milia App
+.block#block-signup
+  %h2 New Organizational Sign up
+  .content
+    %span.description
+      %i
+        If you're a member of an existing group in our system, 
+        click the activate link in the invitation email from your organization's admin.
+        You should not sign up for a new organizational account.
+        %br
+    .flash
+      - flash.each do |type, message|
+        %div{ :class => "message #{type}" }
+          %p= message
+    - flash.clear  # clear contents so we won't see it again
+
+    = form_for(resource, :as => resource_name, :url => registration_path(resource_name), :html => { :class => "form" }) do |f|
+      .group
+        = f.label :email, :class => "label"
+        = f.text_field :email, :class => "text_field"
+        %span.description Ex. test@example.com
+      .group
+        = f.label :password, :class => "label"
+        = f.password_field :password, :class => "text_field"
+        %span.description must be at least 6 characters
+      .group
+        = f.label :password_confirmation, "Re-enter Password", :class => "label"
+        = f.password_field :password_confirmation, :class => "text_field"
+        %span.description to confirm your password
+
+      .group
+        = fields_for( :tenant ) do |w|
+          = w.label( :name, 'Organization', :class => "label" ) 
+          = w.text_field( :name, :class => "text_field")
+          %span.description unique name for your group or organization for the new account
+
+        - if ::Milia.use_coupon
+          .group
+            = label_tag( 'coupon', 'Coupon code', :class => "label" )
+            = text_field_tag( "coupon[coupon]", @coupon.to_s, :size => 8, :class => "text_field" )
+            %span.description optional promotional code, if any
+
+        - if ::Milia.use_recaptcha
+          = recaptcha_tags( :display => { :theme => 'clean', :tabindex => 0 } )
+
+      .group.navform.wat-cf
+        %button.button{ :type => "submit" }
+          = image_tag "web-app-theme/icons/tick.png"
+          Sign up 
+    = render :partial => "devise/shared/links"
+
+```
 
 ### Alternate use case: user belongs to multiple tenants
 
@@ -377,9 +805,100 @@ for each of the subordinate models in the join.
     Comment.joins(stuff).where( where_restrict_tenants(Post, Author) ).all
 ```
 
+## no tenant authorization required controller actions: root_path
+
+Any controller actions, such as the root_path page, will need to skip the tenant & user authorizations.
+For example in <i>app/controllers/home_controller.rb </i> place the following near the top of the controller:
+
+```ruby
+  skip_before_action :authenticate_tenant!, :only => [ :index ]
+```
+
+## using tokens for authentication
+
+My app has certain actions which require a token for authentication, instead of a user
+sign-in. These use cases include an icalendar feed for a particular user's assignments
+or a generic icalendar feed for all of an organization's events. The tokens are NOT
+a general replacement for user sign-in for all actions, but merely to enable a simple
+restful API for certain specific actions. This section will explain how to incorporate
+token authentication together with milia/devise. Please note that the application
+assigns to each user an authentication token for this use, as well as creates a 
+generic "guest" for the organization itself for accessing the organization-wide action.
+
+The general scheme is to have a prepend_before_action authenticate_by_token! specified 
+only for those actions allowed. This action determines the "user" required to proceed
+with the action, signs in that user via devise, then falls through to the normal
+before_action authenticate_tenant! action which establishes the current_tenant.
+
+Below are some examples of this (typically the token is passed as the id parameter):
+
+<i>app/controllers/application_controller</i>
+```ruby
+# ------------------------------------------------------------------------------
+# NOTE: be sure to use prepend_before_action authenticate_by_token!
+# so that this will occur BEFORE authenticate_tenant!
+# ------------------------------------------------------------------------------
+# Notice we are passing store false, so the user is not
+# actually stored in the session and a token is needed for every request. 
+# ------------------------------------------------------------------------------
+  def authenticate_by_token!
+      # special case for designated actions only
+    if ( controller_name == "feeder" && 
+         ( user = User.find_user_by_user_feed( params ) )
+       )  ||
+       ( controller_name == "questions" && ['signup_form', 'finish_signup'].include?(action_name) && 
+         ( user = User.find_user_by_user_feed( params ) )
+       ) 
+       
+        # create a special session after authorizing a user
+      reset_session
+      sign_in(user, store: false)  # devise's way to signin the user
+      # now continue with tenant authorization & set up
+      true  # ok to continue  processing
+       
+    else
+      act_path = controller_name.to_s + '/' + action_name.to_s
+      logger.info("SECURITY - access denied #{Time.now.to_s(:db)} - auth: #{params[:userfeed] }\tuid:#{(user.nil? ? 'n/f' : user.id.to_s)}\tRequest: " + act_path)
+      render( :nothing => true, :status => :forbidden) #  redirect_back   # go back to where you were
+      nil   # abort further processing
+    end
+
+  end
+
+```
+<i>app/controllers/feeder_controller</i>
+```ruby
+  prepend_before_action  :authenticate_by_token!      # special authtentication by html token
+```
+
+<i>app/models/user.rb</i>
+```ruby
+# ------------------------------------------------------------------------
+# find_user_by_user_feed -- returns a user based on auth code from params
+# ------------------------------------------------------------------------
+  def self.find_user_by_user_feed( params )
+      # can get auth by either :userfeed or :id
+    key = ( params[:userfeed].blank? ? params[:id]  :  params[:userfeed] )
+    return nil if key.blank?  # neither key present; invalid
+    return User.where( :authentication_token => key ).first  # find by the key; nil if invalid
+  end
+  
+    def make_authentication_token
+      self.authentication_token = generate_unique_authentication_token
+    end
+
+  def generate_unique_authentication_token
+    loop do
+      token = AuthKey.make_token   # this can be anything to generate a random large token
+      break token unless User.where(authentication_token: token).first
+    end
+  end
+```
+
+
 ## console
 
-Note that even when running the console ($ rails console) will be run in 
+Note that even when running the console, ($ rails console) it will be run in 
 multi-tenanting mode. You will need to establish a current_user and
 setup the current_tenant, otherwise most Model DB accesses will fail.
 
@@ -396,6 +915,229 @@ load when I start the console. This does the following:
 change_tenant(1,1)   # or whatever is an appropriate starting user, tenant
 ```
 
+## Whitelisting additional parameters for tenant/user/coupon
+
+During the Tenant.create_new_tenant part of the sign-up process, three
+sets of whitelisted parameters are passed to the method: The parameters
+for tenant, user, and coupon. But some applications might require more or
+other parameters than the ones expected by milia. Sometimes the application
+might need to add some parameters of its own, such a EULA version number,
+additions to an activation message, or a unique name for the tenant itself.
+
+Milia has a mechanism to add additional parameters to be whitelisted. 
+In <i>config/initializers/milia.rb</i> you can add a list of symbols for
+the additional parameters to each of a config setting for any of the
+three (tenant, user, or coupon). The example below shows how.
+
+```ruby
+  # whitelist user params list
+  # allows an app to expand the permitted attribute list
+  # specify each attribute as a symbol
+  # example: [:name]
+  config.whitelist_user_params = [:eula_id, :message]
+
+  # whitelist tenant params list
+  # allows an app to expand the permitted attribute list
+  # specify each attribute as a symbol
+  # example: [:name]
+  config.whitelist_tenant_params = [:company, :cname]
+
+  # whitelist coupon params list
+  # allows an app to expand the permitted attribute list
+  # specify each attribute as a symbol
+  # example: [:coupon]
+  config.whitelist_coupon_params = [:vendor]
+
+```
+
+## inviting additional user/members
+
+To keep this discussion simple, we'll give the example of using class Member < Activerecord::Base
+which will be a tenanted table for keeping information regarding all the members in a given
+organization. The name "Member" is not a requirement of milia. But this is how you would set up an
+invite_member capability. It is in this event, that you will require the line in the Tenant
+post-processing hook <i>tenant_signup</i> <pre>Member.create_org_admin(user)</pre> which also
+creates the Member record for the initial admin on the account.
+
+```
+  $ rails g resource member tenant:references user:references first_name:string last_name:string favorite_color:string
+```
+
+ADD to <i>app/models/tenant.rb</i>
+```ruby
+  has_many :members, dependent: :destroy
+```
+
+ADD to <i>app/models/user.rb</i>
+```ruby
+    has_one :member, :dependent => :destroy
+```
+
+
+EDIT <i>app/models/member.rb</i>
+REMOVE belongs_to :tenant
+ADD
+```ruby
+  acts_as_tenant
+
+  DEFAULT_ADMIN = {
+    first_name: "Admin",
+    last_name:  "Please edit me"
+  }
+
+  def self.create_new_member(user, params)
+    # add any other initialization for a new member
+    return user.create_member( params )
+  end
+
+  def self.create_org_admin(user)
+    new_member = create_new_member(user, DEFAULT_ADMIN)
+    unless new_member.errors.empty?
+      raise ArgumentError, new_member.errors.full_messages.uniq.join(", ")
+    end
+
+    return new_member
+      
+  end
+```
+
+CREATE a form for inputting new member information for an invite
+(below is a sample only)
+<i>app/views/members/new.html.haml</i>
+```ruby
+%h1 Simple Milia App
+.block#block-signup
+  %h2 Invite a new member into #{@org_name}
+  .content.login
+    .flash
+      - flash.each do |type, message|
+        %div{ :class => "message #{type}" }
+          %p= message
+    - flash.clear  # clear contents so we won't see it again
+
+    = form_for(@member, :html => { :class => "form login" }) do |f|
+      - unless @member.errors.empty? && @user.errors.empty?
+        #errorExplanation.group
+          %ul
+            = @member.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
+            = @user.errors.full_messages.uniq.inject(''){|str, msg| (str << "<li> #{msg}") }.html_safe
+
+      = fields_for( :user ) do |w|
+        .group
+          = w.label :email, :class => "label "
+          = w.text_field :email, :class => "text_field"
+          %span.description Ex. test@example.com; must be unique
+
+      .group
+        = f.label :first_name, :class => "label "
+        = f.text_field :first_name, :class => "text_field"
+
+      .group
+        = f.label :last_name, :class => "label "
+        = f.text_field :last_name, :class => "text_field"
+
+      .group
+        = f.label :favorite_color, :class => "label "
+        = f.text_field :favorite_color, :class => "text_field"
+        %span.description What is your favorite color?
+
+      .group.navform.wat-cf
+        %button.button{ :type => "submit" }
+          = image_tag "web-app-theme/icons/key.png"
+          Create user and invite
+```
+
+## authorized tenanted user landing page:
+
+You will need a members-only landing page for after someone successfully signs into your app.
+Here is what I typically do:
+
+```ruby
+# REPLACE the empty def index ... end with following ADD:
+# this will give you improved handling for letting user know
+# what is expected. If you want to have a welcome page for
+# signed in users, uncomment the redirect_to line, etc.
+  def index
+    if user_signed_in?
+
+        # was there a previous error msg carry over? make sure it shows in flasher
+      flash[:notice] = flash[:error] unless flash[:error].blank?
+      redirect_to(  welcome_path()  )
+
+    else
+
+      if flash[:notice].blank?
+        flash[:notice] = "sign in if your organization has an account"
+      end
+
+    end   # if logged in .. else first time
+
+  end
+
+  def welcome
+  end
+
+```
+
+## Milia API Reference Manual
+
+### From controller-levels:
+
+```ruby
+  set_current_tenant( tenant_id )
+  #  raise InvalidTenantAccess unless tenant_id is one of the current_user valid tenants
+```
+
+set_current_tenant can be used to change the current_tenanted (for example, if a member
+can belong to multiple tenants and wants to switch between them). See example else in this
+README. NOTE: you will normally NEVER use this. Milia does this automatically during
+authorize_tenant! so you never should at the beginning of a session.
+
+### From model-levels:
+```ruby
+  Tenant.current_tenant -- returns tenant object for the current tenant; nil if none
+
+  Tenant.current_tenant_id -- returns tenant_id for the current tenant; nil if none
+```
+
+If you need to gain access to tenant object itself (say to get the name of the tenant),
+then use these accessor methods.
+
+### From background, rake, or console-level (CAUTION):
+
+From background jobs (only at the start of the task); 
+tenant can either be a tenant object or an integer tenant_id; anything else will raise
+exception.  set_current_tenant -- is model-level ability to set the current tenant
+NOTE: *USE WITH CAUTION* normally this should *NEVER* be done from
+the models ... it is only useful and safe WHEN performed at the start
+of a background job (DelayedJob#perform) or at start of rails console, or a rake task.
+
+```ruby
+  Tenant.set_current_tenant( tenant )
+    raise ArgumentError, "invalid tenant object or id"
+```
+
+
+## running tests
+
+You must cd into the milia/test directory.
+Then run test:units, test:functionals seperately. 
+For some reason, rake test won't work and yields errors.
+
+```ruby
+  $ cd test
+  $ rake db:create
+  $ rake db:migrate
+  $ rake db:test:prepare
+  $ rake test:units
+  $ rake test:functionals
+```
+
+### test coverage
+* All models, including milia-added methods, are tested.
+* Functional testing currently covers all milia-added controller methods.
+* TBD: milia overrides of devise registration, confirmation controllers
+
 ## Cautions
 
 * Milia designates a default_scope for all models (both universal and tenanted). From Rails 3.2 onwards, the last designated default scope overrides any prior scopes and will invalidate multi-tenanting; so *DO NOT USE default_scope*
@@ -403,11 +1145,18 @@ change_tenant(1,1)   # or whatever is an appropriate starting user, tenant
 * SQL statements executed outside the context of ActiveRecord pose a potential danger; the current milia implementation does not extend to the DB connection level and so cannot enforce tenanting at this point.
 * The tenant_id of a universal model will always be forced to nil.
 * The tenant_id of a tenanted model will be set to the current_tenant of the current_user upon creation.
+* HABTM (has_and_belongs_to_many) associations don't have models; they shouldn't have id fields
+  (setup as below) nor any field other than the joined references; they don't have a tenant_id field;
+  rails will invoke the default_scope of the appropriate joined table which does have a tenant_id field.
+
 
 ## Further documentation
+
 * Check out the three-part blog discussion of _Multi-tenanting Ruby on Rails Applications on Heroku_
 at: http://myrailscraft.blogspot.com/2013/05/multi-tenanting-ruby-on-rails.html
 * See the Milia tutorial at: http://myrailscraft.blogspot.com/2013/05/multi-tenanting-ruby-on-rails_3982.html
+* see code & setup sample in test/railsapp, which is also used to run the tests.
+* see milia wiki on github for a CHANGE HISTORY page.
 
 
 ## Contributing to milia
@@ -422,5 +1171,5 @@ at: http://myrailscraft.blogspot.com/2013/05/multi-tenanting-ruby-on-rails.html
 
 ## Copyright
 
-Copyright (c) 2011 Daudi Amani. See LICENSE.txt for further details.
+Copyright (c) 2014 Daudi Amani. See LICENSE.txt for further details.