eglobebizcom / heroku-addon-docs Goto Github PK

Rainforest is an add-on 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.]]

Rainforest is accessible via an API and has supported client libraries for [[Java|Ruby|Python|Node.js|Clojure|Scala]]*.

Rainforest can be attached to a Heroku application via the CLI:

callout A list of all plans available can be found here.

$ heroku addons:add rainforest
-----> Adding rainforest to sharp-mountain-4005... done, v18 (free)

Once Rainforest 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 Rainforest service instance."]]. This can be confirmed using the heroku config:get command.

$ heroku config:get ADDON-CONFIG-NAME
http://user:[email protected]/resourceid

After installing Rainforest the application should be configured to fully integrate with the add-on.

[[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.

callout Though less portable it’s also possible to set local environment variables using export ADDON-CONFIG-NAME=value.

Use Foreman to configure, run and manage process types specified in your app’s 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

warning Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

[[If there is a local executable required (like for the memcache add-on) then include installation instructions. If not, omit entire section]]

Rainforest 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.

[[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 Rainforest client library.

gem 'rainforest'

Update application dependencies with bundler.

$ bundle install

[[Describe briefly how to use/integrate your service from Rails 3.x with code samples]]

[[Repeat structure from Rails 3.x section]]

[[Repeat structure from Rails 3.x section for each supported language]]

Stats and the current state of Rainforest can be displayed via the CLI.

$ heroku rainforest:command
example output

Rainforest activity can be observed within the Heroku log-stream by [[describe add-on logging recognition, if any]].

$ heroku logs -t | grep 'rainforest pattern'

callout For more information on the features available within the Rainforest dashboard please see the docs at mysite.com/docs.

The Rainforest dashboard allows you to [[describe dashboard features]].

The dashboard can be accessed via the CLI:

$ heroku addons:open rainforest
Opening rainforest for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Rainforest 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]].

Use the heroku addons:upgrade command to migrate to a new plan. Your plan change will be reflected immediately.

$ heroku addons:upgrade rainforest:newplan
-----> Upgrading rainforest:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: rainforest:newplan

Rainforest can be removed via the CLI.

warning This will destroy all associated account data and cannot be undone!

$ heroku addons:remove rainforest
-----> Removing rainforest from sharp-mountain-4005... done, v20 (free)

All Rainforest support and runtime issues should be submitted via on of the Heroku Support channels.