Opbeat is joining forces with Elastic – Learn more about Elastic APM

Pushing a button to deploy to Heroku

Last week, we introduced webhooks on Opbeat. These hooks allow users to choose where to get notifications sent to. Along with this feature, we got to try out Heroku’s new “Deploy to Heroku”-button.

The barrier to entry

Both of the webhook apps (we got some help from our friends at Iconfinder for the Hipchat-integration) are very small and simple. They are basically ready to go, and just need to be deployed.

However, they are not necessarily easy to deploy for inexperienced users. Open the terminal, clone the repo, create a Heroku application, add the environment variables and deploy the application to Heroku. This is easy to do with the right experience, but for the less experienced, these steps can be confusing and potentially error-prone.

We wondered if it was possible to eliminate some of these steps and make the setup time even shorter. This is the result:

Screenshot of README

From the README from opbeat/slack-hook

When the you click the button, you are taken to the deployment flow which ends with these satisfying steps:

Gif of deployment

It is an easy and fast way to get a small project like this running, and here is how we did it.

The magical button

In early August, Heroku introduced the Heroku Button. It is their latest effort in making it even easier to deploy and run apps.

The button is just a Markdown (or HTML) snippet that can be added to the README of a GitHub repository, or any related website.

When a user clicks the button, they are taken to the app setup and deployment flow in the Heroku dashboard. The project owner can customize this with a project name, logo and even preset environment variables.

It is extremely simple for the end user to click a button and complete all the necessary steps in one go, without having to touch the command line at all. It was perfect for our needs.

Setting up a button for your project

If you have a similar app you would like to make it easy to deploy, this is how you do it:

First you need to create an app.json file in the root of the repository. It is a manifest that tells Heroku how to handle and deploy your project.

Generate it

The easiest way to create the manifest is with a tool made by the nice folks at ExpeditedSSL: Heroku Deploy Button generator. Simply fill in the fields and download the generated manifest.

Screenshot of button maker

Or write it yourself

You can also do it manually. The app.json file is pretty straightforward, and contains just a few basic pieces of information about the project, such as name, description and environment variables, with most of it being optional.

Our app.json file looks like this:

    "name": "Opbeat to Slack hook",
    "description": "Get Opbeat notifications in Slack chatrooms",
    "logo": "https://secure.gravatar.com/avatar/a6ec5537afa27bdb4fe5056e2d34810d",
    "repository": "https://github.com/opbeat/slack-hook",
    "keywords": ["opbeat", "slack", "error logging", "release tracking"],
    "success_url": "/setup",
    "env": {
        "SLACK_URL": null

Read the app.json documentation for more information.

After creating the manifest file, you can add the button snippet where you want. In most cases it will be in the README.md of the project. The snippet looks like this:


The final result will look like this:

This snippet will work for any repo (or fork) because Heroku only looks at the referer header to determine where the request came from. So you do not need to update the snippet when branching and forking.

Buttons, buttons everywhere

The Heroku button is a very clever feature. It significantly lowers the barrier to getting started, and it has the potential to change how a lot of open source projects are used and deployed by end users.

It is of course Heroku-only, and there are many other great services you could deploy to, but for small projects it makes a lot of sense to make use of Heroku’s free tiers.

We encourage you to go out and implement this button on your own projects and (more importantly), contribute it to open source projects that could benefit from it. If you try it out, feel free to comment and tell us about it — we would love to hear about your experiences.

About the author
Vanja Cosic is Opbeat’s community manager, and is the go-to guy in the office for the latest tech. If you have any suggestions, feature requests or just want to troll, you can reach him at vanja@opbeat.com.
You can follow him on Twitter or GitHub.