Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Tutorial (walkthrough)

hackhowtofaq edited this page · 1 revision
Clone this wiki locally


Use this project as a starting point for a Rails 3 application that uses subdomains and authentication. User management and authentication is implemented using Devise.

Help and More Information

To keep up to date with development of this app, follow me on Twitter:

Any issues? Please create an Issue on GitHub.


This tutorial documents each step that you must follow to create this application. Every step is documented concisely, so a complete beginner can create this application without any additional knowledge. However, no explanation is offered for any of the steps, so if you are a beginner, you’re advised to look for an introduction to Rails elsewhere. Refer to the Rails Guides site for help if you are a beginner.

For an introduction to Rails 3 and subdomains, see Ryan Bates’s screencast Subdomains in Rails 3 (a transcription is available from ASCIIcasts).

Use Cases

What Is Implemented

This example implements “blog-style subdomains in Rails.” The example is similar to the application shown in Ryan Bates’s screencast Subdomains in Rails 3 but adds authentication using Devise. In this example, there is a “main” domain where anyone can visit and create a user account. And registered users can create any number of subdomains which could host blogs or other types of sites.

What Is Not Implemented

Another use of subdomains is often called “Basecamp-style subdomains in Rails.” Visitors to the main site can create a user account which is then hosted at a subdomain that matches their user name. Each user has only one subdomain and when they log in, all their activity is confined to their subdomain. A user’s home page and account info is accessed only through the subdomain that matches their user name.

For an implementation of “Basecamp-style subdomains in Rails,” see:

Steve Alex’s Basecamp-style fork.

Sachin Sagar Rai (millisami) has revised Steve Alex’s Basecamp-style fork to use Mongodb with Mongoid:

Millisami’s Basecamp-style fork with Mongoid.

(Got your own? Contact me and I will add it here.)

No testing (RSpec or otherwise) is implemented. This app only serves to demonstrate Devise working with subdomains on Rails 3.


Before beginning this tutorial, you need to install

  • The Ruby language (version 1.8.7 or 1.9.2)
  • Rails (version 3.0.4)
  • A working installation of SQLite (preferred), MySQL, or PostgreSQL

I recommend installing rvm, the Ruby Version Manager, to manage multiple versions of Rails.

If you are using rvm, you can see a list of the Ruby versions currently installed:
$ rvm list

Check that appropriate versions of Ruby and Rails are installed in your development environment:
$ ruby -v
$ rails -v

Generating the Application

To create the application, you can follow each step in this tutorial and cut and paste the code into your own files. However, it may be easier to generate a new Rails app using the example as a template:

$ rails new app_name -m

You MUST be using Rails 3.0.4. Generating a Rails application from an “HTTPS” URL does not work in Rails 3.0.3 and earlier versions.

This creates a new Rails app (with the app_name you provide) on your computer. It includes everything in the example app. You can read through the tutorial with the code already on your computer.

If you wish to “change the recipe” to generate the app with your own customized options, you can copy and edit the file rails3-mongoid-devise-template.rb found at the project fortuity/rails3-application-templates.

Create the Rails Application

If you wish work through this tutorial using copy-and-paste, start by creating a new Rails app.

Open a terminal, navigate to a folder where you have rights to create files, and type:

$ rails new rails3-subdomain-devise

You may give the app a different name. For this tutorial, we’ll assume the name is “rails3-subdomain-devise.”

This application will use a SQLite database for data storage. You may also use MySQL or PostgreSQL for data storage (refer to Getting Started with Rails).

After you create the application, switch to its folder to continue work directly in that application:

$ cd rails3-subdomain-devise

Edit the README file to remove the standard Rails boilerplate. Add what you like (perhaps the name of your app?).

Set Up Source Control (Git)

If you’re creating an app for deployment into production, you’ll want to set up a source control repository at this point. If you are building a throw-away app for your own education, you may skip this step.

Check that git is installed on your computer:

$ git version

Rails 3 has already created a .gitignore file for you. You may want to modify it to add .DS_Store if you are using Mac OS X.


Initialize git and check in your first commit:

$ git init
$ git add .
$ git commit -m 'initial commit'

