.. _heroku:

Setting up an app on Heroku
===========================

Once you have an app ready to go using baldrick, you can deploy it to any
server you want. Here we provide instructions on setting it up on Heroku.

To start off, create a free account on Heroku if you don't already have one.
When you see the option to create a new app, select it (ignore the "add to
pipeline" option). Give a name to your app; You need to select a name that is
not already taken and it does not have to be the same as the bot's name here.

You should now be on the "Deploy" section. Again, ignore the pipeline
option. Select Github as "Deployment Method". Enter the relevant GitHub
organization or account that the bot resides in (this should be automatically
populated if you have given Heroku access to your GitHub account) and type
in the bot's repository name (either this bot or a forked version of it).

If you want to enable automatic deployment from a selected branch of the
repository, click the "Enable Automatic Deploys" button. This will pick up
changes to the given branch and re-deploy the bot as needed.
For most cases, you don't need the "wait for CI to pass before deploy"
option as the bot is already tested here.

For the first time, you also need to manually deploy the bot by clicking
"Deploy Branch".

Once it is successfully deployed, and once you have followed the instructions to
add the app to GitHub (see :ref:`github`) go to "Settings" tab of the app on
Heroku and you can customize its behavior using "Config Vars". This is the only
custom configuration on Heroku and can be set through the Heroku admin
interface, as mentioned. The main required environment variables (also see
"Authentication" section below) are:

* ``GITHUB_APP_INTEGRATION_ID``, which should be set to the integration ID
  provided by GitHub app (see "GitHub settings" section below) under
  "General Settings", specifically "About... ID". This is a numerical integer
  value.

* ``GITHUB_APP_PRIVATE_KEY``, which is generated by the GitHub app
  (see "GitHub settings" section below).
  This private key should look like:

  ```
  -----BEGIN RSA PRIVATE KEY-----
  <some random characters>
  -----END RSA PRIVATE KEY-----
  ```

  The whole key, including the ``BEGIN`` and ``END`` header and footer
  should be pasted into the field.
