Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

local-subdomain: Subdomain support for localhost


This gem helps out when your application depends on subdomain support and you don't want to modify you /etc/hosts file all the time for your development environment.


  1. Add the gem to your Gemfile
gem 'local-subdomain'
  1. Run bundle install
  2. Include the LocalSubdomain module into your application_controller.rb (or the controllers that requires subdomain support)
class ApplicationController < ActionController::Base
  include LocalSubdomain

NOTE: Do not force the gem only to be included in the development group. Because of the inclusion of the module LocalSubdomain, you'll need to have the gem available in every environment. The gem itself contains guards to only perform changes when the environment is development, so no worries or check it out yourself:

Configuration (optional)

By default the gem uses the domain with the port used, when running the rails server, but it is also possible to provide a custom redirect domain and port using the following ENV variables:

SERVER_REDIRECT_PORT The port number to redirect to 5000
SERVER_REDIRECT_DOMAIN The domain to redirect to my.domain.tld

What it does

Basically it does two things:

  1. Extends the Rack::Handler to make sure we bind to instead of localhost
  2. Adds the LocalSubdomain module which executes a before_action to redirect to<port> (or the configured redirect domain and port)


By default, this gem uses the domain to handle our requests for our subdomain(s). Request to the domain redirects all requests to This give's us the ability to browse to and be handle request.subdomain from our controllers.

Because we're going to use the external domain which redirects to we have to make our server not to bind to localhost only.

LocalSubdomain module

This module includes a before_action which will check if the request is served by If not it will redirect to the domain.

So when we browse to http://localhost:3000 it will redirect you to

Supported ruby servers

I've tested the gem with: