<img src=“http://i50.tinypic.com/wag4d4.png”> <img src=“https://secure.travis-ci.org/zamith/citygate.png” /> <img src=“https://codeclimate.com/github/zamith/citygate.png” /> <img src=“http://rails-brakeman.com/zamith/citygate.png” />¶ ↑

Citygate is a rails engine that provides your application with user authentication (on the site or through OAuth) using Devise and authorization using CanCan.

It also provides a customizable backend for administrating all your users, using turbolinks making your website as fast and responsive as you ever wanted it to be.

Citygate aims to provide this functionalities in a hassle free way, thus it requires very little to no configuration in order to have everything up and running. It achieves this at the cost of not being super flexible and configurable, for that you can use gems as sorcery or clearance, or even hack into devise or cancan yourself.

Instalation¶ ↑

First add the gem to your Gemfile to get the latest stable version

gem "citygate"

or go on the edge with

gem "citygate", :git => "https://zamith@github.com/zamith/citygate.git"

Database Configuration¶ ↑

In order to get the database ready to run citygate you will need to fetch the migrations

rake citygate:install:migrations

and run them

rake db:migrate

then drop this line at your db/seeds.rb file in order to be able to populate the db with the needed records

Citygate::Engine.load_seed

and finally run the seeds command to actually populate the db

rake db:seed

Routes Configuration¶ ↑

To get all the citygate routes working you just need to mount them by adding the following line to your config/routes.rb file

mount Citygate::Engine => "/"

Environment Configuration¶ ↑

Since citygate will send confirmation emails to any user that signs up, you will need to have your email configured.

In case of development add this to config/environments/development.rb

config.action_mailer.default_url_options = { :host => 'localhost:3000' }

Helper Configuration¶ ↑

In order to get the helper methods citygate exposes you’ll have to include them in your app/controllers/application_controller.rb like so:

class ApplicationController < ActionController::Base
  helper Citygate::Engine.helpers
end

The exposed methods are:

role_changer

a select for changing roles (only available when logged in and in development)

citygate_nav_links

the default nav for citygate with sign in, log out and admin links

OmniAuth Configuration¶ ↑

Citygate needs your facebook apps identifiers which are loaded from a file you must create called config/accounts.yml and has the following format:

facebook:
  app_id: "your app id from https://developers.facebook.com/apps"
  app_secret: "your app secret from https://developers.facebook.com/apps"

This file is not required for the application to run, but without it the facebook login will not work.

In case you are wondering, the reason it is not required for you to add your google OAuth identifier is because it is the same for everyone. It then redirects you to a authentication service within google servers.

Loading Assets¶ ↑

In order to have the javascript added by Citygate you need to include it in your manifest file, like so:

//= require citygate

Citygate Options¶ ↑

You can change citygate’s defaults by editing your config/application.rb file like so

Citygate::Engine.configure do
  config.option = value
end

Options¶ ↑

The available options are:

will_paginate_options

an hash with any option supported by paginate

mount_path

if you mount the engine in any other path than “/”, must define it here as well so that omniauth can be aware of it

no_of_users

limit the number of users allowed in your system

Authorization¶ ↑

Citygate load CanCan and uses it internally, but since it cannot know which roles and permissions you need it leaves it up to you to define an Ability class following the CanCan format.

Citygate checks for authorization on most of its views, you can generate a default ability class by running:

rails generate ability

You might want to add the files in lib to the load path:

config.autoload_paths += ["#{Rails.root}/lib"]

Running Citygate¶ ↑

Users in citygate will not be able to login with their google account if you use WEBrick, due to its url length limitation. Therefore run your server in development with rails s thin, to run the thin server.

---

Note: Do not forget to check the routes made available to you by Citygate with rake routes and to take a look at the doc at RubyDoc