---
layout: page
title: Using with Rails
---

<div id="toc">
# "Installing Vanity":#install
# "Configuring Vanity":#config
# "Test Environment":#test
# "Unicorn and Forking Servers":#fork
</div>

h3(#install).  Installing Vanity

<em>Rails 3.x and 4.x:</em>

Add Vanity to your Gemfile:

<pre>
gem "vanity"
</pre>

h3(#config).  Configuring Vanity

h4. Configuring identity

Once the gem is setup, enable Vanity in your ActionController:

<pre>
class ApplicationController < ActionController::Base
  use_vanity :current_user
end
</pre>

This example assumes you have a @current_user@ controller method which will return a consistent value for each user.
There are other ways to identify people as well, you can read more about the options in Managing Identity.

h4. Configuring datastore

If you have a @config/vanity.yml@ file, Vanity will read the configuration for the current environment.  For example:

<pre>
staging:
  adapter: redis
  host: staging.internal
production:
  adapter: mongo
  host: live.internal
  database: vanity
</pre>

h4. Using metrics from Google Analytics

If you want to use Vanity with metrics from Google Analytics, you must also tell Rails to include the @garb@ gem, and login for a new session.  You'll want to do that for production, not for development if you like developing offline:

<pre>
config.after_initialize do
  require "garb"
  Garb::Session.login('..ga email..', '..ga pwd..', account_type: "GOOGLE")
end
</pre>

h4. Enabling/disable collection

When collection is off, Vanity doesn't connect to the database server, so there's no need to set a database configuration for these environments.

h4. Overriding default views

If you would like to customize Vanity's dashboard, you can create create copies of the default views in @app/views/vanity@ by running a generator:

<pre>
rails g vanity:views
</pre>

You can then edit them to your heart's content. If you need to use an alternative location for your custom templates, set the configuration variable @custom_templates_path@ on @Vanity.playground@ like this:

<pre>
Vanity.playground.custom_templates_path = 'views/vanity'
</pre>

h3(#fork).  Unicorn and Forking Servers

Unicorn forks the master process to create worker processes efficiently.  Since the master processes opens a connection to the database, all workers end up sharing that connection, resulting in ugly contention issues.

The cure is simple, use the @after_fork@ hook to reconnect each worker process.  Here's the relevant part from my @config/unicorn.rb@:

<pre>
after_fork do |server, worker|
  ActiveRecord::Base.establish_connection
  Vanity.playground.establish_connection
end
</pre>

You'll run into this issue with other forking servers.  Vanity can detect when it runs under Passenger and automatically reconnect each forked process.