This add-on is operated by Expected Behavior

Painless pdf and excel file creation


Last Updated: 10 February 2014

addons pdf

Table of Contents

The DocRaptor add-on allows you to create PDF and XLS documents on the fly from your application using the DocRaptor webservice. Your application passes in HTML and some options, you get a pdf or an excel file back.

DocRaptor is accessible via an API and has supported client libraries for Ruby, Python, Node.js, and Javascript, though it can be used by any language with support for making HTTP requests. We also permit unlimited test docs with our service free of charge so you can hone your documents to look exactly how you want them to.

Provisioning the add-on

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

A list of all plans available can be found here.

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

Once DocRaptor has been added a DOCRAPTOR_API_KEY setting will be available in the app configuration and will contain the API key used to make requests against our document creation API. This can be confirmed using the heroku config:get command.

$ heroku config:get DOCRAPTOR_API_KEY

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

Local setup

Environment setup

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 DOCRAPTOR_API_KEY=api_key.

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 DOCRAPTOR_API_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep DOCRAPTOR_API_KEY >> .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.

Using with Rails 3.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the DocRaptor client library.

gem 'doc_raptor'

Update application dependencies with bundler.

$ bundle install

A very basic example of using DocRaptor to create a document might look something like this:

DocRaptor.create(:document_content => "<html><body>Some HTML!</body></html>", :document_type => "pdf")

Using with Python/Django, Java, Node.js, etc.

There are many more samples on the DocRaptor Coding Examples page.

Monitoring & Logging

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

$ heroku docraptor:command
example output


For more information on the features available for DocRaptor please see the docs at

The DocRaptor dashboard allows you to review logs from previous documentation creation requests.

The dashboard can be accessed via the CLI:

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

or by visiting the Heroku apps web interface and selecting the application in question. Select DocRaptor from the Add-ons menu.


If document generation does not seem to be working then check your document logs on the DocRaptor dashboard.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade docraptor:premium
-----> Upgrading docraptor:newplan to sharp-mountain-4005... done, v1 ($95/mo)
       Your plan has been updated to: docraptor:premium

Removing the add-on

DocRaptor can be removed via the CLI.

This will destroy all associated data and cannot be undone!

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


Billing and Heroku account issues should be submitted via one of the Heroku Support channels. All technical questions and product feedback is welcome by contacting us at