Archived Support Site

This support site is archived. You can view the old support discussions but you cannot post new discussions.

Building an AppHarbor Add-on

Introduction

So, you've read about the AppHarbor add-on program and have decided to build an add-on for the platform? Here's what you need to know.

The AppHarbor add-on API is compatible with the Heroku add-on API and the process of becoming an add-on provider is -- for all intents and purposes -- the same as on Heroku. For that reason, we recommend following the Heroku add-on provider guide.

(now is good time to go read through that)

Registering your Add-on on AppHarbor

Once you have created your add-on and tested it with Kensa, follow these steps:

Create an AppHarbor account
Make sure you're logged in, then create an AppHarbor add-on provider
Create an add-on using a manifest with AppHarbor-specific password, sso-salt and id

At this point, you will be able to provision the add-on to applications controlled by your account. The add-on is also visible to AppHarbor employees for testing. It's not visible to other AppHarbor users. Once you've tested the add-on on AppHarbor, drop us a line at [email protected] and we'll give it a whirl before adding it to the add-on catalog.

Sample Code

We have created a .NET add-on template project if you want to implement your add-on in .NET. Heroku has sample code in both Ruby and Python.

Sample Application

If you want to offer an add-on on AppHarbor, but don't have enough .NET-fu to create a test-application, we provide a sample .NET application. Create an application on AppHarbor and do the following, substituting the AppHarbor repository URL for the one shown on the application dashboard:

git clone https://github.com/appharbor/AddonProviderSampleApplication
git remote add appharbor REPOSITORY_URL_FROM_APPLICATION_DASHBOARD
git push appharbor master~1:master
git push appharbor master

This should build and deploy on AppHarbor, and will give you two builds that you can play around with.

Manifest

Here is an example manifest (you should use kensa to generate yours). AppHarbor only supports the "old" manifest format, without a Sso_Url. A SSO url can be added once the add-on has been created. Note that plans are created through the add-on provider web interface:

{
  "id": "foo",
  "name": "Foo",
  "api": {
    "config_vars": [
      "FOO_URL"
    ],
    "production": "https://example.com/",
    "test": "http://localhost:4000/",
    "username": "appharbor",
    "password": "baf",
    "sso_salt": "bof"
  }
}

API URL endpoint

You're free to specify whatever you url you want as "production" API endpoint. AppHarbor will not add any additional url segments. If you already host an add-on on Heroku and want to use the the exact same endpoint, you should specify https://example.com/heroku/resources.

Regions

AppHarbor supports running applications in regions other that US-East. Moving apps between regions is not supported

To let you know where the app provisioning an add-on is located, we have extended the Heroku provisioning API slightly. We provide a region parameter in the provision request. amazon-web-services::us-east-1 and amazon-web-services::eu-west-1 are valid values.

It's up to you, the add-on provider, whether you want to take advantage of region information in the provision request. If your add-on is not latency-sensitive (email, etc.), it's probably safe to ignore it. If your add-on is latency sensitive and you're currently running your service in eu-west, we -- and our users -- would appreciate it if the requested resource was provisioned in eu-west for provision-requests specifying amazon-web-services::eu-west-1 as the region.

If you're not running infrastructure in eu-west and you don't think your add-on is usable from the eu-west data center (or maybe you don't want to incur ingress/outgress bandwidth charges), you can respond with HTTP 422 or 503 and a message in the response body, something like this: { "message": "eu-west not supported, sorry" }

In the add-on provider dashboard (https://appharbor.com/addonprovider), you can specify which regions
your add-ons support. If your add-on is not region-sensitive, you should specify support for all regions. AppHarbor users can provision your add-on to apps running in unsupported regions but we'll display a
warning to let them know that performance might not be optimal. If your add-on supports the current application region for an app that a user is about to provision your add-on to, no warning will be displayed.

Logplex

AppHarbor supports adding a Logplex log drain during the provisioning process. You can also log back to a customer's Logplex channel. Contact us for more details.

Other

AppHarbor supports all aspects of the Heroku add-on API, including Single Sign On. The AppHarbor SSO header is available here. We expect addon-providers to set a cookie called appharbor-nav-data with the contents of the nav-data url parameter.

AppHarbor supports both GET-based and POST-based SSO logins. If you want to use the new POST SSO scheme, you have to add the url you want us to POST users to in the "manage add-on endpoint" interface.

Like Heroku, AppHarbor also provides a callback_url in the provision request. This url can be used to PUT a new config hash and to GET information about the add-on as provisioned to the application. Here's a sample response to a GET (where {guid} is a unique identifier):

{
    "callback_url":"https://appharbor.com/addons/{addonname}/resources/{guid}",
    "config":"{\"ADDONNAME_CONFIGVAR\":\"Foo\"}",
    "domains":["Foo.apphb.com"],
    "id":"{guid}@apphb.com",
    "name":"Foo",
    "owner_email":"{guid}@apphb.com",
    "region":"{region-identifier}"
}

This is a sample payload that you can PUT to update the configuration:

{
    "config": {
        "ADDONNAME_CONFIGVAR": "Foo"
    }
}

AppHarbor also supports retrieving info on all the current provisions of your add-on on AppHarbor. This is available at https://appharbor.com/addons/{addon}/resources/.

Emails

Note that we do not provide actual AppHarbor user email addresses to add-on providers but emails sent to the heroku_id passed in the provision response are routed to our users (you can also query for owner_email address, it's the same value).

Custom transforms

AppHarbor can perform custom transforms if your add-on requires configuration other than merely inserting keys into appSettings. Let us know what your needs are, and we'll add the necessary transformations.

AppHarbor Support