app.json Schema

Last updated 01 July 2016

app.json is a manifest format for describing web apps. It declares environment variables, add-ons, and other information required to run an app on Heroku. This document describes the schema in detail.

See the Setting Up Apps using the Platform API for details on how to use app.json to set up apps on Heroku.

Example app.json

{
  "name": "Small Sharp Tool",
  "description": "This app does one little thing, and does it well.",
  "keywords": [
    "productivity",
    "HTML5",
    "scalpel"
  ],
  "website": "https://small-sharp-tool.com/",
  "repository": "https://github.com/jane-doe/small-sharp-tool",
  "logo": "https://small-sharp-tool.com/logo.svg",
  "success_url": "/welcome",
  "scripts": {
    "postdeploy": "bundle exec rake bootstrap"
  },
  "env": {
    "SECRET_TOKEN": {
      "description": "A secret key for verifying the integrity of signed cookies.",
      "generator": "secret"
    },
    "WEB_CONCURRENCY": {
      "description": "The number of processes to run.",
      "value": "5"
    }
  },
  "formation": {
    "web": {
      "quantity": 2,
      "size": "Performance-M"
    }
  },
  "image": "heroku/ruby",
  "addons": [
    "openredis",
    {
      "plan": "mongolab:shared-single-small",
      "as": "MONGO"
    },
    {
      "plan": "heroku-postgresql",
      "options": {
        "version": "9.5"
      }
    }
  ],
  "buildpacks": [
    {
      "url": "https://github.com/stomita/heroku-buildpack-phantomjs"
    }
  ]
}

Schema Reference

name

(string, optional) A clean and simple name to identify the template (30 characters max).

{
  "name": "Small Sharp Tool"
}

description

(string, optional) A brief summary of the app: what it does, who it’s for, why it exists, etc.

{
  "description": "This app does one little thing, and does it well."
}

keywords

(array, optional) An array of strings describing the app.

{
  "keywords": [
    "productivity",
    "HTML5",
    "scalpel"
  ]
}

website

(string, optional) The project’s website.

{
  "website": "https://small-sharp-tool.com/"
}

repository

(string, optional) The location of the application’s source code, such as a Git URL, GitHub URL, Subversion URL, or Mercurial URL.

{
  "repository": "https://github.com/jane-doe/small-sharp-tool"
}

logo

(string, optional) The URL of the application’s logo image. Dimensions should be square. Format can be SVG, PNG, or JPG.

{
  "logo": "https://small-sharp-tool.com/logo.svg"
}

success_url

(string, optional) A URL specifying where to redirect the user once their new app is deployed. If value is a fully-qualified URL, the user should be redirected to that URL. If value begins with a slash /, the user should be redirected to that path in their newly deployed app.

{
  "success_url": "/welcome"
}

scripts

(object, optional) A key-value object specifying scripts or shell commands to execute at different stages in the build/release process. Currently, postdeploy is the only supported script.

{
  "scripts": {
    "postdeploy": "bundle exec rake bootstrap"
  }
}

env

(object, optional) A key-value object for environment variables, or config vars in Heroku parlance. Keys are the names of the environment variables. Values can be strings or objects. If the value is a string, it will be used. If the value is an object, it defines specific requirements for that variable:

• description: a human-friendly blurb about what the value is for and how to determine what it should be
• value: a default value to use. This should always be a string.
• required: A boolean indicating whether the given value is required for the app to function (default: true).
• generator: a string representing a function to call to generate the value. Currently the only supported generator is secret, which generates a pseudo-random string of characters.

{
  "env": {
    "SECRET_TOKEN": {
      "description": "A secret key for verifying the integrity of signed cookies.",
      "generator": "secret"
    },
    "WEB_CONCURRENCY": {
      "description": "The number of processes to run.",
      "value": "5"
    }
  }
}

formation

(object, optional) A key-value object for process type configuration. Keys are the names of the process types. Values are objects like the formation resource:

• quantity: number of processes to maintain
• size: dyno size according to this list (default: Standard-1X)

{
  "formation": {
    "web": {
      "quantity": 2,
      "size": "Performance-M"
    }
  }
}

image

(string, optional) The Docker image that can be used to build the app. This key is used by Heroku-Docker to provision local Docker containers.

{
  "image": "heroku/nodejs"
}

Official, maintained Docker images can be found on Heroku’s Docker Hub.

addons

(array, optional) An array of strings or objects specifying Heroku add-ons to provision on the app before deploying.

If an add-on plan is given as an object, the following properties configure the add-on:

• plan: (string, required) The add-on and plan to provision. This should should be in the format addon:plan or addon. If plan is omitted, that addon’s default plan will be provisioned.
• as: (string, optional) The attachment name for the new add-on. If the attachment name is omitted, the add-on will be attached using its default name.
• options: (object, optional) Any add-on-specific options (for example, the database version to provision with Heroku PostgreSQL). Keys correspond to option names from the add-on’s documentation. Values correspond to add-on option values, and should be strings. For options that do not take a value, use the value true.

If an add-on is given as a string, the string should should be in the format addon:plan or addon. The add-on will be provisioned with its default attachment name and options. The object form is preferred.

{
  "addons": [
    "openredis",
    {
      "plan": "mongolab:shared-single-small",
      "as": "MONGO"
    },
    {
      "plan": "heroku-postgresql",
      "options": {
        "version": "9.5"
      }
    }
  ]
}

buildpacks

(array, optional) An array of objects specifying the buildpacks needed to build the app. Each buildpack object must contain a url field where the buildpack can be downloaded or cloned from. The last buildpack in the list will be used to determine the process types for the application.

The shorthand names for officially supported buildpacks can also be used as a URL.

{
  "buildpacks": [
    {
      "url": "https://github.com/heroku/heroku-buildpack-pgbouncer"
    },
    {
      "url": "heroku/ruby"
    }
  ]
}