[ADDON-NAME](http://addons.heroku.com/ADDON-SLUG) is an [add-on](http://addons.heroku.com) for providing functionality X.
Adding functionality X to an application provides benefits X, Y and Z. [[Sell the benefits here! Don't skimp - developers have many options these days.]]
ADDON-NAME is accessible via an API and has supported client libraries for [[Java|Ruby|Python|Node.js|Clojure|Scala]]*.
## Provisioning the add-on
ADDON-NAME can be attached to a Heroku application via the CLI:
> A list of all plans available can be found [here](http://addons.heroku.com/ADDON-SLUG).
$ heroku addons:add ADDON-SLUG
-----> Adding ADDON-SLUG to sharp-mountain-4005... done, v18 (free)
Once ADDON-NAME has been added a `ADDON-CONFIG-NAME` setting will be available in the app configuration and will contain the [[variable purpose, i.e. "canonical URL used to access the newly provisioned ADDON-NAME service instance."]]. This can be confirmed using the `heroku config:get` command.
$ heroku config:get ADDON-CONFIG-NAME
After installing ADDON-NAME the application should be configured to fully integrate with the add-on.
## Local setup
### Environment setup
[[If running against the add-on service during development is not applicable this section can be omitted]]
After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.
> Though less portable it’s also possible to set local environment variables using `export ADDON-CONFIG-NAME=value`.
Use [Foreman](config-vars#local-setup) to configure, run and manage process types specified in your app’s [Procfile](procfile). Foreman reads configuration variables from an .env file. Use the following command to add the ADDON-CONFIG-NAME values retrieved from heroku config to `.env`.
$ heroku config -s | grep ADDON-CONFIG-NAME >> .env
$ more .env
> Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: `echo .env >> .gitignore`.
### Service setup
[[If there is a local executable required (like for the memcache add-on) then include installation instructions. If not, omit entire section]]
ADDON-NAME can be installed for use in a local development environment. Typically this entails [[installing the software | creating another version of the service]] and pointing the ADDON-CONFIG-NAME to this [[local | remote]] service.
## Using with Rails 3.x
[[Repeat this ##Rails 3.x sections for all other supported languages/frameworks including Java, Node.js, Python, Scala, Play!, Grails, Clojure. Heroku is a polyglot platform - don't box yourself into supporting a single language]]
Ruby on Rails applications will need to add the following entry into their `Gemfile` specifying the ADDON-NAME client library.
Update application dependencies with bundler.
$ bundle install
[[Describe briefly how to use/integrate your service from Rails 3.x with code samples]]
## Using with Python/Django
[[Repeat structure from Rails 3.x section]]
## Using with Java, Node....
[[Repeat structure from Rails 3.x section for each supported language]]
## Monitoring & Logging
Stats and the current state of ADDON-NAME can be displayed via the CLI.
$ heroku ADDON-SLUG:command
ADDON-NAME activity can be observed 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 please see the docs at [mysite.com/docs](mysite.com/docs).
The ADDON-NAME dashboard allows you to [[describe dashboard features]].
The dashboard can be accessed via the CLI:
$ heroku addons:open ADDON-SLUG
Opening ADDON-SLUG for sharp-mountain-4005…
or by visiting the [Heroku apps web interface](http://heroku.com/myapps) and selecting the application in question. Select ADDON-NAME from the Add-ons menu.
If [[feature X]] does not seem to be [[common issue Y]] then
[[add specific commands to look for symptoms of common issue Y]].
## Migrating between plans
> Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
[[Specific migration process or any migration tips 'n tricks]]
Use the `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
ADDON-NAME can be removed via the CLI.
> This will destroy all associated data and cannot be undone!
$ heroku addons:remove ADDON-SLUG
-----> Removing ADDON-SLUG from sharp-mountain-4005... done, v20 (free)
Before removing ADDON-NAME a data export can be performed by [[describe steps if export is available]].
All ADDON-NAME support and runtime issues should be submitted via on of the [Heroku Support channels](support-channels). Any non-support related issues or product feedback is welcome at [[your channels]].
|If you have...
|Mac OS X
brew install X
||Link to some installer
apt-get install X
||Link to some raw package