Deployment

This article walks through deploying on each supported cloud and container platform — for both engines. Every platform section below has two tabs:

CobaltPdf (Chromium) — ships Chromium in the NuGet package. Chromium depends on system libraries (libglib, libnss3, the GTK/X11 stack), so Linux deployments need those libraries present — which on some platforms means deploying as a custom container.
CobaltPDF.WebKit — downloads a fully self-contained WebKit bundle at first start (everything except glibc is included). No system libraries to install, so it runs on stock platforms — including code-only Azure Functions and App Service Linux plans — with no container required. See the WebKit edition overview and the dedicated WebKit docs.

Pick your engine tab once — every section on this page follows it.

Tip

If you are building a PDF microservice that accepts JSON payloads from other applications, see HTTP Requests for the PdfRequest / PdfResponse model. The same wire model works against either engine, so clients never need to know which one the service runs.

Choosing an engine for deployment

	CobaltPdf (Chromium)	CobaltPDF.WebKit
Linux system libraries	Required (apt/yum packages)	None — bundle is self-contained
Stock (code-only) Azure Functions Linux	❌ Not possible — must use a custom container	✅ Works — zip deploy
Stock Azure App Service Linux	⚠ Depends on image; container recommended	✅ Works — zip deploy
Docker	✅ Custom image with system packages	✅ Any glibc ≥ 2.35 base image, no packages
Deployment artifact size	~460 MB (Chromium ships in the package)	~3 MB (bundle downloads at first start, ~262 MB, cached)
Typical memory per instance	1.5–2.5 GB peak	0.3–1.3 GB peak
Windows servers / containers	✅ Native	Dev-only (WSL2 / Docker); production targets Linux

Warning

A code-only (zip) deployment to a Linux Functions plan does not work for Chromium. Azure's stock Functions image does not contain Chromium's system libraries and they cannot be installed on a stock plan. The browser fails to launch with: error while loading shared libraries: libglib-2.0.so.0: cannot open shared object file. Deploy as a custom container instead (steps below). The Consumption plan is not supported either way — use Premium (EP1 or higher) or a Dedicated plan with at least 3.5 GB memory (1.75 GB B1 instances are below Chromium's floor and OOM under load).

1. Configure the function app in Program.cs:

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        services.AddCobaltPdf(o =>
        {
            CloudEnvironment.ConfigureForAzure(o);
        });
    })
    .Build();

CobaltEngine.SetLicense(Environment.GetEnvironmentVariable("COBALTPDF_LICENSE")!);
await CobaltEngine.PreWarmAsync();

await host.RunAsync();

2. Publish — without -r or --self-contained (both flatten the runtimes/ folder and break Chromium.Path resolution):

dotnet publish -c Release -o ./publish

3. Dockerfile — the Functions base image plus Chromium's system libraries:

FROM mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated8.0
ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
    AzureFunctionsJobHost__Logging__Console__IsEnabled=true

