Heroku Review Apps: Custom Domains

Gilbert Fu
Apr 16, 2019 · 3 min read

At Clutter, we have several engineering teams rapidly developing new features every week. Before releasing to production, the new code is uploaded to a staging machine so that product managers can provide QA and give final approval.

A pain point in this process has been the lack of availability of staging machines for our growing team. When our engineering team was smaller, we could sufficiently share a pool of configured staging machines; however, this did not scale well with the growth of our engineering department. Setting up a staging machine is a complicated and an unpleasant exercise that requires a lot of environment configuration and third-party services integrations. To ease our troubles, we decided to use Heroku Review Apps to automate this process.

Image for post
Image for post

Heroku does a great job at explaining how to set up Review Apps but the documentation lacks details on supporting custom domains, integrating third-party APIs and enabling cross-origin requests. This article details how we managed to achieve that at Clutter.

What are Review Apps

Review Apps are application instances that can be automatically spun up on every pull request opened on GitHub. Heroku takes the code from a GitHub pull request and deploys it into a brand new app with its own unique URL. One of the main challenges in using the Review Apps is having custom domains for routing within our Rails Application.

Image for post
Image for post
Heroku Dashboard with a Review Apps enabled in the pipeline

By default, Review App are hosted on a machine that is reachable by an autogenerated domain likeyour_app_name.herokuapp.com. Heroku allows the use of custom domains, and they can be set up manually in the settings panel of each app.

Image for post
Image for post

A limitation to Heroku’s custom domain feature is that it does not update the DNS registry, so you must register a CNAME record for the new app with your DNS provider. To automate this process, we make use of postdeploy and pr-predestroy scripts that can be specified in the app.json file needed for Review Apps.

The app.json file

An app.json must exist in your project directory to enable Review Apps. This configuration file specifies how each app should be built. At Clutter, our app.json file looks like this:

Sample app.json file with scripts specified

The app.json file gives us the ability to specify a postdeploy script to run after the release of the app has succeeded, and a pr-predestroy script that will deregister the domain when the Review App is destroyed.

The postdeploy script

In our postdeploy script, we utilize the open source Ruby gems dnssimple-ruby and platform-api to make the API calls for the domain and subdomain configurations.

The platform-api gem is provided by Heroku to interact with its platform via code, rather than manually. We use it to tell Heroku that Review Apps should not only be available at clutter-pr-NN.herokuapp.com, but also available at a custom domain pr-NN.clutter.com.

The dnssimple-rubygem is provided by DNSimple to set up CNAME records via code, rather than manually. We use it to tell DNSimple to create a CNAME for the new custom domain pr-NN.clutter.com.

The resulting script looks like:

An example postdeploy script that will be executed through our app.json configuration

The pr pre-destroy script

Our pr-predestory script handles the cleanup of the CNAME record in our DNSimple account so that it is not polluted with old records.

A sample pr pre-destroy script that cleans up our CNAME records

Heroku Review Apps are a powerful tool to help our engineering and product teams here at Clutter continuously deliver new features. With the postdeploy script capability, we can continue to add more functionality to Review Apps such as third party integrations with other services.

If you enjoyed this article, please share with your friends. If you are looking to join an amazing team of Ruby developers, check our current openings at Clutter.

Clutter Developers

Working at Clutter.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store