Cream

h1. Cream

h2. August 9, 2011 - Announcement!

During the past few months, @kristianmandrup and @stanislaw have been working hard to come up with a replacement for cream, redesigning the core components from the ground up, with a full spec suite, dummy apps for integration testing etc.

The fruits are now ready to be harvested! Today we announce the Release Candidate of "CanTango":https://github.com/kristianmandrup/cantango

The gem (with Rails 3 engine) will be released later today when we have the wiki and README in place ;)

Also join the "CanTango discussion group":http://groups.google.com/group/cantango

We hope you will enjoy it and join in the effort to create a super ACM system for Rails 3 :)

Cheers!

PS: This also means that cream will no longer be maintained. All efforts are now on CanTango. Please migrate from cream to CanTango. A migration guide will be available on the wiki soon.

h2. Intro

This project aims to assist in setting up a Rails 3 app with an integrated Authentication and Authorization solution for your ORM of choice.

Execute the full_config generator with arguments specifying:

• The User types in the application (for Authentication, route Authorization and User data)
• The User roles in the app (for fine-grained Authorization)
• The main Role strategy to use (allow single or multiple roles for each user)
• ORM to use (Relational and Document based datastores are supported - see below)

The cream generator will apply all its "magic" to your app so you can implement your permission business logic using intuitive APIs.

Cream targets smooth integration of the following main systems:

• "Devise":http://github.com/plataformatec/devise - Users and Authentication
• "CanCan":http://github.com/ryanb/cancan - Authorization of users
• "Roles":http://github.com/kristianmandrup/roles_generic - Roles and role groups for authorization

Cream comes with a suite of specialized generators that aim to facilitate configuration of your Rails 3 app with these systems. For details on how to use these generators, please see the documentation for the individual gem.

h2. Status update (June 22, 2011)

During most of May and June (2011), the cream gem has been broken due to an update of the gem 'sugar-high', which the generators depend on for file operations via the 'file_mutate' pack. The latest release of sugar-high, version '0.4.6.4' should now ensure that the file_mutate pack is backwards compatible so that this should no longer cause an error.

I am currently working on a new framework 'dancing tango with troles' taking what I've learned so far and providing a far better solution which incorporates use of multiple user accounts for a given user and thus that a user can be logged into multiple applications simultaneously in different roles!

Please help out on this project if you find it useful! Thanks!

h2. Status update (June 12, 2011)

Please check out the rails_3_1 branch. I've just added support for the File.mutat_ext :all macro available from the gem "sugar-high":http://github.com/kristianmandrup/sugar-high

Cream might currently have a few gotchas to get it working (not tested since mid May). For the roles part you can substitute roles_generic with the new gem "troles":http://github.com/kristianmandrup/troles, which has a much cleaner design and also supports role groups. Cream will be redesigned and rebranded as Dancing over the summer, and will support Rails 3.1. Stay tuned. You are as always most welcome to assist in the project :)

h2. Installation and configuration

The cream gem has been designed for Rails 3 and Ruby 1.9 only.

h3. Installing Cream

Insert <pre>gem 'cream'</pre> in your Rails 3 Gemfile

<pre>$ bundle install</pre>

h2. ORMs supported

Relational Databases:

• Active Record
• Data Mapper

Document stores:

• Mongo Mapper
• Mongoid
• Couch DB

Note: Couch DB support will soon be migrated to use "CouchRest":https://github.com/mattetti/couchrest

h2. More info

For more information:

• "Cream Wiki":https://github.com/kristianmandrup/cream/wiki
• "Cream user group":http://groups.google.com/group/rails-cream

Please let me know of other areas that you think should be covered in the Wiki or on page. One or more tutorials with demo applications are planned for the near future.

h2. How to start with Cream

Cream integrates so many moving parts that running the full generator to generate all the bells and whistles and start playing around might be overwhelming for most. I therefore recommend that you start out by experimenting with the main parts and get a feel for how to design the users/roles/permits parts of your application.

1. Devise user with Roles
2. Cancan permits
3. User types

First I would generate a single Devise user and then run Roles for the ORM you are using. Then play around with the Roles API to get a feel for it. Later You can run the cancan-permits generator and play around with permissions, using permits and licenses to get a feel for this API and how it plays with the roles.

