How to Host Sites on a Subdomain with Heroku

A few weeks ago, Jesse asked me about my process for putting content on gabebw.com subdomains. For example, http://steal-my-gurl.gabebw.com is linked to http://steal-my-gurl.herokuapp.com/. I have a lot of projects on subdomains of gabebw.com, so I have some experience in this area. In this guide, I’ll assume you’ve used Heroku but know almost nothing about DNS.

Set up Heroku

Before the content can show up on your site, it needs to be on Heroku. I’m not going to go into how to deploy a site to Heroku, but for this guide you can use any language: Ruby, Python, PHP, whatever. I like using Sinatra for one-off sites like Steal my Gurl that serve one HTML file and one CSS file. Steal my Gurl has a short app.rb that serves index.html at the root route and serves static CSS via the public_folder setting.

Once you have a site that’s serving your HTML/CSS/images/etc, deploy it to Heroku. Let’s say you deploy it to my-cool-site.herokuapp.com.

Set up your DNS provider

To put content on a subdomain, you need to own a domain name (I use Gandi). You also need a way to manage your domain’s DNS. This is an important decision! Every domain registrar has a built-in DNS management interface, but most of them are frankly terrible. I use DNSimple to manage all of my domains’ DNS settings. It costs extra money, but is absolutely, one-hundred-percent worth it. DNSimple is so, so great and I love everything about using it.

I use a separate domain registrar and DNS management service because I read somewhere that it’s more secure. If you don’t care, use DNSimple to register domains. It’ll make everything easier. If you use separate services like I do, or you already have domains registered elsewhere, DNSimple has a short guide on how to use them as another registrar’s DNS.

OK I’m going to assume that you have DNSimple set up, and your domain name is tutorial.com.

Connecting your domain to your Heroku app

There are two steps here: pointing your subdomain at Heroku, and telling Heroku to allow you to link to it.

To point your subdomain at Heroku, add a CNAME record in DNSimple.

A CNAME is like a symlink in Unix. It says that the canonical name (C NAME) of domain A is actually this other domain B, so when someone visits domain B, show the content of domain A. It’s exactly what we want.

The “Name” field is your subdomain, and the “Alias for” is the domain to point it at. Here’s what it looks like if you want cool.tutorial.com to be linked to my-cool-site.herokuapp.com:

For security reasons, Heroku won’t let anyone set up a CNAME to your domain. You have to explicitly allow it by running this command:

$ heroku domains:add cool.tutorial.com --app my-cool-site

It will take up to an hour for everything to start working, though in my experience DNSimple takes much less time than that.

And that’s it! You now have a subdomain on your site pointing to your project on Heroku.