Migration guides · Ruby on Rails

Replace `wkhtmltopdf` with pdfkiln in `wicked_pdf`

wicked_pdf renders Rails views to PDF with wkhtmltopdf, usually from the wkhtmltopdf-binary gem. Remove the gem, install pdfkiln, point wicked_pdf at it.

1. Install pdfkiln

On Debian and Ubuntu, amd64 and arm64: the signed APT repository installs /usr/bin/wkhtmltopdf in place of the wkhtmltox package, and brings Chromium’s fixes with apt upgrade.

curl -fsS https://apt.pdfkiln.org/pdfkiln-archive-keyring.asc | sudo tee /usr/share/keyrings/pdfkiln-archive-keyring.asc > /dev/null
printf 'Types: deb\nURIs: https://apt.pdfkiln.org\nSuites: stable\nComponents: main\nSigned-By: /usr/share/keyrings/pdfkiln-archive-keyring.asc\n' \
  | sudo tee /etc/apt/sources.list.d/pdfkiln.sources
sudo apt update && sudo apt install pdfkiln

Elsewhere: the Docker image, the archives and the Windows installer.

2. Point `wicked_pdf` at it

# Gemfile: remove the gem that bundled wkhtmltopdf
# gem 'wkhtmltopdf-binary'

# config/initializers/wicked_pdf.rb
WickedPdf.config = { exe_path: '/usr/bin/wkhtmltopdf' }

3. Check

wkhtmltopdf --version
# wkhtmltopdf 0.12.6 (with patched qt), pdfkiln 1.0.4, Chromium 156.0.8078.80

The answer starts as wkhtmltopdf 0.12.6’s does: libraries that read the version keep working.

What `wicked_pdf` expects, and what pdfkiln does

wicked_pdf reads wkhtmltopdf --version with wkhtmltopdf\s*(\d*\.\d*\.\d*\w*) to choose its syntax: pdfkiln’s answer starts with wkhtmltopdf 0.12.6, so the current syntax stays.
Headers and footers rendered from views are --header-html and --footer-html pages: their JavaScript, and the variables wkhtmltopdf puts in their query string (page, topage, section…), work unchanged.

Tested

wicked_pdf 2.7.0’s own test suite passes with pdfkiln in place of wkhtmltopdf (Ubuntu, CI job libraries).

Something renders differently? Open an issue with the HTML and both PDFs: github.com/Jamalofski/pdfkiln/issues. The known differences are listed in the README.

Replace wkhtmltopdf with pdfkiln in wicked_pdf