Replace wicked_pdf with ferrum_pdf for PDF generation

[chahmedejaz]

What? Why?

• Closes Replace wicked_pdf and wkhtmltopdf-binary gems #13547

Replace wicked_pdf and wkhtmltopdf with ferrum_pdf for PDF generation across invoices and reporting.

wkhtmltopdf, the underlying tool currently used for PDF generation, has been archived and is no longer maintained. While wicked_pdf is still actively maintained, there are currently no plans to move away from supporting wkhtmltopdf, which makes our current PDF stack a growing piece of technical debt.

Key changes:

• Remove wicked_pdf and wkhtmltopdf-binary dependencies.
• Introduce a dedicated PdfRenderer service using FerrumPdf.render_pdf.
• Replace invoice PDF rendering flow from render_with_wicked_pdf to send_data.
• Remove wicked_pdf-specific helpers and initializers.
• Replace wicked_pdf_image_tag with standard Rails image_tag.
• Simplify stylesheet handling since Ferrum resolves relative asset paths using display_url.
• Add Ferrum configuration for CI and Docker environments.
• Adjust PDF scale (0.85) to better match previous wicked_pdf output and reduce layout regressions.
• Add specs for the new rendering service and update invoice renderer specs.

This migration also removes several workarounds and monkey patches that previously existed to support wkhtmltopdf limitations.

What should we test?

• Visit the admin order invoice page and print/download invoices.
• Verify invoice PDFs render correctly for all types of invoice templates.
• Verify distributor logos render correctly in generated PDFs.
• Verify stylesheets and background colors are correctly applied in PDFs.
• Verify long invoices still paginate correctly and table headers behave as expected across pages.
• Verify reporting PDFs still generate correctly.
• Compare generated PDFs against previous wicked_pdf output for layout consistency and scaling.
• Verify other places from where we are generating PDFs if any

Release notes

Changelog Category (reviewers may add a label for the release notes):

• User facing changes
• API changes (V0, V1, DFC or Webhook)
• Technical changes only
• Feature toggled

Dependencies

• Chrome needs to be present on servers for this to work. It's handled here: Install FerrumPDF browser dependencies ofn-install#1060

[rioug]

It looks mostly good, there are a couple of things to address.

[rioug]

That seems redundant, specifying the default in the method definition should be enough ? or maybe I am missing something ?

[chahmedejaz]

Yes, it seems so; however, if by any chance display_url is passed as nil, then the default value would be overridden with nil, which will break the flow.

ref: https://github.com/openfoodfoundation/openfoodnetwork/pull/14221/changes#diff-6c6be13436a2ea06a1d07fb497d53f757f1113601f8f38f408134552bea87b4dR14-R42

[chahmedejaz]

Now I think about it more, we could avoid sending display_url from here and just use the default value in the pdf renderer. I'll update that

[chahmedejaz]

It has been addressed here: 4b65460

[rioug]

The original comment says :

    # Conversion from PDF to text struggles with multi-line text.
    # We avoid that by printing on bigger pages.
    # https://github.com/openfoodfoundation/openfoodnetwork/pull/9674

Should we check if this still an issue ?
Comment from the issue : #9674 (review)
It's due to known bug, which have not been fixed. So I think we can keep it like this, but could you add the original comment ?

[chahmedejaz]

Good catch! Yes, I observed this as well while writing specs, and missed adding that comment. It's still an issue and a very annoying one 😅

It's addressed here: 4c27242

[chahmedejaz]

Thanks for the feedback, @rioug. It's addressed and ready for review. Thanks

[rioug]

Much simpler, Thanks !

[mkllnk]

Nice work!

[ValVerCH]

Hi @openfoodfoundation/reviewers , I have tested it and all seems ok, see the PDF attached, only there is a point of Attention below that I detected on Staging_AU (not related to this issue I think, but strange maybe to fix to be sure our tests are correct with the logos of enterprises)

ATTENTION
There is no logo on the invoice at the top right, but instead there is the name of order cycle, here so called “Toute l’année”
And it appears the same after the PR deployment
So I guess it is something to be fixed on Staging_AU

OFN Testing - PDF generation#14221.pdf

[RachL]

@ValVerCH FYI there are 2 invoices templates in OFN. Super admins can change the template here: https://staging.openfoodnetwork.org.au/admin/invoice_settings/edit

Only the alternative invoice template has the logo. So what you've seen is the expected behavior of the classic OFN template. All good :)

[ValVerCH]

super Merci beaucoup Rachel ! [logo] OPEN FOOD NETWORK Schweiz, Suisse, Svizzera Valérie Veron (basée à Attalens-Fribourg) PROJECT MANAGER Circuits courts et Alimentation durable T : M : F : [T :][M :]+41 79 256 42 42 ***@***.*** Wasserwerkgasse 2 3011 Bern - SWITZERLAND [https://] [avatar] Le 2026-05-20T17:34:49.000+02:00, Rachel Arnould ***@***.***> a écrit :

…

 RACHL left a comment (openfoodfoundation/openfoodnetwork#14221)  [#14221 (comment)] ***@***.*** [https://github.com/ValVerCH] FYI there are 2 invoices  templates in OFN. Super admins can change the template here:  https://staging.openfoodnetwork.org.au/admin/invoice_settings/edit    Only the alternative invoice template has the logo. So what you've  seen is the expected behavior of the classic OFN template. All good  :)    —  Reply to this email directly, view it on GitHub  [#14221 (comment)],  or unsubscribe  [https://github.com/notifications/unsubscribe-auth/B4YQQUYNLCEM3J26ZWHQKLL43XGBPAVCNFSM6AAAAACYISF3KCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DIOJZHE3DGNJYGM].  Triage notifications on the go with GitHub Mobile for iOS  [https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675]  or Android  [https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub].    You are receiving this because you were mentioned.Message ID: ***@***.***>

[mkllnk]

I've installed Chromium on all production servers. Merging.