Skip to content
By Sebastian Porto

Developing and testing Rails applications with subdomains

Subdomains can be a tricky thing to work with. Here are some tips to develop and test Rails applications using them.


During development there are a few ways you can handle subdomains. If you are using the bundled webrick server, you won't be able to access your subdomain at all.


If you are using the webrick server or something like Puma for development you can use to access your subdomains. e.g.

'' resolves to localhost, so this provides access to the subdomain in Rails on port 9292 (the Puma default). This is convenient but can be very slow to work with.

Editing your hosts file

To avoid having to do a round trip to the internet you can add a record to your machine hosts file. In Unix/mac you can find it on /etc/hosts

You can add something like: sub.virtual.local

Then you should be able to access your subdomain using the built in web server or puma by going to: (again 9292 is the port used by puma):


Using Pow (Only available for Mac)

Pow makes it extremely easy to work with subdomains: - Install pow - Link your application - Access the application using a subdomain e.g.

Have a look at the powder gem, it makes installing pow even easier.


Capybara needs to hit a real webserver in order to test your application. So you will have the same challenge as when accessing it on development.


The easiest way is to use `' for this (as long as your CI server can resolve it).

Add a couple of methods accessible by your tests, e.g. in spec/support/subdomains.rb:

def switch_to_subdomain(subdomain)
    # always resolves to
    Capybara.app_host = "http://#{subdomain}"

def switch_to_main_domain
    # Capybara.app_host = ""

Then in your feature test you can do:


Testing on your local machine

The above approach should work on your local machine as well, but it still wasteful as it is doing a round trip to I found it useful to do the following:

First add an entry to your hosts file as described above: sub.virtual.local

Add an environment variable (e.g. LOCALVIRTUALHOST) only available on development (e.g. using the dotenv-rails gem)

In .env:

LOCAL_VIRTUAL_HOST  = virtual.local

Then change spec/support/subdomains.rb to look like:

def local_virtual_host

def switch_to_subdomain(subdomain)
    # always resolves to
    Capybara.app_host = "http://#{subdomain}.#{local_virtual_host}"

def switch_to_main_domain
    Capybara.app_host = "http://#{local_virtual_host}"

This should make testing on your machine a lot faster. The only caveat with this approach is that something like *.virtual.local in your hosts file won't work, you have to list the subdomains one by one. But this is not a huge problem because you can usually limit the tests to a few specific known subdomains.

Popular Articles by Our Team

Our expert team of designers and developers love what the do and enjoy sharing their knowledge with the world.

We Hire Only the Best

reinteractive is Australia’s largest dedicated Ruby on Rails development company. We don’t cut corners and we know what we are doing.

We are an organisation made up of amazing individuals and we take pride in our team. We are 100% remote work enabling us to choose the best talent no matter which part of the country they live in. reinteractive is dedicated to making it a great place for any developer to work.

Free Community Workshops

We created the Ruby on Rails InstallFest and Ruby on Rails Development Hub to help introduce new people to software development and to help existing developers hone their skills. These workshops provide invaluable mentorship to train developers, addressing key skills shortages in the industry. Software development is a great career choice for all ages and these events help you get started and skilled up.

  • Webinars


    Webinars are our online portal for tips, tricks and lessons learned in everything we do. Make the most of this free resource to help you become a better developer.

    Learn more about webinars

  • Installfest


    The Ruby on Rails Installfest includes a full setup of your development environment and step-by-step instructions on how to build your first app hosted on Heroku. Over 1,800 attendees to date and counting.

    Learn more about Installfest

  • Development Hub

    Development Hub

    The Ruby on Rails Development Hub is a monthly event where you will get the chance to spend time with our team and others in the community to improve and hone your Ruby on Rails skills.

    Learn more about Development Hub

Get the “reinteractive Review” Monthly Email