Sinatra-based Heroku Add-on provisioning service, generated with the Pliny gem.

Deploy your copy via the Heroku Button

Then run the following commands to work with the generated code locally:

heroku git:clone --app <new-app-name>
bin/setup
kensa init
#edit addon-manifest.json in your favorite editor - see notes below
kensa push

Please see How Add-ons Work first.

Most of the work happens in Mediators::* classes, which are invoked via endpoints when something happens relative to an add-on associated with an application.

Endpoints are defined in the lib/endpoints/ directory, and mounted in lib/routes.rb. The most relevant endpoints are in lib/endpoints/heroku/resources.rb.

Look through the code for FIXME comments pointing out specific relevant code paths.

When a heroku customer requests an instance of your add-on, we POST to your add-on's /heroku/resources endpoint identifying the app, the plan, the region and other metadata. This initializes and runs Mediators::Resources::Creator.call, which is where you do whatever creates the services your add-on provides. You return app specific environment variables here that are exported to the provisioning heroku app's environment.

When an add-on is deprovisioned, we send a DELETE request to the /heroku/resources/:id endpoint with the id you returned to us as part of the original provisioning request. This initializes and runs Mediators::Resources::Destroyer.call, which is where you remove the app specific services.

When an add-on's plan changes, we PUT to your add-on's /heroku/resources/:id endpoint with metadata similar to a provisioning call. This initializes and runs Mediators::Resources::Updater.call. If you need to return new environment variables (say, a new connection string because of a plan change), return those here similar to a provisioning call.

The add-on manifest is a JSON document which describes the interface between Heroku and your service. It's used for both local development via the kensa gem and to submit your add-on to the marketplace.

id

Set the value for id to a lowercase, URL-friendly version of your add-on's name.

Choose wisely; once your add-on has been created under this name, it cannot be changed.

api: config_vars

If you wish to provide configuration variables to applications that install your add-on, include every uppercase variable name here. You must list every variable you will send in response to a provision request, or your response will be rejected, and installation will fail for the customer.

If your add-on does not rely on providing environment variables, then you do not need to list config vars here.

Refer to the Building a Heroku Add-on article for instructions and how to use kensa to test your add-on service.

If you're using postgres on linux (rather than osx), you're probably not using a superuser account during development. This means the database init run during ./bin/setup will fail due to insufficient privileges.

The easiest fix is to add the relevant procedural languages to template1 as the postgres superuser, and then re-run ./bin/setup.

    sudo -u postgres psql template1
    psql# create extension "plpgsql";
    psql# create extension "uuid-ossp";

We use bundler-audit to ensure we aren't using gems with known vulnerabilities. It runs automatically in the default rake task and, consequently, on travisci. If a gem with a known vulnerability is found, the build will fail.

• The pliny gem docs
• The pliny wiki
• Building a Heroku Add-on

MIT License. See LICENSE.