Lightningspirit's Blog

How to redirect a Heroku subdomain

This article is about how to redirect all requests from to a different address such as or

The procedure will also apply to different scenarios where a permanent redirect is needed to maintain the consistency with previous URLs.

We reached to this problem when we were planning to migrate some apps out of Heroku to our own Kubernetes instance.

They also had a custom domain configured and we needed to redirect all upcoming requests to a new one pointing to the instance inside our Kubernetes cluster.

For that purpose, I created a small app written in Node.js that would respond to every request with a HTTP/1.1 301 Moved Permanently with the exact location, keeping the path structure.

We monitored for some months the Heroku instance and watched a gradual decrease of requests for the first days until it reached the absolute zero in the last 30 days. After that period of time, we switched it off and finally completed the migration.

How to use?

It’s all done in four simple steps.

The source code lives under this Github repository and you can use it for your own purpose as well.

Looking at the codebase you’ll see that it’s a simple Node.js app that creates an HTTP server and handles a raw HTTP response, using the native http.createServer method.

This also includes a Procfile which will be enabled as soon as it reaches the Heroku instance.


1. Clone the repository

First, clone the repository and configure the Heroku git remote to push:

$ git clone
$ git remote add heroku

2. Run the tests

Make sure you’ll run the automated tests before using this for real.

$ npm test

If anything went wrong in this part, you should not proceed but file an issue in the repository.

3. Configure the address to redirect

Now, you need to tell the script where to redirect all new requests by adding a new environmental variable to the container:

$ heroku config:set NEW_BASE_URL= -a my-app
Setting NEW_BASE_URL and restarting ⬢ my-app... done, vX

All set! Now we just need to deploy it.

4. Zero-downtime deployment

The Heroku deployment strategy tries to reduce to the very minimum the downtime when uploading a new version. The existing containers are only removed when the new one is ready and all existing requests are fulfilled.

You even have a pre-boot option for apps that need to warm-up their first content, which for this case, you can ignore it.

Before you do this step, make sure the new instance is properly working and can handle the traffic shift that comes from Heroku.

So, let’s deploy it:

$ git push heroku master

Wait for the build process to finish, and test it:

$ curl -v
< HTTP/1.1 301 Moved Permanently
< Location:

Finished! For now on, all requests will be redirect to the new instance. :D

Featured image by Gratisography

Keywords: heroku, redirect, node.js, http, migration, zero-downtime deployment

Vitor De Carvalho

Written by Vitor De Carvalho, Software Developer, Hacker, Musician, Astrophysics lover, who lives in sunny Lisbon, Portugal.
Follow me on Twitter Github Soundcloud