RUN apt-get update && apt-get install -y --no-install-recommends \
    libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libatspi2.0-0 libx11-6 \
    libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
    libgbm1 libpango-1.0-0 libcairo2 libasound2 \
    fonts-liberation fonts-dejavu-core \
    && rm -rf /var/lib/apt/lists/*

COPY ./publish /home/site/wwwroot

4. Build, push to a registry, and create the container-based function app:

az acr create -n myacr -g myRG --sku Basic --admin-enabled true
az acr login -n myacr

docker build -t myacr.azurecr.io/pdf-func:1 .
docker push myacr.azurecr.io/pdf-func:1

az functionapp create -n my-pdf-func -g myRG \
    --plan my-premium-plan --storage-account mystorage \
    --functions-version 4 --os-type Linux \
    --image myacr.azurecr.io/pdf-func:1 \
    --registry-server https://myacr.azurecr.io \
    --registry-username myacr --registry-password "$(az acr credential show -n myacr --query 'passwords[0].value' -o tsv)"

az functionapp config appsettings set -n my-pdf-func -g myRG \
    --settings COBALTPDF_LICENSE="YOUR-LICENSE-KEY"

Note

A code-only (zip) deployment to a stock Linux Functions plan works. No container, no registry, no system packages. The library downloads its self-contained render bundle (~262 MB) on each instance's first start and caches it. B2 (3.5 GB) is the recommended minimum for production — it gives one warm worker real headroom above the ~300–400 MB a typical render peaks at, so image-rich pages render without memory pressure. The classic Consumption plan is not supported (its writable temp disk is smaller than the extracted bundle, and it can't keep the pool warm).

Warning

B1 (1.75 GB) is only for light, self-contained HTML you control (invoices, receipts, statements). Heavy or image-rich third-party pages can exceed its memory and get OOM-killed mid-render — the worker dies and the response is a bare HTTP 500 with no body. Use B2 (3.5 GB), or B3 (7 GB) for very large pages. B1's single burstable core also makes renders slow; for lower per-render latency choose Premium v3 (Pv3) — its dedicated cores are far quicker than the burstable Basic core.

1. Configure the function app in Program.cs:

using CobaltPdf.WebKit;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .Build();

CobaltEngine.SetLicense(Environment.GetEnvironmentVariable("COBALTPDF_LICENSE")!);
CobaltEngine.Configure(o =>
{
    o.MinSize = 1;
    o.MaxSize = 1;                                    // 1 on B2 (3.5 GB); 2 on B3/EP2 (7 GB)
    o.MaxMemoryMb = 2048;                             // clean error instead of OOM-kill
    o.BrowserLeaseTimeout = TimeSpan.FromSeconds(180); // queued requests outlive a slow render
});

// Downloads + extracts the bundle and warms a render worker off the request path.
_ = Task.Run(() => CobaltEngine.PreWarmAsync());

host.Run();

2. App settings — one is critical:

az functionapp config appsettings set -n my-pdf-func -g myRG --settings \
    COBALT_BUNDLE_CACHE_DIR=/tmp/cobaltbundle \
    COBALTPDF_LICENSE="YOUR-LICENSE-KEY" \
    SCM_DO_BUILD_DURING_DEPLOYMENT=false ENABLE_ORYX_BUILD=false

Important

COBALT_BUNDLE_CACHE_DIR=/tmp/cobaltbundle keeps the bundle on the instance's local disk. Without it, the cache lands on /home — an Azure Files network share where extracting thousands of files takes 10–100× longer and the first render times out.

3. Publish and deploy — a plain zip, ~3 MB:

dotnet publish -c Release -o ./publish
func azure functionapp publish my-pdf-func
# or: zip the publish folder and `az functionapp deployment source config-zip`

Note

First start per instance: ~40 s download + ~90 s extract, performed by PreWarmAsync off the request path. Outbound HTTPS to github.com and release-assets.githubusercontent.com must be allowed (relevant for VNet-locked apps — or self-host the bundle with COBALT_BUNDLE_BASE_URL). Subsequent renders touch the network not at all.

Azure App Service (Linux)

CobaltPdf (Chromium)
CobaltPDF.WebKit

App Service Linux code-only deployments run on Azure's stock runtime image. Like the Functions image, it may not include all of Chromium's system libraries.

Warning

If your app fails its first render with error while loading shared libraries: …, the stock image is missing Chromium's dependencies and you should deploy as a custom container instead — use the Docker steps below with az webapp create --deployment-container-image-name.

Use the Azure preset either way:

CobaltEngine.Configure(CloudEnvironment.ConfigureForAzure);

Code-only attempt (works only if the stock image carries the libraries):

dotnet publish -c Release -o ./publish
az webapp deploy --resource-group myRG --name myApp --src-path ./publish --type zip
az webapp config appsettings set -g myRG -n myApp --settings COBALTPDF_LICENSE="YOUR-LICENSE-KEY"

Code-only zip deployment works on stock App Service Linux — same model as Azure Functions:

dotnet publish -c Release -o ./publish
az webapp deploy --resource-group myRG --name myApp --src-path ./publish --type zip

az webapp config appsettings set -g myRG -n myApp --settings \
    COBALT_BUNDLE_CACHE_DIR=/tmp/cobaltbundle \
    COBALTPDF_LICENSE="YOUR-LICENSE-KEY"

Call CobaltEngine.PreWarmAsync() at startup so the one-time bundle provisioning happens before traffic. The /tmp cache-dir setting matters here for the same reason as on Functions: /home is a slow network share. As with Functions, B2 (3.5 GB) is the recommended minimum — B1 can OOM on heavy or image-rich pages.

Docker

CobaltPdf (Chromium)
CobaltPDF.WebKit

Use a multi-stage Dockerfile; the runtime stage installs Chromium's system libraries.

# ── Build stage ─────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY MyApp.csproj ./
RUN dotnet restore MyApp.csproj
COPY . .
RUN dotnet build MyApp.csproj -c Release --no-restore -o /app/publish

# ── Runtime stage ──────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime

RUN apt-get update && apt-get install -y --no-install-recommends \
    libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libatspi2.0-0 \
    libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 \
    libpango-1.0-0 libcairo2 libasound2 libxshmfence1 libx11-xcb1 \
    libxss1 libxtst6 \
    fonts-liberation fonts-noto-color-emoji \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Warning

The build stage uses dotnet build without the -r or --self-contained flags. Both flatten the runtimes/{rid}/native/ folder into the output root, which breaks Chromium.Path resolution. If Chromium.Path returns null at runtime, this is the most likely cause.

Configure with the Docker preset, and give Chromium shared memory in compose:

CobaltEngine.Configure(o =>
{
    CloudEnvironment.ConfigureForDocker(o);
});

services:
  myapp:
    build: { context: ., dockerfile: Dockerfile }
    shm_size: '1gb'          # required — Chromium needs shared memory
    environment:
      - COBALTPDF_LICENSE=YOUR-LICENSE-KEY
    ports:
      - "8080:8080"

Important

shm_size is required. Docker defaults to 64 MB of shared memory, which causes Chromium to crash under load. Set at least 256mb (recommended 1gb).

No system packages and no shm_size — the bundle is self-contained. The only requirement is a base image with glibc ≥ 2.35: mcr.microsoft.com/dotnet/aspnet:8.0 (Debian 12) and any Ubuntu 22.04+/24.04+ base qualify.

# ── Build stage ─────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY MyApp.csproj ./
RUN dotnet restore MyApp.csproj
COPY . .
RUN dotnet publish MyApp.csproj -c Release --no-restore -o /app/publish

# ── Runtime stage — no apt packages needed ─────────────────────
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .

# Optional but recommended: pre-stage the render-bundle tarball at image-build
# time so containers skip the ~262 MB first-start download (the library
# SHA-256-verifies the file and goes straight to extraction).
ENV COBALT_BUNDLE_CACHE_DIR=/opt/cobalt-bundle
ADD https://github.com/CobaltPDF/cobalt-webkit-bundles/releases/download/v1.0.0/cobalt-webkit-bundle-linux-x64-glibc-u2204.tar.gz \
    /opt/cobalt-bundle/cobalt-webkit-bundle-linux-x64-glibc-u2204-v1.0.0.tar.gz

ENTRYPOINT ["dotnet", "MyApp.dll"]

Note

Pick the bundle variant by your base image's glibc: u2204 for glibc ≥ 2.35 (Debian 12, Ubuntu 22.04) or u2404 for glibc ≥ 2.38 (Ubuntu 24.04 / noble images). Skip the ADD lines entirely and the bundle simply downloads on first start instead.

services:
  myapp:
    build: { context: ., dockerfile: Dockerfile }
    environment:
      - COBALTPDF_LICENSE=YOUR-LICENSE-KEY
    ports:
      - "8080:8080"

No engine preset is needed — on Linux the WebKit edition always renders natively in-process (ExtraArgs Chromium flags are accepted for API compatibility and ignored).

Azure Container Apps

CobaltPdf (Chromium)
CobaltPDF.WebKit

Container Apps runs standard Docker containers — use the Docker image above with the Docker preset. Give each replica at least 2 Gi memory (4 Gi for production). Scale on HTTP concurrency, not instance count, so the browser pool is shared within each replica.

AWS ECS / Fargate

CobaltPdf (Chromium)
CobaltPDF.WebKit

Use the ECS preset, which omits --single-process for better stability under sustained load:

CobaltEngine.Configure(CloudEnvironment.ConfigureForAwsEcs);

Resource	Minimum	Recommended
vCPU	0.5	1.0
Memory	1 GB	2 GB
`/dev/shm`	—	`linuxParameters.sharedMemorySize: 256`

Build with the Docker steps above, push to ECR, set the license key via task environment variables or AWS Secrets Manager.

Any Linux container with glibc ≥ 2.35 works — use the WebKit Docker image above, push to ECR. No shared-memory setting needed.

Resource	Minimum	Recommended
vCPU	0.5	1.0
Memory	1 GB	1–2 GB

AWS Lambda

CobaltPdf (Chromium)
CobaltPDF.WebKit

Warning

Lambda imposes a 512 MB /tmp default and browser-pool persistence across invocations is not guaranteed. For high-volume PDF generation prefer ECS or App Runner.

Use the low-memory preset (MaxSize = 1, --single-process) and a custom container image:

CobaltEngine.Configure(CloudEnvironment.ConfigureForLowMemory);

FROM public.ecr.aws/lambda/dotnet:8 AS base
RUN yum install -y \
    glib2 nss atk at-spi2-atk cups-libs \
    libdrm libxkbcommon libXcomposite libXdamage \
    libXfixes libXrandr mesa-libgbm alsa-lib \
    && yum clean all
WORKDIR /var/task
COPY ./publish .
CMD ["MyApp::MyApp.LambdaEntryPoint::FunctionHandlerAsync"]

Recommended: 2048 MB memory, 60 s timeout, x86_64.

Linux VM / Bare Metal

CobaltPdf (Chromium)
CobaltPDF.WebKit

Use the Linux preset and install Chromium's system libraries:

CobaltEngine.Configure(CloudEnvironment.ConfigureForLinux);

# Debian / Ubuntu
sudo apt-get install -y \
    libglib2.0-0 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
    libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
    libxfixes3 libxrandr2 libgbm1 libasound2

# RHEL / Amazon Linux 2023
sudo yum install -y \
    glib2 nss atk at-spi2-atk cups-libs libdrm \
    libxkbcommon libXcomposite libXdamage \
    libXfixes libXrandr mesa-libgbm alsa-lib

Nothing to install — any x64 distro with glibc ≥ 2.35 (Ubuntu 22.04+, Debian 12+, Fedora 39+) runs the self-contained bundle out of the box:

dotnet publish -c Release -o ./publish
COBALTPDF_LICENSE="YOUR-LICENSE-KEY" dotnet ./publish/MyApp.dll

The bundle downloads to ~/.cache/CobaltPdfWebKit on first render (override with COBALT_BUNDLE_CACHE_DIR). Air-gapped hosts can pre-stage the tarball or self-host it via COBALT_BUNDLE_BASE_URL.

Windows development machines

CobaltPdf (Chromium)
CobaltPDF.WebKit

Works natively — no preset, no extra setup. The bundled Windows Chromium binary is used automatically, on dev machines and Windows servers/containers alike.

WebKitGTK is a Linux engine, so on Windows the library renders through a local Linux backend — automatically selected, in this order:

WSL 2 (preferred — near-native speed). Any distro with glibc ≥ 2.35; the bundle installs into the distro automatically. wsl --install Ubuntu-24.04 if you have none.
Docker Desktop — used when WSL isn't available (ForceDocker = true to require it). Pulls the public dev image ghcr.io/cobaltpdf/cobalt-webkit-render.
Stub mode (StubModeOnWindows = true, opt-in) — returns placeholder PDFs so controller/integration tests run with no backend at all.

These switches are dev-only: on Linux deployments they are ignored and rendering is always native in-process, so dev configuration can ship to production unchanged.

CI/CD Tips

CobaltPdf (Chromium)
CobaltPDF.WebKit

- name: Install Chromium dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y libglib2.0-0 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
      libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
      libxfixes3 libxrandr2 libgbm1 libasound2

- name: Publish
  run: dotnet publish -c Release -o ./publish

# No system packages needed — ubuntu-latest runners satisfy the glibc floor.
- name: Publish
  run: dotnet publish -c Release -o ./publish

# Integration tests render for real; the bundle downloads once per runner
# (cache COBALT_BUNDLE_CACHE_DIR between runs to skip it).
- name: Cache render bundle
  uses: actions/cache@v4
  with:
    path: ~/.cache/CobaltPdfWebKit
    key: cobalt-webkit-bundle-v1

Store the license key in a CI secret for either engine:

env:
  COBALTPDF_LICENSE: ${{ secrets.COBALTPDF_LICENSE }}

CobaltEngine.SetLicense(Environment.GetEnvironmentVariable("COBALTPDF_LICENSE")!);

Platform Summary

CobaltPdf (Chromium)
CobaltPDF.WebKit

Platform	Preset	Notes
Windows (local / IIS)	(none needed)	Chromium sandbox works natively
Linux VM / bare metal	`ConfigureForLinux`	Install system libs
Docker	`ConfigureForDocker`	Include apt deps in `Dockerfile`; `shm_size ≥ 256mb`
Azure App Service (Linux)	`ConfigureForAzure`	Custom container recommended
Azure Functions (Linux)	`ConfigureForAzure`	Custom container required; EP1+ / ≥ 3.5 GB
Azure Container Apps	`ConfigureForDocker`	≥ 2 Gi memory per replica
AWS ECS / Fargate	`ConfigureForAwsEcs`	`sharedMemorySize ≥ 256 MB`
AWS Lambda	`ConfigureForLowMemory`	Custom container; pool may restart per cold start

Platform	Key setting	Notes
Windows (development)	(none — auto WSL/Docker)	Production targets Linux
Linux VM / bare metal	(none)	glibc ≥ 2.35; zero packages
Docker	optional pre-staged tarball	No apt deps, no `shm_size`
Azure App Service (Linux)	`COBALT_BUNDLE_CACHE_DIR=/tmp/...`	Stock plan, zip deploy
Azure Functions (Linux)	`COBALT_BUNDLE_CACHE_DIR=/tmp/...`	Stock plan, zip deploy; B2 (3.5 GB) min, B3/EP1+/Pv3 for heavy pages & latency
Azure Container Apps	pre-staged tarball	≥ 1 Gi memory per replica
AWS ECS / Fargate	(none)	Standard Linux container
AWS Lambda	ephemeral storage ≥ 1 GB	Untested guidance — prefer ECS

Table of Contents

Deployment

Tip

Choosing an engine for deployment

Azure Functions (Linux)

Warning

Azure App Service (Linux)

Warning

Docker

Warning

Important

Azure Container Apps

AWS ECS / Fargate

AWS Lambda

Warning

Linux VM / Bare Metal

Windows development machines

CI/CD Tips

Platform Summary