Heroku Review Apps: Custom Domains
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.
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.
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.
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:
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:
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.
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.
