Rendering Backends

WebKitGTK is a Linux rendering engine. CobaltPDF.WebKit therefore always renders on Linux — the question is only which Linux, and the library answers it automatically.

Selection order

Host	Backend	Notes
Linux (Azure, AKS, ECS, any container/VM)	Inline — native, in-process	Always. Dev-only force flags are ignored on Linux by design.
Windows with WSL 2	WSL	Preferred dev backend — near-native speed, pooled warm workers.
Windows/macOS with Docker	Docker	Used when WSL is unavailable, or when forced. One-shot renders against the public dev image.
Neither available	Actionable error — or stub mode if opted in.

With logging enabled the choice is stated once per process:

CobaltPDF.WebKit: render backend = inline (native Linux — no WSL, no Docker)

Linux: inline (production)

On Linux the engine runs in-process against the auto-provisioned render bundle. Workers are pooled and recycled (see Configuration); there is nothing to install and no container requirement. This path is deliberately unconditional — ForceWsl / ForceDocker are dev-machine switches and have no effect on Linux, so configuration written on a dev box can ship to production unchanged.

Windows: WSL 2 (preferred for development)

The library uses your default WSL distro (or PoolOptions.WslDistribution to pick one), installs the bundle into it on first render, and keeps pooled warm workers there. Any glibc ≥ 2.35 distro works — Ubuntu 22.04/24.04, Debian 12+:

wsl --install Ubuntu-24.04

A one-time probe selects the right bundle variant for the distro's glibc and surfaces a clear error if the distro is too old (PoolOptions.SkipWslDependencyCheck skips it).

Windows / macOS: Docker fallback

When WSL isn't available the engine renders through Docker using the public multi-arch dev image (ghcr.io/cobaltpdf/cobalt-webkit-render — runs on Intel and Apple-Silicon). Force it explicitly on a machine that has both:

CobaltEngine.Configure(o => o.ForceDocker = true);   // or COBALT_FORCE_DOCKER=1

Docker renders are one-shot (no pooled workers) — fine for development, not a production path. Production is native Linux.

Stub mode (opt-in, tests only)

CobaltEngine.Configure(o => o.StubModeOnWindows = true);

On a non-Linux host without WSL or Docker, returns a clearly-marked placeholder PDF instead of rendering — so controller/integration tests can run anywhere. Off by default in every build configuration; on Linux it has no effect.

Forcing a backend (dev machines only)

Switch	Effect
PoolOptions.PreferWsl (default true)	Prefer WSL when both WSL and Docker exist
PoolOptions.ForceWsl / COBALT_FORCE_WSL=1	Require WSL, fail fast without it
PoolOptions.ForceDocker / COBALT_FORCE_DOCKER=1	Require Docker
PoolOptions.StubModeOnWindows	Placeholder PDFs when no backend exists

All four are ignored on Linux — a Linux deployment always renders inline.