fay

Fay

Stateless, Fast and Reliable PDF rendering service.

Dockerhub · Load tests · Contributing

Features

• Fast and reliable due to Playwright.
• Use Chromium 89.0.4344.0.
• Render any URL or static HTML to PDF.
• Sandbox mode with network and javascript disabled.
• Healthcheck endpoint.
• Ready to use docker image.
• Swagger endpoint.

Installation

docker run --rm -p 3000:3000 starptech/fay

The image is relatively big due to the playwright base image. This might be improved in the future. Versioning will be added soon as well.

Endpoints

• /convert - Converts a website to PDF document.
  • filename (form,query, default: "result.pdf"): Filename of the resulting pdf.
  • url (form,query, default: ""): The url of the website to convert.
  • html (file, default: ""): Convert the HTML to PDF instead url.
  • locale (form,query, default: en-US): Browser locale.
  • format (form,query, default: A4): Page format.
  • offline (form,query, default: false): Disable network connectivity.
  • media (form,query, default: print): Page media emulation.
  • javascript (form,query, default: true): Enable javascript on the website.
  • marginTop,marginRight,marginBottom,marginLeft (form,query, default: 0): Set page margin.
  • headerTemplate (file, default: <span></span>): Header template.
  • footerTemplate (file, default: <span></span>): Footer template.
• /ping - Check if the server is ready to accept requests.
• /metrics - Returns informations about the current load and health of the server.
• /swagger/index.html - Swagger introspection

For detail description of the pdf options check the playwright documentation or the swagger documentation.

Environment variables

• FAY_MAX_ACTIVE_PAGES (default: 0): Controls how many pages can be opened at the same time before responding with status code 429.

Scalability

Fay is staless and can be scaled infinitely. If you run fay on your infrastructure you should keep some things in mind. Fay will open as many pages as possible depending on the available host resources. You can control the maximum active pages by the environment variable FAY_MAX_ACTIVE_PAGES=20. As a general thumb you can calculate the base memory consumption in the following way. The chrome instance takes around ~45MB. Every additional page ~15MB. In case of the limit is reached the server will respond with status code 429. The client is responsible to implement a backoff strategy.

A single fay instance (static HTML mode) is capable to serve 20 parallel virtual users with an average request duration of ~0.5s. The memory consumption was ~500MB.

Load tests are part of our CI. For more informations check the load-test.

Best practice

In order to produce reproducible results try to avoid downloading external resources you can't control and executing javascript. Use the options offline=true and javascript=false to enforce that. You can inline images / fonts / styles with base64 in the document. Fonts can also be embedded in the docker image to make them accesible to the chromium browser.

Credits

• https://github.com/mxschmitt/playwright-go
• https://github.com/thecodingmachine/gotenberg
• Elf icon icon by Icons8