Click or drag to resize

The Remote ExpertPdf Engine

The conversion engines normally run on the machine the application runs on, from the ExpertPdf.Anywhere.Native.<rid> package. With ChromiumRemote the application sends that work over HTTP to the ExpertPdf engine instead - a service that ships as the container image ghcr.io/expertpdf-components/engine and runs on another machine, as another container, or beside the application in the same pod.

Every native operation goes to the engine: HTML to PDF and HTML to image (the Chromium engine), and PDF to text and PDF to image (the PDF tool). Everything else stays in the application and works as before: building the document, headers and footers, bookmarks, PDF/A and PDF/UA, security and signatures, Word, Excel and PowerPoint to PDF, redaction, forms - and the license check. The engine itself needs no license.

Use the remote engine to:

  • Run on Alpine Linux and other musl-based systems, where the native engines cannot run. This is the supported way to use the library there.

  • Keep the application small: it references only the ExpertPdf.Anywhere package - no native package and no fonts package.

  • Isolate rendering from the application, scale it separately, or share one engine between several applications.

Quick start

Start the engine with an access token:

docker run -d --name expertpdf-engine -p 8080:8080 \
  --read-only --tmpfs /tmp \
  -e EXPERTPDF_ENGINE_TOKEN="$(openssl rand -base64 32)" \
  ghcr.io/expertpdf-components/engine:22.0

Then point the application at it, once at start-up. The conversion code does not change:

using ExpertPdf.Anywhere;
using ExpertPdf.Anywhere.HtmlToPdf;

GlobalSettings.RenderingEngine = RenderingEngine.ChromiumRemote;
GlobalSettings.EngineEndpoint = "http://localhost:8080";
GlobalSettings.EngineAccessToken = "the token the engine was started with";

PdfConverter pdfConverter = new PdfConverter();
pdfConverter.SavePdfFromUrlToFile("https://www.example.com", "test.pdf");

The same settings can come from environment variables instead, with no code at all - which is how a container deployment usually does it:

EXPERTPDF_RENDERING_ENGINE=ChromiumRemote
EXPERTPDF_ENGINE_ENDPOINT=http://expertpdf-engine:8080
EXPERTPDF_ENGINE_TOKEN=the token the engine was started with
Application settings

Property

Environment variable

Meaning

RenderingEngine

EXPERTPDF_RENDERING_ENGINE

Chromium (the default: the engines run on this machine) or ChromiumRemote. Every converter and HTML element follows it unless its own RenderingEngine property is set, and the PDF tools always follow it.

EngineEndpoint

EXPERTPDF_ENGINE_ENDPOINT

The engine's url. Default http://expertpdf-engine:8080: an engine service named expertpdf-engine on the same Docker network or cluster.

EngineAccessToken

EXPERTPDF_ENGINE_TOKEN

One of the tokens the engine was started with, or none when the engine requires none.

EngineTimeout

EXPERTPDF_ENGINE_TIMEOUT (seconds)

How long one request may take. By default it follows the conversion's own navigation and print timeouts, plus time to wait for a free slot on a busy engine.

A single converter can use the other engine than the global setting through its own RenderingEngine (and the RenderingEngine property of ImgConverter, HtmlToPdfElement, HtmlToImageElement and HtmlToPdfArea).

// this converter uses the remote engine, whatever the global setting is
PdfConverter remoteConverter = new PdfConverter();
remoteConverter.RenderingEngine = RenderingEngine.ChromiumRemote;
byte[] pdf = remoteConverter.GetPdfBytesFromUrl("https://www.example.com");
Running the engine

The image is ghcr.io/expertpdf-components/engine (mirrored on Docker Hub as expertpdf/engine), for x64 and arm64. Use the tag of the library's version - 22.0.0, or 22.0 for its latest build; an engine that does not speak the library's protocol is reported as such. The engine listens on port 8080, runs as a non-root user, works with a read-only file system and a writable /tmp, and needs no extra capabilities. It carries fonts for every language (the Noto family), so it renders every script without a fonts package.

