README.md in cadenero-0.0.2.b6 vs README.md in cadenero-0.0.2.b7
- old
+ new
@@ -5,49 +5,76 @@
[](https://travis-ci.org/AgilTec/cadenero)
[](https://codeclimate.com/github/AgilTec/cadenero)
[](https://coveralls.io/r/AgilTec/cadenero?branch=master)
[](https://gemnasium.com/AgilTec/cadenero)
+THIS README IS FOR THE MASTER BRANCH OF **CADENERO** AND REFLECTS THE WORK CURRENTLY EXISTING ON THE MASTER BRANCH. IF YOU ARE WISHING TO USE A NON-MASTER BRANCH OF **CADENERO**, PLEASE CONSULT THAT BRANCH'S README AND NOT THIS ONE.
+
Authentication Engine for Rails.API multitenant RESTful APIs based on Warden. It:
* Is Racked based
* Use token authentication as strategy for the API
* Is RESTful API
* Allows you to have multiple roles (or models/scopes) signed in at the same time
## Information
### Why Cadenero?
**"Cadenero"** is the spanish word for ["Bouncer (doorman)"](http://en.wikipedia.org/wiki/Bouncer_(doorman\)). The main function of **Cadenero** is to be a resource for authenticating consumers of the services that the API provides. As the real bouncers, **Cadenero** aims to provide security, check authorized access, to refuse entry for intoxication, aggressive behavior or non-compliance with statutory or establishment rules.
+
You can use [Warden](https://github.com/hassox/warden) or [Devise](https://github.com/plataformatec/devise) directly but for API apps the rewritting and monkey patching can be messy.
### Installing **Cadenero**
+#### Preconditions
+
+##### Postgresql
+You should have a Postgresql server (for downloading see: http://www.postgresql.org/download/). If you are using OSX, you can install using [Homebrew](http://mxcl.github.io/homebrew/) for that you can follow the following this [instructions](http://www.moncefbelyamani.com/how-to-install-postgresql-on-a-mac-with-homebrew-and-lunchy/)
+
+##### Ruby 1.9.x or 2.x
+For that we recommend that you use [rbenv](https://github.com/sstephenson/rbenv) with [ruby-build](https://github.com/sstephenson/ruby-build) or [rvm](https://rvm.io/)
+
+We use the standard `rake`, `bundler` and `gem`
+
+##### Git/Github
+You are here. Then you know what to do ;-)
+
+#### Setup
+
Rails 3.2.13 is the master version used now by **Cadenero**, if you want to use Rails 4 goodness please use the branch "rails4"
Generate first your Rails app as usual using:
```
- $ rails _3.2.13_ new your_app --skip-test-unit
+ $ rails _3.2.13_ new your_app --skip-test-unit -d postgresql
```
In the `Gemfile` add the following lines:
```ruby
- gem 'cadenero', '~> 0.0.2.b6'
- gem 'pg'
+ gem 'cadenero', '~> 0.0.2.b7'
+
+ group :development, :test do
+ gem 'rspec-rails', '~> 2.14.0'
+ gem 'capybara', '~> 2.1.0'
+ gem 'rack-test', '~> 0.6.2'
+ end
```
In the `config/database.yml` replace the `sqlite3` adapter for `postgresql` as follow:
```
development:
adapter: postgresql
+ encoding: unicode
database: your_app_development
+ pool: 5
min_messages: warning
test:
adapter: postgresql
- database: your_app_test
+ encoding: unicode
+ database: your_app_test
+ pool: 5
min_messages: warning
```
Then run bundle, create the databases and run the generator:
@@ -112,10 +139,19 @@
You can check them running:
```
$ rake routes
```
+### Strategies
+For authentication **Cadenero** has two default Warden Strategies:
+ * **Password**. That expect that the client to keep a session cookie and using for authentication the user `email` and `password`.
+ * **Token Authentication**. That is stateless and expects that for each request the user include the `auth_token` as a key-value of the request params.
+
+In any case when you signed up **Cadenero** creates an auth_token for the membership to the account that you signed up.
+
+If you want to know more about Warden Strategies see: https://github.com/hassox/warden/wiki/Strategies
+
### Documentation
You can review the YARD docs in: http://rubydoc.info/github/AgilTec/cadenero/frames
### The Cadenero Task List
- [x] Specs for the code 100% Coverage using BDD with [Rspec](https://github.com/rspec/rspec) and [Capybara](https://github.com/jnicklas/capybara)
@@ -133,18 +169,24 @@
If you found a security bug, do *NOT* use the GitHub issue tracker. Send an email to the maintainers listed at the bottom of the README please.
### Contributing
-We hope that you will consider contributing to **Cadenero**. Please read this short overview for some information about how to get started:
+We hope that you will consider contributing to **Cadenero**. You're encouraged to submit pull requests, propose features and discuss issues.
-https://github.com/AgilTec/cadenero/Contributing
+ * Fork the project
+ * Write test for your new feature or a test that reproduces a bug
+ * Implement your feature or make a bug fix
+ * Commit, push and make a pull request. Bonus points for topic branches.
-You will usually want to write tests for your changes using BDD tools as RSpec, Rack::Test and Capybara. To run the test suite, go into **Cadenero**'s top-level directory and run "bundle install" and "rspec". For the tests to pass, you will need to have a Postgresql server running on your system.
+You will usually want to write tests for your changes using BDD tools as RSpec, Rack::Test and Capybara.
+To run the test suite, go into **Cadenero**'s top-level directory and run `bundle install` and `rspec spec`. For the tests to pass, you will need to have a Postgresql server running on your system.
+
#### Running the Specs
-**Cadenero** use [RSpec](https://github.com/rspec/rspec) and [Capybara](https://github.com/jnicklas/capybara). If you want to extend **Cadenero** please fork and clone the repo. To run the specs you only need to do:
+**Cadenero** use [RSpec](https://github.com/rspec/rspec) and [Capybara](https://github.com/jnicklas/capybara). To run the specs you only need to do:
+
```
$ RAILS_ENV=test bundle exec rake db:create
$ RAILS_ENV=test bundle exec rake db:migrate
$ bundle exec rspec spec
```
@@ -155,10 +197,13 @@
$ bundle binstubs rake
```
### Warden
-**Cadenero** is based on Warden, which is a general Rack authentication framework created by Daniel Neighman. We encourage you to read more about Warden here: https://github.com/hassox/warden
+**Cadenero** is based on [Warden](https://github.com/hassox/warden), which is a general Rack authentication framework created by Daniel Neighman. We encourage you to read more about Warden here: https://github.com/hassox/warden/wiki
+
+#### Devise
+Some code and architectural decisions in **Cadenero** have been inspired for the excellent gem [Devise](https://github.com/plataformatec/devise).
### Rails::API
**Cadenero** is a Rails::API Engine, Rails::API is a subset of a normal Rails application, created for applications that don't require all functionality that a complete Rails application provides. It is a bit more lightweight, and consequently a bit faster than a normal Rails application. The main example for its usage is in API applications only, where you usually don't need the entire Rails middleware stack nor template generation. Rails::API was created by Santiago Pastorino. We encourage you to read more about Rails::API here: https://github.com/rails-api/rails-api
\ No newline at end of file