Then think about which user types you need. User types are distinct types of users that might have individual data needs (separate table or schema), individual registration pages or different administration rules (devise strategies such as email confirmation etc.)

Then decide which roles should be available for each user type, that is what kind of user_type each role makes sense for. You might also decide to group multiple roles into role groups.

h3. Scenario example

Roles: super admin, forum admin, guest user, normal user, content publisher

In this scenario it would make sense to have these User types: User, Guest, Admin

The user types should make roles available as follows:

• Guest: guest
• User: normal, content_publisher
• Admin: super_admin, forum_admin

This is done via the method valid_roles_are (see the Roles API).

h2. Rails 3 demo apps with Cream

The following Rails 3 demo apps use Cream 0.7.7 and above and were created around Dec 1. 2010

• "Cream app with Active Record":https://github.com/kristianmandrup/cream-app-active_record
• "Cream app with Mongoid":https://github.com/kristianmandrup/cream-app-mongoid
• "Cream app with Mongo Mapper":https://github.com/kristianmandrup/cream-app-mongo_mapper

You are most welcome to publish your own demo app with a later version of Cream. These apps need to be updated and demonstrate the real functionality of using the various APIs and DSLs that come with Cream and its supporting libs ;)

I plan to release new demo apps for the 0.9 version of Cream in May, 2011

h2. Sub systems of Cream

• Devise
• Cancan
• Roles
• Permits

h3. Authentication

Cream targets "Devise":http://github.com/plataformatec/devise as the Authentication system of choice

See "Devise Configuration options":https://github.com/kristianmandrup/cream/wiki/Devise-Configuration-options for more details on configuring your devise User models.

The project "devise links":http://github.com/kristianmandrup/devise-links adds more convenience for creating view links to trigger Devise session actions.

h3. Authorization

Cream supports "CanCan":http://github.com/ryanb/cancan as the Authorization system. The project "Cancan permits":http://github.com/kristianmandrup/cancan-permits adds the concept of Permits for each role.

h3. Roles

The Roles system is based on "Roles Generic":http://github.com/kristianmandrup/roles_generic, a generic Roles API implementation where parts are overriden by Roles implementations for specific ORMs.

The Roles Generic API has been implemented for the following ORMs

• "Roles Active Record":http://github.com/kristianmandrup/roles_active_record
• "Roles DataMapper":http://github.com/kristianmandrup/roles_data_mapper
• "Roles MongoMapper":http://github.com/kristianmandrup/roles_mongo_mapper
• "Roles Mongoid":http://github.com/kristianmandrup/roles_for_mongoid
• "Roles Simply Stored":https://github.com/kristianmandrup/roles_simply_stored

Any role system can be substituted as long as you have a method #has_role? on the user which returns true or false given a string or symbol that identifies the role.

You can also use "Role groups":https://github.com/kristianmandrup/cream/wiki/Role-groups to group multiple roles into a group and query if a user has any of the roles in the group.

h3. Permits

A Permit lets a user in a given role do certain actions as defined in the Permit. A Permit can also reuse permission logic in the form of Licenses for a more fine grained design if needed.

CanCan Permits comes with generators to generate Permit files which are placed in '/app/permits'. You can then edit the Permits to suit your needs.

The project "CanCan REST links":http://github.com/kristianmandrup/cancan-rest-links provides a convenient way to handle CanCan REST links, using a flexible API.

Check out "Cancan permits":http://github.com/kristianmandrup/cancan-permits for more info for how to use Permits.

Cancan permits support all the ORMs that both Devise and Roles support.

h4. Licenses

For more advanced authorization scenarios you can create reusable permission logic in license classed that are placed in '/app/licenses/'. A License can be reused in multiple Permits.

See "CanCan permits demo app":https://github.com/kristianmandrup/cancan-permits-demo for an example of how to use cancan-permits and licenses.

h4. Permits Editor

I have recently created a "Permits editor":http://github.com/kristianmandrup/permits_editor application that demonstrates how you can let the user edit the Permits, Licenses and even individual User permissions directly as part of an admin section of the web app.

The Permits editor updates yaml files that are now part of the cancan-permits infrastructure (if present and registered). I plan to refactor the Permits Editor into a "mountable app":http://piotrsarnacki.com/2010/12/21/mountable-apps-tutorial/ when I have the time.

h2. Generators

Please see "Cre