App setups are the technology powering Heroku Button. To simplify setting up source code that you maintain, consider adding a Heroku Button to the README or to relevant guides and tutorials.

Here are some scenarios were app.json and app-setups might come in handy for source code that you maintain:

You want to make it easy for collaborators to setup and deploy your source code to Heroku for testing in staging apps

You maintain a ready-to-deploy app or framework and you want to let others quickly deploy and try it out on Heroku

The app-setups resource accepts a tar archive of an application’s source code, looks for the app.json manifest file, and uses it to orchestrate the first time setup of the application on Heroku, streamlining the deployment and release of the application.

Preparing for the setup

Imagine that you want to deploy a simple application using the app-setups resource. This may be your own application or, a sample or template you are interested in.

The ruby-rails-sample sample application is such an example. Note that this API applies to apps written in any language, and we’re just using Ruby here as an example.

The first step is to add an app.json configuration file to the app. This app’s configuration includes:

a config var in the runtime environment to customize the template

a couple of add-ons:

Papertrail for logging

Heroku Postgres for the database.

a command to be run after deployment to prepare the database.

To call the API, you need the URL of its source tarball.For this example, use this URL. The API expects the app.json file, that contains this configuration information, to be present at the root of the source bundle’s directory structure.

If you are using a public GitHub repo for your source code, GitHub provides a specific URL for each repo that resolves to a tarball of the repo’s contents. This URL typically looks like: https://github.com/<username>/<repo name>/tarball/master/

Creating an app setup

With a source tarball, which contains an app.json, call the https://api.heroku.com/app-setups endpoint to setup the app.json enabled application on Heroku. The request body must contain a source URL that points to the tarball of your application’s source code.

Optionally, the request can include an overrides section to provide values for environment variables specified in the app.json, override default values, or to provide additional environment variables. The only portion of the app.json that you can override is the env section.

At any point a step in the setup process fails, the app is deleted but the setup status is always available.

Once the build status has been updated to succeeded or failed you can use the build ID to call the Platform API for more detailed status of the build. See the Building and Releasing using the Platform API for more information. To construct the build status request, you need both the name of the app being set up and the build ID; both of these are available in the response above.

The output of the post deploy script is provided inline within the response to the polling request for the overall setup status.

"postdeploy": {
"output": "",
"exit_code": 0
}

When the status is succeeded, the resolved_success_url is populated with a fully-qualified URL to which to redirect users upon completion of the setup. The value is derived from the success_url attribute in the app.json manifest file. If the success_url is absolute, it is returned as-is; if it relative, it is resolved in the context of the app’s web_url.

"resolved_success_url": "http://pacific-peak-6986.herokuapp.com/"

Behind the scenes

Here’s a look at what the Heroku Platform API does with different elements in the app.json file. Apps that are set up with app.json generally work the same as apps deployed with the git based workflow. Note that app-setups use the Build API, and if source tarballs are fetched from GitHub, then those source tarballs will not have git submodules restored.

Application metadata

The name, description, website, repository and logo fields provide basic information about the application. This is simply for users looking at the app.json to understand what the application is about—the API does not use this section during application setup.

"name": "Ruby on Rails",
"description": "A template for getting started with the popular Ruby framework.",
"website": "http://rubyonrails.org"

Environment variables

The env section consists of a series of variables with more information about them. For each variable, the API sets up a config var on the app.

A variable can have a description and a default value. As shown in a previous example, the Platform API request may include a overrides section that provides values to override these defaults.

If a value is provided in the app.json, the API treats it as a required variable. Values for variables must be provided in the overrides section when the Platform API is called or the setup will fail. Optional variables can be specified with "required": false.

Some variables need values that are generated when the application is deployed and set up. You may specify a generator for these variables. The only generator supported today is secret which generates a 64 character hexadecimal string.

This section may also contain a BUILDPACK_URL to specify which buildpack should be used to build the application’s slug.

Add-ons

"addons": ["heroku-postgresql:hobby-dev", "papertrail"]

The API provisions add-ons immediately after creating the app, before the code is built and released. The app.json may specify just the add-on name or the add-on name together with a specific tier. When no tier is specified, the Platform API provisions the lowest tier, which for many add-ons is its free tier.

Post-deployment scripts

You can specify one postdeploy script in the app.json file. This script will be executed by Heroku on a one-off dyno as soon as your application has been built and released. The script is run in the same environment as your application and has access to its config vars and add-ons.

"scripts": {
"postdeploy": "bundle exec rake db:migrate"
}

If you have multiple commands to execute, put them in a script, add the script to the source bundle and provide the command you would use to run that script as the value for postdeploy. You can also write your scripts in the same language as your application and provide the appropriate command such as rails setup-script.rb.

The deployed app

The Heroku app in this example has been setup with the following config vars: