Docker Guide — EggPdf

Quick Start

Pull and run the latest EggPdf image. The REST API and WebUI start immediately on port 8080.

docker run -p 8080:8080 eggspot/eggpdf:latest

The image is also available from the GitHub Container Registry:

docker run -p 8080:8080 ghcr.io/eggspot/eggpdf:latest

✅

Once the container starts, open http://localhost:8080 in your browser to access the WebUI.

Test the API

Send an HTML string to POST /api/render and receive a PDF in the response body:

bash

curl -X POST http://localhost:8080/api/render \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello from EggPdf</h1><p>Rendered in Docker.</p>"}' \
  --output hello.pdf

You can also pass render options:

curl -X POST http://localhost:8080/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>My Report</h1>",
    "options": {
      "pageSize": "A4",
      "title": "My Report",
      "footer": "Page {page} of {pages}"
    }
  }' \
  --output report.pdf

Built-in WebUI

The Docker image ships with a full-featured WebUI at http://localhost:8080:

HTML Editor — write or paste HTML with live preview
PDF Preview — see the rendered PDF in real time
E2E Comparison — side-by-side browser vs PDF view at /e2e
Download — export the PDF directly from the browser

ℹ️

Disable the WebUI in production by setting WEBUI_ENABLED=false.

Docker Compose

docker-compose.yml

version: "3.9"

services:
  eggpdf:
    image: eggspot/eggpdf:latest
    ports:
      - "8080:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - AUTH_ENABLED=false
      - WEBUI_ENABLED=true
    volumes:
      - ./fonts:/app/fonts:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 256M

Environment Variables

Variable	Default	Description
`ASPNETCORE_ENVIRONMENT`	`Production`	ASP.NET Core environment name. Use `Development` for detailed error pages.
`ASPNETCORE_URLS`	`http://+:8080`	Listening address. Override to change the port.
`AUTH_ENABLED`	`false`	Set to `true` to require an API key header (`X-Api-Key`).
`AUTH_API_KEY`	—	The API key value when `AUTH_ENABLED=true`.
`WEBUI_ENABLED`	`true`	Set to `false` to disable the WebUI and serve API only.

Volume Mounts

Mount a directory containing custom .ttf or .otf font files into /app/fonts. EggPdf will discover and use them automatically:

docker run -p 8080:8080 \
  -v /path/to/your/fonts:/app/fonts:ro \
  eggspot/eggpdf:latest

Health Check

The service exposes a health endpoint that returns 200 OK with a JSON payload:

curl http://localhost:8080/health
# {"status":"Healthy","version":"0.3.0"}

Use this with container orchestrators (Kubernetes, ECS, Docker Swarm) for liveness and readiness probes.

Using CLI Inside the Container

The CLI is bundled inside the Docker image. You can use it without installing anything locally:

# Convert a local HTML file to PDF (mount current directory)
docker run --rm \
  -v "$(pwd):/work" \
  eggspot/eggpdf:latest \
  dotnet /app/cli/EggPdf.Cli.dll /work/input.html -o /work/output.pdf

Multi-arch Support

The eggspot/eggpdf:latest image is a multi-arch manifest that supports:

linux/amd64 — standard x86-64 servers and desktops
linux/arm64 — AWS Graviton, Apple Silicon in Docker, Raspberry Pi 4+

Docker automatically selects the correct image for your host architecture. No flags required.

Production Tips

Resource limits

EggPdf is CPU-bound. For most workloads, limit to 1 CPU and 256 MB RAM. For high-throughput invoice generation, consider horizontal scaling behind a load balancer rather than increasing single-container resources.

docker run -p 8080:8080 \
  --cpus="1.0" \
  --memory="256m" \
  eggspot/eggpdf:latest

Non-root user

The image runs as a non-root user (appuser, UID 1001) by default. No additional configuration required for least-privilege deployments.

Disable the WebUI

docker run -p 8080:8080 \
  -e WEBUI_ENABLED=false \
  eggspot/eggpdf:latest

Enable authentication

docker run -p 8080:8080 \
  -e AUTH_ENABLED=true \
  -e AUTH_API_KEY=my-secret-key \
  eggspot/eggpdf:latest

# Then include the key in requests:
curl -X POST http://localhost:8080/api/render \
  -H "X-Api-Key: my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Secure PDF</h1>"}' \
  --output secure.pdf