Health:GET /health answers 200 once the engine is ready to convert (the image's own HEALTHCHECK uses it), and 503 before that or when it cannot convert. /healthz answers the same. GET /v1/info (with the token) reports the engine's version, its Chromium version and its limits.

Engine environment variable

Meaning

EXPERTPDF_ENGINE_TOKEN

The access tokens the engine accepts, separated by commas - several at once let a token be rotated without downtime. Each must be at least 32 characters, or the engine does not start; generate one with openssl rand -base64 32. Without a token anyone who can reach the port can use the engine (it logs a warning).

EXPERTPDF_ENGINE_TOKEN_FILE

A file holding the tokens, one per line - a Docker or Kubernetes secret. Instead of EXPERTPDF_ENGINE_TOKEN.

EXPERTPDF_MAX_CONCURRENCY

HTML conversions run at once. Default: the number of CPUs the container has.

EXPERTPDF_MAX_TOOL_CONCURRENCY

PDF to text / image operations run at once. Default: the number of CPUs.

EXPERTPDF_QUEUE_TIMEOUT

Seconds a request waits for a free slot (default 30). After that the engine answers 503, so a retry can reach another replica; the library retries such an answer.

EXPERTPDF_MAX_BODY_MB

The largest request accepted, in MB (default 100).

EXPERTPDF_ENGINE_HTTP_CACHE

The most of the HTTP cache a conversion may keep: clear, thirdParty or all (the default - each conversion keeps what it asks for through HttpCache). Set clear on an engine shared by different callers.

EXPERTPDF_ENGINE_PORT

The port to listen on (default 8080) - change it when the engine runs beside an application that uses 8080 in the same pod.

EXPERTPDF_TEMP_DIR

Where conversions work (default /tmp/expertpdf-engine). Each request has a folder of its own, deleted when it ends.

Docker Compose: name the engine service expertpdf-engine and the application needs no endpoint setting at all:

services:
  expertpdf-engine:
    image: ghcr.io/expertpdf-components/engine:22.0
    read_only: true
    tmpfs:
      - /tmp
    environment:
      EXPERTPDF_ENGINE_TOKEN: ${EXPERTPDF_ENGINE_TOKEN}
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      EXPERTPDF_RENDERING_ENGINE: ChromiumRemote
      EXPERTPDF_ENGINE_TOKEN: ${EXPERTPDF_ENGINE_TOKEN}
    depends_on:
      expertpdf-engine:
        condition: service_healthy

In Kubernetes, run the engine as a Deployment behind a Service named expertpdf-engine, with /health as its readiness and liveness probe and the token in a Secret; from another namespace use http://expertpdf-engine.<namespace>.svc.cluster.local:8080.

Security
  • Use a token and keep the engine off the public internet - on the Docker network, the cluster network or a private subnet of the application.

  • The token is never sent in clear text to another network. With a token set, the library requires an https endpoint unless the endpoint is a local one: a service name without a dot, localhost, a loopback or a private address. The engine itself serves plain HTTP; for an engine on another machine, put TLS in front of it (an ingress, a load balancer or a reverse proxy).

  • A page cannot read the engine's files: local file access is always off in the engine, whatever a conversion asks for.

  • The engine fetches what the pages reference, from its own network. When it converts html you do not control, limit where the engine's network can reach (internal services, cloud metadata addresses).

  • A shared engine: set EXPERTPDF_ENGINE_HTTP_CACHE=clear, so no conversion is served a response another caller's conversion fetched. Cookies and storage are cleared after every conversion in any case.

What is different from a local engine
  • Local files: the engine cannot see the application's files, so a file:// url or base url is refused before anything is sent. Convert the html as a string, or serve the files over http. Local files an html string references - images, stylesheets, fonts and media - are sent with it, so they are drawn as a local engine draws them (not when local file access is denied, as locally).

  • localhost in a url means the engine's own machine, not the application's - except when the engine runs in the application's pod or on its host network. Use an address the engine can reach, such as the application's service name.

  • Fonts in the application's own fonts folder are sent to the engine with each conversion.

  • Per-conversion settings that a local in-process engine fixes for the whole process - WebGL, a proxy, insecure content - are honoured per conversion. A proxy must be reachable from the engine.

  • Errors are the same exception types as locally. When the engine itself could not be reached or refused the request, the message says so and names the request id the engine logs its runs under.

  • Logging: with a log file set (LogFile), the engine's own log of the conversion is appended to it.

  • Cancellation: cancelling an awaited conversion cancels it in the engine.

See Also