Quickstart

You do not need to build anything to try PDF Server: prebuilt images are published to the GitLab Container Registry. Pull one, point it at a directory of templates, and POST some JSON.

latest-* tracks the master branch; released versions are tagged vX.Y.Z-chromium / vX.Y.Z-firefox — pin one in production.

Render a PDF in one minute

Create a one-file template and run the image against it. The image serves templates from /src/templates, so we bind-mount a local directory there — no image build required.

mkdir -p templates/hello
cat > templates/hello/template.mustache <<'EOF'
<h1>Hello, {{name}}!</h1>
<p>Rendered by PDF Server.</p>
EOF

docker run --rm -p 9999:9999 \
  -v "$PWD/templates:/src/templates" \
  registry.gitlab.com/c0va23/pdf-server:latest-chromium

On startup the server loads and validates every template, then prints the URL of its debug tools (the tester UI and API spec viewers):

Debug tools (Tester UI, Swagger UI and etc.): http://[::]:9999/

In another terminal, render the template with your data:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"name": "world"}' \
  http://localhost:9999/templates/hello/render > hello.pdf

xdg-open hello.pdf   # Linux
open hello.pdf       # macOS

You get back an application/pdf response — a one-page PDF of the rendered template. Open http://localhost:9999/ for the interactive tester UI.

Chromium sandbox. The images already pass --no-sandbox to the browser, so a plain docker run works. On hardened hosts you may additionally need --security-opt seccomp=unconfined.

Explore the bundled examples

The repository ships a set of example templates (the same ones shown in the Gallery). Clone the repo and bind-mount them to try every engine, compositions, headers/footers, assets, and partials:

git clone https://gitlab.com/c0va23/pdf-server.git
docker run --rm -p 9999:9999 \
  -v "$PWD/pdf-server/examples/templates:/src/templates" \
  registry.gitlab.com/c0va23/pdf-server:latest-chromium

Templates that ship example datasets can be rendered with a GET:

# List everything the server exposes:
curl http://localhost:9999/spec/swagger.json | jq '.paths | keys'

# Render a named example dataset:
curl http://localhost:9999/templates/examples_template/examples/alice > alice.pdf

Ship it as your own image

Bind-mounting is great for local iteration; for deployment you bake the templates into your own image on top of the base image — one FROM, one COPY:

# Dockerfile
FROM registry.gitlab.com/c0va23/pdf-server:latest-chromium
COPY templates /src/templates

docker build -t my-pdf-service .
docker run --rm -p 9999:9999 my-pdf-service

That is the whole deployment model — see Build your image for the full walkthrough.

Local development (from source)

If you have the repository and a local Go toolchain + Chromium:

# Hot-reloading dev server on :9999 against ./examples, with the tester UI:
make -j=2 dev.run

This runs with --templates-reload-mode=always, so edits to template files take effect on the next request without a restart.

What next

• Explore the Gallery to see every example rendered as a real PDF.
• Learn the template author workflow.
• Read the HTTP API reference.