Add-on Article Template
Last updated December 08, 2021
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
ADDON-NAME is an add-on for providing functionality X.
Adding functionality X to an application provides benefits X, Y, and Z.
Access ADDON-NAME via its API or its client libraries for [[Java|Ruby|Python|Node.js|Clojure|Scala|PHP|Go]]*.
Provisioning the Add-on
Attach ADDON-NAME to a Heroku application via the CLI:
Reference the Add-on Name Elements Page for a list of available plans and regions.
$ heroku addons:create ADDON-SLUG Creating ADDON-SLUG on sharp-mountain-4005... free Your add-on has been provisioned successfully
After provisioning ADDON-NAME, the
ADDON-CONFIG-NAME config var is available in the attached app’s configuration. It contains the [[variable purpose, for example, “canonical URL used to access the newly provisioned ADDON-NAME service instance.”]]. You can see the config var via the
heroku config:get command:
$ heroku config:get ADDON-CONFIG-NAME http://user:firstname.lastname@example.org/resourceid
After installing ADDON-NAME, the application is fully configured to integrate with the add-on.
[[If running against the add-on service during development isn’t applicable, omit this section.]]
After provisioning the add-on, replicate its config vars locally for development environments that need the service.
local Heroku CLI command to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a
.env file. Use
heroku config to view an app’s configuration variables in a terminal. Use the following command to add a configuration variable to a local
$ heroku config:get ADDON-CONFIG-NAME -s >> .env
Don’t commit credentials and other sensitive configuration variables to source control. In Git exclude the
.env file with:
echo .env >> .gitignore.
For more information, see the Heroku Local article.
[[If there’s a local executable required (like for the Memcache add-on), include installation instructions. If not, omit the entire section.]]
You can install ADDON-NAME for use in a local development environment. Typically, this process entails [[installing the software | creating another version of the service]] and pointing the ADDON-CONFIG-NAME to this [[local | remote]] service.
|Windows||Link to some installer|
|Other||Link to some raw package|
Ruby on Rails
[[Repeat this ###Rails section for all other supported languages and frameworks, including Java, Node.js, Python, Scala, Play!, Grails, Clojure. Heroku is a polyglot platform - don’t box yourself into supporting a single language.]]
Add the following to the
Gemfile, specifying the ADDON-NAME client library.
Update the application dependencies with bundler.
$ bundle install
[[Describe briefly how to use and integrate your service from Rails with code samples]]
[[Repeat structure from Rails section]]
[[Repeat structure from Rails section for each supported language]]
Monitoring and Logging
Display stats and the current state of ADDON-NAME via the CLI:
$ heroku ADDON-SLUG:command example output
Monitor ADDON-NAME activity within the Heroku log stream by [[describe add-on logging recognition, if any]]:
$ heroku logs -t | grep 'ADDON-SLUG pattern'
For more information on the features available within the ADDON-NAME dashboard, see the docs at mysite.com/docs.
The ADDON-NAME dashboard provides [[describe dashboard features]].
Access the dashboard via the CLI:
$ heroku addons:open ADDON-SLUG Opening ADDON-SLUG for sharp-mountain-4005
or by visiting the Heroku Dashboard and selecting the application in question. Select ADDON-NAME from the Add-ons menu.
If [[feature X]] doesn’t seem to be [[common issue Y]] then [[add specific commands to look for symptoms of common issue Y]].
Migrating Between Plans
Application owners must carefully manage the migration timing to ensure proper application function during the migration process.
[[Specific migration process or any migration tips and tricks.]]
heroku addons:upgrade command to migrate to a new plan.
$ heroku addons:upgrade ADDON-SLUG:newplan -----> Upgrading ADDON-SLUG:newplan to sharp-mountain-4005... done, v18 ($49/mo) Your plan has been updated to: ADDON-SLUG:newplan
Removing the Add-on
Remove ADDON-NAME via the CLI:
This action destroys all associated data and you can’t undo it!
$ heroku addons:destroy ADDON-SLUG -----> Removing ADDON-SLUG from sharp-mountain-4005... done, v20 (free)
Before removing ADDON-NAME, export its data by [[describe steps if export is available]].
Submit all ADDON-NAME support and runtime issues via one of the Heroku Support channels. Any non-support-related issues or product feedback is welcome at [[your channels]].