Generating PDF from HTML using DocRaptor on Heroku

There comes a time one has to create PDFs for a Rails application. Searching the web will most likely bring you to libraries like PDF Kit and Wicket PDF that use wkhtmltopdf as a driver.

If your app is hosted on Heroku you wonder weather wkhtmltopdf is available so that you can use one of these awesome libraries. Searching the Heroku docs, you will probably come to same conclusion: nothing on there!

As the Heroku support states:
You’re correct that there’s no official documentation. Most of our customers seem to be using wkhtmltopdf, generally with pdfkit. I do hope to document this usage soon.

If you want us to offer a Prince add-on, I encourage you to write them inviting them to check out our Add-on Provider Programme:

Of course, you can always purchase your own license and run it on EC2 or another server of your choosing.


One of the libraries that were used at my last job was PrinceXML, which did a great jog generating PDFs from HTML pages. It supports most of the HTML and CSS stuff, passing the ACID2 test. PrinceXML has some additional CSS attributes that enable you to configure additional PDF specific layout settings.


Since PrinceXML is a commercial product, Heroku won’t support it and I did not find anything on the web, that would offer PDF generation as a service. Asking the PrinceXML Forum I found out about DocRaptor. These guys provide a service to convert HTML to XLS or PDF over a webservice interface, extactly what I was looking for. As an additional bonus, they just implemented a gem for supporting the Heroku Add-on interface. Mail to Expected Behavior Support if you want to participate in the private beta.


DocRaptor offers a great service, but they are still in early development. There were some Issues that were resolved recently. If you are a user of PrinceXML you probably know the —baseurl option that allows usage of relative paths for images and stylesheets. DocRaptor adds support for command line options just yet. The feature for generating a PDF from a given URL is even better!

Using DocRaptor from Rails

The latest DocRaptor documentation for the Heroku Add-on is decent and it provides some nice examples.

PDF from raw HTML

Here is what I did to get it running on my Rails 3 project:

# Gemfile
gem "doc_raptor", "0.1.1"

# mime_types.rb
Mime::Type.register_alias "application/pdf", :pdf

# your_controller.rb
def your_pdf_action
  respond_to do |format|
    format.pdf do
      data = DocRaptor.create(:name => 'DocRaptor.pdf', :document_content => render_to_string, :document_type => "pdf", :prince_options => {:baseurl => ''})
      send_data data, :type => 'application/pdf', :filename => 'DocRaptor.pdf'

If you registered the pdf mime-type you will have to provide an additional layout for this. I added some PrinceXML specific parameters to the styles to make it a fullscreen PDF. One thing that is essential for making the stylesheets work is the media => ‘screen, print’ settings:

// application.pdf.haml
= stylesheet_link_tag 'style', :media => 'screen, print'
// you can provide a base tag for images and stylesheets
// %base{:url=>''}

  @page { size: A4 }
  @page { margin: 0px }
  @page { border: none }
  @page { padding: 0px }
  @page { prince-shrink-to-fit: auto }

PDFs from an URL

The simplest solution for generating a PDF is to send an url to the service, so you can re-use all your view logic:

data = DocRaptor.create(:name => "DocRaptor.pdf", :document_url => "", :document_type => "pdf")
send_data data, :type => 'application/pdf', :filename => "DocRaptor.pdf"

One caveat though, you got to have at least two dynos to serve the additional request from DocRaptor!

See a working example on my homepage.

Generating PDF form HTML without the hassle, thanks to DocRaptor!

Published by


I am a professional Software Developer from Hamburg, Germany.

5 thoughts on “Generating PDF from HTML using DocRaptor on Heroku”

  1. Thanks for the kind words, Peter! You’ve been giving us great feedback and ideas.

    As an aside, clicking on the skull images in the upper right of your blog takes one to instead of

  2. you are welcome! thanks for providing such a nice service and fast problem resolution!

    i fixed the link, thanks for reporting.

  3. Thanks for that! I’ll make sure to check it.
    On a different account: Do you guys know that your skulls in the upper right, link the .com version of your blog, which is a parked site? Making some extra cash there ? ;)

Comments are closed.