At this point you can check your local project into a remote source control repository. We’ll assume you are using git with an account at GitHub.

Check that your GitHub account is set up properly:

$ ssh git(at)

Go to GitHub and create a new empty repository ( into which you can push your local git repo.

Add GitHub as a remote repository for your project and push your local project to the remote repository:

$ git remote add origin git(at)
$ git push origin master

You can check your commit status at any time with:

$ git status

At each stage of completion, you should check your code into your local repository:

$ git commit -am "some helpful comment"

and then push it to the remote repository:

$ git push origin master

Set Up Gems

Required Gems

The application uses the following gems.

The SQLite3 gem is used for the database. You can substitute a different database if you wish.

The FriendlyId gem is used to give users and subdomains easily recognizable strings instead of numeric ids in URLs.

I recommend checking for newer versions of these gems before proceeding:

The app has been tested with the indicated versions. If you are able to build the app with a newer gem, please create an issue on GitHub and I will update the app.

Set up Your Gemfile

Edit the Gemfile file to look like this:

source ''

gem 'rails', '3.0.4'
gem 'sqlite3-ruby', :require => 'sqlite3'
gem 'devise', '1.2.rc'
gem 'friendly_id', '3.2.1'

Optional Gems

If you wish to deploy to Heroku, you will need to include the following gem:

# uncomment the next line if you wish to deploy to Heroku
# gem 'heroku', :group => :development

Install the Gems

Install the required gems on your computer:

$ bundle install

If you need to troubleshoot, you can check which gems are installed on your computer with:

$ gem list --local

Test the App

You can check that your app runs properly by entering the command

$ rails server

Or you can use the shortcut:

$ rails s

To see your application in action, open a browser window and navigate to http://localhost:3000/. You should see the Rails default information page.

Stop the server with Control-C.

Configuration for FriendlyId

The FriendlyId gem allows us to use easily recognizable strings instead of numeric ids in URLs. To install a database migration for FriendlyId, run:

$ rails generate friendly_id

Prevent Logging of Passwords

We don’t want passwords written to our log file.

In Rails 3, we modify the file config/application.rb to include:

config.filter_parameters += [:password, :password_confirmation]

Note that filter_parameters is an array.

Create a Home Page

Remove the Default Home Page

Delete the default home page from your application:

$ rm public/index.html

You may also want to modify the file public/robots.txt to prevent indexing by search engines if you plan to have a development version on a publicly accessible server:

# To ban all spiders from the entire site uncomment the next two lines:
User-Agent: *
Disallow: /

Create a Home Controller and View

Create the first page of the application. Use the Rails generate command to create a “home” controller and a “views/home/index” page.

$ rails generate controller home index

If you’re using the default template engine, you’ll find the file:


Now, you have to set a route to your home page. Edit the file config/routes.rb and replace:

get "home/index"


root :to => "home#index"

Set Up Authentication

Set Up Configuration for Devise

This app uses Devise for user management and authentication. Devise is at

We’ve already installed the Devise gem with the $ bundle install command. Run the generator:

$ rails generate devise:install

which installs a localization file and a configuration file:


Now is a good time to change the value config.mailer_sender in the configuration file.

In its default configuration, Devise needs to send email to register a new user or reset a password. We’ll need to set up action_mailer.

Set up action_mailer in your development environment in the file


by changing:

# Don't care if the mailer can't send
# config.action_mailer.raise_delivery_errors = false

and adding:

### ActionMailer Config
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
# A dummy setup for development - no deliveries, but logged
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = false
config.action_mailer.raise_delivery_errors = true
config.action_mailer.default :charset => "utf-8"

Set up action_mailer in your production environment in the file


by adding:

config.action_mailer.default_url_options = { :host => '' }
### ActionMailer Config
# Setup for production - deliveries, no errors raised
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default :charset => "utf-8"

Generate a Model and Routes for Users

Devise can manage users and administrators separately, allowing two (or more) roles to be implemented differently. For this example, we just implement Users.

Use Devise to generate a model, database migration, and routes for a User:

$ rails generate devise User

Devise will modify the config/routes.rb file to add:

devise_for :users

which provides a complete set of routes for user signup and login. If you run rake routes you can see the routes that this line of code creates.

Customize the Application

Enable Users to Have Names

By default, Devise uses an email address to identify users. We’ll add a “name” attribute as well.

Modify the migration file in db/migrate/ to add:

t.string :name

to add a “name” field to the data table.

Next, we’ll modify the User model to allow a “name” to be included when adding or updating a record.

We’ll also modify the User model so the URL for accessing a user uses a name instead of a number (the FriendlyId gem provides this feature).

You’ll also want to prevent malicious hackers from creating fake web forms that would allow changing of passwords through the mass-assignment operations of update_attributes(attrs) and new(attrs). With the default Rails ActiveRecord, Devise adds

attr_accessible :email, :password, :password_confirmation, :remember_me

We’ll need to add the :name attribute to attr_accessible.

Modify the file models/user.rb to include this:

validates_presence_of :name
validates_uniqueness_of :name, :email, :case_sensitive => false
attr_accessible :name, :email, :password, :password_confirmation, :remember_me
has_friendly_id :name, :use_slug => true, :strip_non_ascii => true

This will allow users to be created (or edited) with a name attribute. When a user is created, a name and email must be present and must be unique (not used before). Note that Devise (by default) will check that the email address and password are not blank.

Create Model and Migration for Subdomains

Each user will be able to register and use a subdomain. We’ll create a Subdomain model that belongs to a User. In this implementation, the Subdomain model just stores a string that is the name of the subdomain. Later, we’ll create another model, the Site, that subclasses Subdomain and is used to create the page that is hosted at a URL using the name of the subdomain.

Generate a model and migration for Subdomains. Since a Subdomain will belong to a user, the “user:references” parameter adds a field “user_id” to the data table to handle the relationship with a User:

$ rails generate model Subdomain name:string user:references

Modify the Subdomain model so the URL for accessing a subdomain uses a name instead of a number (the friendly_id gem provides this feature):

class Subdomain < ActiveRecord::Base
  belongs_to :user
  has_friendly_id :name, :use_slug => true, :strip_non_ascii => true
  validates_uniqueness_of :name, :case_sensitive => false
  validates_presence_of :name

When a subdomain is created, it must have a name and the name must be unique.

Enable Users to Own Subdomains

A registered user will access his or her profile on the main site to add or delete subdomains.

Subdomains belong to users, so we have to set up the User side of the relationship. Modify the file models/user.rb to look like this:

class User < ActiveRecord::Base
  has_many :subdomains, :dependent => :destroy
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :trackable, :validatable
  validates_presence_of :name
  validates_uniqueness_of :name, :email, :case_sensitive => false
  attr_accessible :name, :email, :password, :password_confirmation, :remember_me
  has_friendly_id :name, :use_slug => true, :strip_non_ascii => true

Create a Site Model

We’ll create a Site model as a subclass of the Subdomain model so any visitor can view a subdomain-hosted site. The Site is a simple stub in this application. It can be customized for additional functionality (for example, implementation as a blog).

The Site model is very simple so there’s no need to use a generator. Just create a file app/models/site.rb:

$ touch app/models/site.rb


class Site < Subdomain

Set Up the Database

Create a Database and Run Migrations

Now create an empty database. You can do this by running a rake command:

$ rake db:create

Run the migrations:

$ rake db:migrate

You can take a look at the database schema that’s been created for you:


Seed the Database With Users and Subdomains

Edit the file db/seeds.rb and add the following code:

user1 = User.create! :name => 'First User', :email => '', :password => 'please', :password_confirmation => 'please'
puts 'New user created: ' <<
user2 = User.create! :name => 'Other User', :email => '', :password => 'please', :password_confirmation => 'please'
puts 'New user created: ' <<
subdomain1 = Subdomain.create! :name => 'foo'
puts 'Created subdomain: ' <<
subdomain2 = Subdomain.create! :name => 'bar'
puts 'Created subdomain: ' <<
user1.subdomains << subdomain1
user2.subdomains << subdomain2

Run the rake task to seed the database:

$ rake db:seed

Set Up the Main Domain

Create Customized Views for User Registration

Devise provides a controller and views for registering users. It is called the “registerable” module. The controller and views are hidden in the Devise gem so we don’t need to create anything. However, because we want our users to provide a name when registering, we will create custom views for creating and editing a user. Our custom views will override the Devise gem defaults.

First, to copy all the default Devise views to your application, run

rails generate devise:views

This will generate a set of views in the directory app/views/devise/.

Next, modify the views to create and edit users.

Add the following code to each file:


  <p><%= f.label :name %><br />
  <%= f.text_field :name %></p>


  <p><%= f.label :name %><br />
  <%= f.text_field :name %></p>

We do not need to add a controller with methods to create a new user or edit or delete a user. We use the existing “registerable” module from Devise which provides a controller with methods to create, edit or delete a user.

Note that Devise’s default behaviour allows any logged-in user to edit or delete his or her own record (but no one else’s). When you access the edit page you are editing just your info, and not info of other users.

Create a Controller and Views to Display Users

The site’s home page has no subdomain. We want to add a list of users to the home page. And we want links to pages that shows details about each user. Later we’ll add a list to the details page that shows which subdomains they own.

Create a controller to display users:

$ rails generate controller Users index show

You’ll need to modify the Users controller:


class UsersController < ApplicationController
  def index
    @users = User.all

  def show
    @user = User.find(params[:id])


Next, modify the views to display users. Add the following code to each file:


<% @users.each do |user| %>
    <td><%= link_to, user %></td>
<% end %>


<h1><%= %></h1>
<p><%= %></p>
<br />
<p><%= link_to 'Edit', edit_user_registration_path %></p>
<p><%= link_to 'List of Users', users_path %></p>

Implement Routing for the Main Domain

Add a route in the file config/routes.rb to display the users. Your file should look like this:

 devise_for :users
 resources :users, :only => [:index, :show]
 root :to => "home#index"

Note that devise_for :users must be placed above resources :users, :only => [:index, :show] or else you will get errors.

Add a Link to the Main Domain Home Page

We want a link to a list of users on the application home page.

Modify the file:


with these changes:

<p><%= link_to "View List of Users", users_path %></p>

Add Devise Navigation Links

You will want to add navigation links to the application layout for the Devise sign-up and log-in actions. You’ll find a simple example on the Devise wiki.

First, create a folder app/views/devise/menu.

Create the file app/views/devise/menu/_login_items.html.erb and add:

<% if user_signed_in? %>
  <%= link_to('Logout', destroy_user_session_path, :method => :delete) %>        
<% else %>
  <%= link_to('Login', new_user_session_path)  %>  
<% end %>

Create the file app/views/devise/menu/_registration_items.html.erb and add:

<% if user_signed_in? %>
  <%= link_to('Edit account', edit_user_registration_path) %>
<% else %>
  <%= link_to('Sign up', new_user_registration_path)  %>
<% end %>

Create a Stylesheet

Create a public/stylesheets/application.css file and add some menu styling to the css (here for a horizontal menu for navigation links):

ul.hmenu {
  list-style: none;	
  margin: 0 0 2em;
  padding: 0;

ul.hmenu li {
  display: inline;  

Set up the Application Layout

Add the navigation links to your layouts/application.html.erb file.

And include flash messages to show application alerts and notices.

Your file should look like this:

<!DOCTYPE html>
  <%= stylesheet_link_tag :all %>
  <%= javascript_include_tag :defaults %>
  <%= csrf_meta_tag %>
  <ul class="hmenu">
    <%= render 'devise/menu/registration_items' %>
    <%= render 'devise/menu/login_items' %>
  <p style="color: green"><%= notice %></p>
  <p style="color: red"><%= alert %></p>
  <%= yield %>

Test the Application

You can check that your app runs properly by entering the command:

$ rails server

If you launch the application and visit
you can click a link to register as a new user. The app is configured to require a new user to confirm registration by clicking a link in an email message. The app’s development environment is set up to log email messages instead of attempting to send them. Check your console or log file for a log entry that contains the text of the email message with the URL you can use to confirm the new user.

It will look something like this:

Visit the confimation URL in your web browser to complete registration of a new user.

Set Up Subdomains

Create a Controller and Views to Manage Subdomains

Each registered user will be able to create any number of subdomains which will be hosts for the user’s “sites.” This app does not provide any functionality for a user’s “sites,” but you can add functionality so each user can have a blog or other features for their “site.”

Create a controller to manage subdomains:

$ rails generate scaffold_controller Subdomains

with the following code in the file:


class SubdomainsController < ApplicationController
  before_filter :authenticate_user!, :except => [:index, :show]
  before_filter :find_user, :except => [:index, :show]
  respond_to :html

  def index
    @subdomains = Subdomain.all

  def show
    @subdomain = Subdomain.find(params[:id])

  def new
  @subdomain = => @user)

  def create
    @subdomain =[:subdomain])
      flash[:notice] = "Successfully created subdomain."
    redirect_to @user

  def edit
    @subdomain = Subdomain.find(params[:id])

  def update
    @subdomain = Subdomain.find(params[:id])
    if @subdomain.update_attributes(params[:subdomain])
      flash[:notice] = "Successfully updated subdomain."

  def destroy
    @subdomain = Subdomain.find(params[:id])
    flash[:notice] = "Successfully destroyed subdomain."
    redirect_to @user


    def find_user
      if params[:user_id]
        @user = User.find(params[:user_id])
        @subdomain = Subdomain.find(params[:id])
        @user = @subdomain.user
      unless current_user == @user
        redirect_to @user, :alert => "Are you logged in properly? You are not allowed to create or change someone else's subdomain."


Create views to manage subdomains, with the following code in each file:


<% if @subdomain.errors.any? %>
  <div id="error_explanation">
    <h2><%= pluralize(@subdomain.errors.count, "error") %> prohibited this subdomain from being saved:</h2>
    <% @subdomain.errors.full_messages.each do |msg| %>
      <li><%= msg %></li>
    <% end %>
<% end %>
<%= fields_for @subdomain do |f| %> 
  <%= f.label :name %>
  <%= f.text_field :name %>
  <%= f.hidden_field(:user_id, :value => @subdomain.user_id) %>
  <br />
  <div class="actions">
    <%= f.submit %>
<% end %>


<h1>Editing subdomain</h1>
<%= form_for(@subdomain) do |f| %>
  <%= render 'form' %>
<% end %><%= link_to 'Show', @subdomain %> |
<%= link_to, user_path(@subdomain.user) %>


<% @subdomains.each do |subdomain| %>
    <td><%= link_to, subdomain %></td>
    <td>(belongs to <%= link_to, user_url(subdomain.user) %>)</td>
    <td><%= link_to 'Edit', edit_subdomain_path(subdomain) %></td>
    <td><%= link_to 'Destroy', subdomain, :confirm => 'Are you sure?', :method => :delete %></td>
<% end %>


<h1>New subdomain</h1>
<%= form_for([@user, @subdomain]) do |f| %>
  <%= render 'form' %>
<% end %>
<%= link_to, user_path(@subdomain.user) %>


<h1><%= %></h1>
<p>Belongs to: <%= link_to, user_url(@subdomain.user) %></p>
<%= link_to 'Edit', edit_subdomain_path(@subdomain) %>

Modify the User’s Detail Page to List Subdomains

Show a list of subdomains on the user’s detail page. Edit the file app/views/users/show.html.erb to look like this:

<h1><%= %></h1>
<p>Email: <%= %></p>
<%= link_to 'Edit', edit_user_registration_path %> |
<%= link_to 'List of Users', users_path %>
<h3><%= %>'s Subdomains</h3>
<% @user.subdomains.each do |subdomain| %>
    <td><%= link_to, subdomain %></td>
    <td><%= link_to 'Edit', edit_subdomain_path(subdomain) %></td>
    <td><%= link_to 'Destroy', subdomain, :confirm => 'Are you sure?', :method => :delete %></td>
<% end %>
<br />
<%= link_to "Add New Subdomain", new_user_subdomain_path(@user) %>

Implement Routing for Subdomains

Add a route for subdomains in the file config/routes.rb:

 devise_for :users
 resources :users, :only => [:index, :show] do
   resources :subdomains, :shallow => true
 root :to => "home#index"

We use “shallow routes” to simplify the URLs. Routes are built only with the minimal amount of information that is needed to uniquely identify the resource. So instead of:

user_subdomain_url(subdomain.user,subdomain) #=> '/users/firstuser/subdomain/foo'

we can use:

subdomain_url(subdomain) #=> '/subdomains/foo'

Create a Controller and Views to Display Subdomain Sites

In this step, we will create a simple stub that displays a “site” page as the home page of any registered subdomain.

Create a controller to display sites:

$ rails generate controller Sites show

You’ll need to modify the Sites controller:


class SitesController < ApplicationController
  def show
    @site = Site.find_by_name!(request.subdomain)


Add the following code to the file:


<h1>Site: <%= %></h1>
<p>Belongs to: <%= link_to, user_url(@site.user) %></p>

Implement Routing for Sites

At this point you can use the Rails 3 built-in routing support for subdomains.

Edit the file config/routes.rb to look like this:

devise_for :users
resources :users, :only => [:index, :show] do
  resources :subdomains, :shallow => true
match '/' => 'sites#show', :constraints => { :subdomain => /.+/ }
root :to => "home#index"

Test the Application With Subdomains

If you launch the application, it will be running at http://localhost:3000/ or However, unless you’ve made some configuration changes to your computer, you won’t be able to resolve an address that uses a subdomain, such as http://foo.localhost:3000/. There are several complex solutions to this problem. You could set up your own domain name server on your localhost and create an A entry to catch all subdomains. You could modify your /etc/hosts file (but it won’t accommodate dynamically created subdomains). You can create a proxy auto-config file and set it up as the proxy in your web browser preferences. There’s a far simpler solution that does not require reconfiguring your computer or web browser preferences. The developer Levi Cook registered a domain, (short for: local virtual host me), that resolves to the localhost IP address and supports wildcards (accommodating dynamically created subdomains). See Tim Pope’s blog post for a NSFW alternative.

To test the application, visit You can also try or

Add Navigation Between Sites

Applications that do not use subdomains use routing helpers to generate links that either include the site’s hostname (for example, users_url generates or links that only contain a relative path (for example, users_path generates /users).

To provide navigation between sites hosted on the subdomains and the main site, you must use URL helpers (“users_url”) not path helpers (“users_path”) because path helpers do not include a hostname. You’ll also need to find a way to include a subdomain as part of the hostname when generating links. You can specify a hostname when creating a link, with the syntax:

root_url(nil, {:host => ""})

but this will require you to hardcode the name of the host into every link. Ideally, we should be able to pass a :subdomain option to the url helper, like this:

root_url(:subdomain =>

In his screencast Subdomains in Rails 3, Ryan Bates makes some useful suggestions for improved handling of URLs that contain subdomains. He shows how to write a helper that constructs a URL with an optional subdomain parameter.

In a June 19, 2010 blog post on Custom Subdomains in Rails 3, Brian Cardarella makes similar suggestions (you may want to compare his implementation with Ryan Bates’s).

Overwriting the URL Helper

Ryan Bates suggests the following. Create a app/helpers/url_helper.rb file with the following code:

module UrlHelper
  def with_subdomain(subdomain)
    subdomain = (subdomain || "")
    subdomain += "." unless subdomain.empty?
    [subdomain, request.domain, request.port_string].join

  def url_for(options = nil)
    if options.kind_of?(Hash) && options.has_key?(:subdomain)
      options[:host] = with_subdomain(options.delete(:subdomain))

and modify the file app/controllers/application_controller.rb to look like this:

class ApplicationController < ActionController::Base
  include UrlHelper

Use Subdomain-Specific Links

To provide navigation between sites hosted on the subdomains and the main site, you’ll need to use the custom URL helpers we created above.

To add links from a subdomain-hosted site to the main site, modify the code in the file:


<h1>Site: <%= %></h1>
<p>Belongs to: <%= link_to, user_url(@site.user, :subdomain => false) %></p>
<p><%= link_to 'Home', root_url(:subdomain => false) %></p>

You can also modify the users’ details pages to include links to their sites.

Edit the file app/views/users/show.html.erb to look like this:

<h1><%= %></h1>
<p>Email: <%= %></p>
<%= link_to 'Edit', edit_user_registration_path %> |
<%= link_to 'List of Users', users_path %>
<h3><%= %>'s Subdomains</h3>
<% @user.subdomains.each do |subdomain| %>
    <td><%= link_to, subdomain %></td>
    <td><%= link_to 'Edit', edit_subdomain_path(subdomain) %></td>
    <td><%= link_to 'Destroy', subdomain, :confirm => 'Are you sure?', :method => :delete %></td>
    <td><%= link_to "Visit #{root_url(:subdomain =>}", root_url(:subdomain => %></td>
<% end %>
<br />
<%= link_to "Add New Subdomain", new_user_subdomain_path(@user) %>

Prevent Use of the Main Site With Subdomain URLs

Though there are no links to main site pages such as user profiles on the subdomain-hosted sites, it’s possible for a clever visitor to enter a URL such as We want to segregate the functionality of the main site and make sure it is only accessible when there is no subdomain attached to the hostname. There are several ways to accomplish this. One approach is to set a before_filter in the application controller.

Modify the file app/controllers/application_controller.rb to look like this:

class ApplicationController < ActionController::Base
  include UrlHelper
  before_filter :limit_subdomain_access


    def limit_subdomain_access
        if request.subdomain.present?
          # this error handling could be more sophisticated!
          # please make a suggestion :-)
          redirect_to root_url(:subdomain => false)


To allow access to the subdomain-hosted sites, override the before_filter by adding the following code in the only controller that should allow access via subdomains:


The top few lines will look like this:

class SitesController < ApplicationController
  skip_before_filter :limit_subdomain_access

  def show
    @site = Site.find_by_name!(request.subdomain)


Using Subdomains in Emails

Devise sends registration confirmations, forgotten password messages, and other email messages. These will originate from the main domain. You can modify the application so these emails originate from subdomains.

Add the following code to the file app/helpers/url_helper.rb:

def set_mailer_url_options
  ActionMailer::Base.default_url_options[:host] = with_subdomain(request.subdomain)

and modify the file app/controllers/application_controller.rb to add:

before_filter :set_mailer_url_options

(Thanks to Tom Howlett for this contribution.)

Ignore a “www” Subdomain

At this point, if we visit our application will look for a site with the subdomain “www” which doesn’t exist. Instead this should redirect to the main home page.

In his screencast Subdomains in Rails 3, Ryan Bates shows how to create a routing constraint that will redirect a “www” URL to the main home page. His solution requires writing an auxiliary class but there’s a simpler solution.

Here’s how to create a routing constraint that will redirect a “www” URL to the main home page.

Edit the file config/routes.rb to look like this:

devise_for :users
resources :users, :only => [:index, :show] do
  resources :subdomains, :shallow => true
match '/' => 'home#index', :constraints => { :subdomain => 'www' }
match '/' => 'sites#show', :constraints => { :subdomain => /.+/ }
root :to => "home#index"

This will intercept the “www” subdomain first, then the limit_subdomain_access method in the ApplicationController will redirect to root, effectively getting rid of the “www”. Note that you will need to add your own code to prevent users from creating a subdomain called “www”.

Maintaining Sessions Across Subdomains

The application has a significant limitation as implemented so far. A user can log in to the main site but will not be logged in when they visit a subdomain-hosted site. That’s because session data for each visitor is managed by browser-based cookies and cookies are not shared across domains (and, by default, not shared across subdomains). Not only is the user login not maintained between the main site and subdomains, but flash messages (used to communicate between actions) are lost because they are stored in sessions.

Examine the Issue

You can see this limitation by displaying the current_user on each page.

Modify the file app/views/devise/menu/_login_items.html.erb to look like this:

<% if user_signed_in? %>
  <%= link_to('Logout', destroy_user_session_path) %>        
<% else %>
  <%= link_to('Login', new_user_session_path)  %>  
<% end %>
  <% if current_user %>
    <%= %>
  <% else %>
    (not logged in)
  <% end %>

When you first visit the main site, a cookie is set to maintain the session. When you log in, the current_user value is set and will be displayed on each page. If you visit a subdomain-hosted page, a new session is created, a new cookie is set (corresponding to the subdomain hostname), and no current_user value is present.

Test the app by logging in to the main site and then visiting a subdomain-hosted site. You’ll see the user login is lost when visiting the subdomain-hosted site.

If you examine the browser’s cookies, you will see that a separate session is stored for each different subdomain you’ve visited.

Troubleshooting Cookies

If you’re using Firefox as your web browser, you can use the Firecookie extension for Firebug to examine and remove cookies.

If you remove cookies for the site, you can visit any pages that don’t require session data. But as soon as you try to login (after submitting the login form), you will see an error:

ActionController::InvalidAuthenticityToken in Devise/sessionsController#create

The error arises because the authenticity token used by the “protect_from_forgery” feature (in the application controller) is stored in session data which requires a cookie.

Allow Cookies To Be Shared Across Subdomains

To maintain sessions between the main site and subdomain-hosted sites, modify the configuration file to add the parameter :domain => :all:


Rails3SubdomainDevise::Application.config.session_store :cookie_store, :key => '_rails3-subdomain-devise_session', :domain => :all

Alternatively, we can use the domain name of the deployed application (with a prepended dot), such as :domain => "". However, by using the parameter :domain => :all we don’t have to hardcode the domain name in the app and we can test the app on our localhost machine.

Deploying to Heroku

Set Up Heroku

For your convenience, here are instructions for deploying your app to Heroku. Heroku provides low cost, easily configured Rails application hosting.

To deploy this app to Heroku, you must have a Heroku account. If you need to obtain one, visit to set up an account.

Make sure the Heroku gem is in your Gemfile. If it’s not, add it and run

$ bundle install

to set up your gems again.

If you’ve just created a Heroku account, add your public key immediately after installing the heroku gem so that you can use git to push or clone Heroku app repositories. See for details.

Create Your Application on Heroku

Use the Heroku create command to create and name your new app> Specify the “bamboo-ree-1.8.7” stack so Heroku will allow you to use Rails 3.

$ heroku create _myapp_ --stack bamboo-ree-1.8.7

Heroku Add-ons and DNS Configuration

You will need the following Heroku add-ons to deploy your app using subdomains with your own custom domain:

  • Custom Domains (free)
  • Custom Domains + Wildcard ($5 per month)
  • Zerigo DNS Tier 1 ($7 per month)

To enable the add-ons, you can use the Heroku web interface or you can enter the following commands:

$ heroku addons:add custom_domains

$ heroku domains:add

$ heroku addons:add wildcard_domains

$ heroku domains:add *

$ heroku addons:add zerigo_dns:tier1

If you are using the Zerigo DNS service, you will need to set the nameserver with your domain registrar. It can take a few minutes (or longer) for DNS changes to propagate. When DNS is set properly, you should be able to visit or in your web browser and see the Heroku default page:

Heroku | Welcome to your new app!

You can check that everything has been added correctly by running:

$ heroku info --app myapp

Set Up Your Application on Heroku

Push your application to Heroku:

$ git push heroku master

Set up your Heroku database:

$ heroku rake db:migrate

Initialize your application database:

$ heroku rake db:seed

Visit Your Site

If you use the heroku command to open your default web browser to your site with

$ heroku open

or if you visit your site with you’ll see the error, “The page you were looking for doesn’t exist.” That’s because your app is trying to find a subdomain “myapp” that doesn’t exist. You’ll need to visit the site using your own domain name, such as Domain name service must be set properly to use the Zerigo nameservers.


If you get errors, you can troubleshoot by reviewing the log files:

$ heroku logs


This concludes the tutorial for creating a Rails 3 web application that uses subdomains and provides user management and authentication using Devise.


Daniel Kehoe ( implemented the application and wrote the tutorial.

Was this useful to you? Follow me on Twitter:
and tweet some praise. I’d love to know you were helped out by the tutorial.


Thank you to contributor Fred Schoeneman for improving the tutorial.
Thank you to contributor Charlie Ussery for suggesting how to ignore the “www” subdomain.
Thank you to contributor Tom Howlett for suggesting how to use subdomains in Devise emails.
Thank you to contributor Tom Mornini for improvements to forms.

Something went wrong with that request. Please try again.