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
index.html at the root route and serves static CSS via the
Once you have a site that’s serving your HTML/CSS/images/etc, deploy it to
Heroku. Let’s say you deploy it to
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
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
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.