PDFkit hangs when generating a pdf with an image

Question 1

This is a notorious issue, and you're running into it because your probably have relatively linked assets in your HTML (i.e. images, CSS, JS, fonts, etc), and your web server is only capable of handling one request/thread at a time (like WEBrick).

So what happens? The server begins generating the PDF when you request its URL. PDFkit finds a linked asset, so it tries to load this asset from the server, which happens to be the same server that PDFkit is running on. However, the server's single thread is already busy running PDFkit, so it cannot "free up" to serve the requested asset. In conclusion, it's a deadlock -- PDFkit is awaiting on an asset on the same server that is waiting for PDFkit to finish up processing, so that it can serve the asset to PDFkit...

Solution: either Base64-embed your assets in the HTML so that PDFkit doesn't need to make any additional requests (my personally preferred solution), or temporarily offload the assets to another server (e.g. a temporary AWS bucket). You can also try using the unicorn or Thin webserver with multi-threading enabled, or adding config.threadsafe! in in application.rb, but there is no guarantee that these methods will work.

Of course, these hacks (embedding assets or hosting elsewhere) should only be used in the dev environment -- you shouldn't be running into these kinds of issues in production, as the live server should (hopefully) be able to handle multiple GET requests.

Question 2

You can use unicorn in development which serve multiple request at a time. And is easy to setup. refer http://dave.is/unicorn.html and https://devcenter.heroku.com/articles/rails-unicorn

It solved my problem in development.

Question 3

Here's a workround helper

Arman's answer helped me a lot. Here's an implementation that I came up with.

module PdfHelper

  def pdf_image_tag(image_name)
    if Rails.env.development? || Rails.env.test?
      # Unless running a web server that can process 2 requests at the same
      # time, trying to insert an image in a PDF creates a deadlock: the server
      # can't finish processing the PDF request until it gets the image, but it
      # can't start processing the image request until it has finished
      # processing the PDF request.
      # This will not be a problem in production, but in dev, a workaround is
      # to base64 the image and insert its contents into the HTML
      image_data = Rails.application.assets[image_name].to_s
      image_tag "data:image/png;base64,#{::Base64.encode64(image_data)}"
    else
      image_tag image_name
    end
  end

end

Question 4

You are getting this error because by default WEBrick is a single threaded server and is capable of fulfilling one request at a time (because of the single worker thread).To get WEBrick fully multi-threaded in Rails 4.0, just add this to config/initializers/multithreaded_webrick.rb:

# Remove Rack::Lock so WEBrick can be fully multi-threaded.
require 'rails/commands/server'

class Rails::Server
  def middleware
    middlewares = []
    middlewares << [Rails::Rack::Debugger] if options[:debugger]
    middlewares << [::Rack::ContentLength]

    Hash.new middlewares
  end
end

add config.middleware.delete 'Rack::Lock' in your application.rb