Becoming an Add-on Provider
Last updated 26 August 2015
In order to effectively market your product to the Heroku community, you will need to be familiar with the basic Heroku user experience. If your team is new to the Heroku platform, we highly recommend you walk through the core concepts of creating and deploying an application on Heroku, to understand what sort of experience your future add-on customers will expect.
Once you’ve got that down, check out the article which covers how your service will interact with the Heroku platform.
After completing the tour, you should be ready to start the technical integration of your add-on service. To help guide you along there’s both a step-by-step tutorial as well as several code examples.
Building & Testing
One of the key goals for the Add-on Program is to make the process and experience of building add-ons as easy as possible. We’ve made sure that it’s an open playground to experiment on - there is no registration or setup required to start building an add-on. In many cases a day or two is all that is needed to produce a working add-on.
Before you can load your add-on onto Heroku, and begin testing it with real users, you must register on our Provider Portal as an Add-on Provider. All that’s required to do this is a Heroku account.
If you already have an existing account, you will log in with your existing credentials. If not, you will be able to sign-up for a new account. Upon sign-up/registration you will need to accept the terms of the Heroku Add-ons License Agreement.
The purpose of this agreement is formally set up the business relationship between your company and Heroku. It covers the following:
- Distribution agreement granting Heroku permission to distribute your product via the Add-on Marketplace.
- Intellectual property protection for both parties.
- Revenue sharing terms, including payments, reporting and audits.
- Rules for pricing changes.
- Confidentiality, allowing your company and Heroku to safely share details about upcoming product features, usage metrics etc.
- Technical support and marketing responsibilities.
You can download a copy of the agreement here. Be sure to familiarize yourself thoroughly with the terms and conditions before signing up.
Once registered you will have access to the Provider Portal, which gives you a single place to manage your Add-ons and your relationship with Heroku and offers instructions on how to submit your Add-ons to Heroku.
Bootstrapping an Add-on Provider
This is a short guide showing how to get started building your own add-on. It assumes you’ve read the docs on building an Add-on.
Cloning a template add-on
kensa create command will clone a template add-on from GitHub (or any git URL) so you can immediately get started with a working application that implements the cloud services API. It will also create an
addon-manifest.json file for you and a matching
.env file you can use to boot up your app locally with correct credentials via
Say you wanted to clone the sinatra add-on template into the directory
my_addon. You would use the following command:
$ kensa create my_addon --template sinatra Cloning into my_addon... remote: Counting objects: 92, done. ... Created my_addon from sinatra template Initialized new addon manifest in addon-manifest.json Initialized new .env file
The templates are simply cloned from the github repository at http://github.com/heroku/kensa-create-sinatra. Alternatively you can provide a full git URL of a different template to use.
Starting the template add-on
After cloning the template, you can start it with
heroku local. Heroku and kensa use the credentials provided in your
addon-manifest.json for API authentication. Your app also needs to be aware of these credentials. Because we don’t recommend checking the manifest into version control, the template app is designed to read the credentials from the environment.
kensa create writes a
.env file that matches the credentials in
HEROKU_USERNAME matches the id, the
HEROKU_PASSWORD matches the API passsword, and the
SSO_SALT matches the API sso_salt.
heroku local uses the
.env file to create an environment for its applications. Refer to the Heroku Local article for more advanced
.env file usage.
$ cd my_addon $ bundle install $ heroku local 17:57:39 web.1 | started with pid 12966
This will start your freshly cloned add-on on port 5000. You can now test your add-on with the
Testing the template add-on
In a new shell:
$ cd path/to/my_addon $ kensa test provision #look at the output for the id of the provisioned resource Testing POST /heroku/resources Check response [PASS] Check valid JSON [PASS] Check authentication [PASS] Testing response Check contains an id [PASS] (id 1) $ kensa test planchange <id> <newplan> $ kensa test sso <id> $ kensa sso <id> $ kensa test deprovision <id> $ kensa test all
After you’ve confirmed everything is working, you can rename your add-on by editing the
.env files and concentrate on your application logic.