Add-on Article Template
Last updated August 22, 2022
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 example-app... 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:pass@instance.ip/resourceid
After installing ADDON-NAME, the application is fully configured to integrate with the add-on.
Local Setup
Environment Setup
[[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.
Use the 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 .env file:
$ 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.
Service Setup
[[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.
| On… | Install with… |
|---|---|
| macOS | brew install X |
| Windows | Link to some installer |
| Ubuntu Linux | apt-get install X |
| Other | Link to some raw package |
Language-Specific Integrations
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.
gem 'ADDON-SLUG'
Update the application dependencies with bundler.
$ bundle install
[[Describe briefly how to use and integrate your service from Rails with code samples]]
Python/Django
[[Repeat structure from Rails section]]
Java, Node….
[[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'
Dashboard
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.
Troubleshooting
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.]]
Use the heroku addons:upgrade command to migrate to a new plan.
$ heroku addons:upgrade ADDON-SLUG:newplan
-----> Upgrading ADDON-SLUG:newplan to example-app.. 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 example-app... done, v20 (free)
Before removing ADDON-NAME, export its data by [[describe steps if export is available]].
Support
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]].