A tiny, self-contained Spring Boot service that turns HTML into PDF — including PDF/A (PDF/A-1a, 1b, 2a, 2b, 2u, 3a, 3b, 3u). Push HTML (and the images, SVG charts, stylesheets and fonts it cites), get the PDF binary back. No external services, no configuration required, no network access unless you allow it, fonts bundled for offline generation of exotic scripts (Vietnamese, Hebrew, Arabic, Thai, Devanagari, Japanese/CJK…).
POST your HTML ──► pdfbox ──► PDF/A binary
📖 Full documentation: https://softwarity.github.io/pdfbox/ — getting started, the API & endpoints, PDF/A standards, fonts & scripts, configuration, Docker (amd64 / arm64) and a Kubernetes (Helm) guide.
Real output of the service: every page of each PDF, at the same scale. Each example is
an HTML file rendered by the test suite (ShowcaseTest), which also
checks the page sizes and the PDF/A conformance (veraPDF). More, with their sources, on the
Examples page.
Portrait and landscape in one document — a named page (page: wide + @page wide { size: A4 landscape })
(PDF · HTML)
Page sizes — A4, A5, A3 landscape, US Letter, US Legal landscape and a custom 85 × 55 mm card, in one PDF (PDF · HTML)
Headers, footers and page numbers — running header, Page n / total, no header on the cover (PDF/A-3a)
(PDF · HTML)
Long table across landscape pages — header row repeated on every page, rows never split (PDF · HTML)
Mixing page sizes: blocks are laid out against the width of the default page. Give the block that lands on a wider or narrower named page an explicit
width(that page's width minus its margins, e.g.width: 267mmfor A4 landscape with 15 mm margins). A document that is landscape throughout only needs@page { size: A4 landscape }.
To regenerate the images after a rendering change: mvn test -Dtest=ShowcaseTest -Dshowcase.write=true.
docker run --rm -p 8080:8080 softwarity/pdfbox:latestThen open http://localhost:8080 for a small test page, or call the API directly:
# PDF/A-1b (default) — HTML in the request body, standard as a query param
curl -X POST "http://localhost:8080/api/v1/pdf?standard=PDF_A_1B" \
-H "Content-Type: text/html" \
--data '<h1>Hello</h1><p>Tiếng Việt · עברית · 日本語</p>' \
-o document.pdfThat is the whole contract: send HTML, pick a standard, receive application/pdf.
Requires JDK 25.
mvn spring-boot:run # run from sources
# or
mvn package && java -jar target/pdfbox.jarA broad Noto font set is bundled inside the jar, so multi-script rendering works offline the same way whether you run the jar, the IDE, or the Docker image — no system fonts required.
| Method & path | Description |
|---|---|
POST /api/v1/pdf |
Body = HTML, or multipart/form-data (see below). Query params: standard (see below, default PDF_A_1B), filename (default document.pdf), onMissingResource (fail default, or report). Returns application/pdf. |
POST /api/v1/pdf/upload |
multipart/form-data: file = the HTML, resources = files it cites (repeatable), plus standard, filename, onMissingResource. Same as the multipart form of /pdf. This is the form Swagger UI shows with file pickers. |
GET /api/v1/standards |
Lists the supported standards. |
GET /api/v1/pdf-info |
Query param standard. Returns a PDF, conforming to that standard, that documents the constraints the standard enforces — a self-describing reference page and end-to-end check. |
GET /v3/api-docs |
OpenAPI 3 description (JSON). |
GET /swagger-ui.html |
Interactive Swagger UI — dev profile only (see below). |
GET /actuator/health |
Health probe. |
GET / |
Browser test page. |
Supported standard values: NONE, PDF_A_1A, PDF_A_1B, PDF_A_2A, PDF_A_2B, PDF_A_2U,
PDF_A_3A, PDF_A_3B, PDF_A_3U, and PDF_UA_1 (accessible PDF/UA-1, without the PDF/A archiving
constraints).
# Upload an HTML file (no JavaScript — it is not executed) and get a PDF/A-2b back:
curl -X POST "http://localhost:8080/api/v1/pdf/upload" \
-F "file=@invoice.html;type=text/html" \
-F "standard=PDF_A_2B" \
-o invoice.pdfSend the HTML as the file part and every file it cites as a resources part — stylesheets
(.css), images (.png, .jpg/.jpeg, .gif, .webp, .svg) and TrueType fonts (.ttf), plus
the files to embed in the PDF (.xml, .json, .csv, .txt, .pdf — see
Embedded files). The HTML cites them by their plain file
name; the part's file name is what counts:
<link rel="stylesheet" href="page.css">
<style>@font-face { font-family: Logo; src: url(logo-font.ttf) }</style>
<img src="sigwx.svg" alt="Significant weather"> <img src="wind.png" alt="Winds aloft">curl -X POST "http://localhost:8080/api/v1/pdf?standard=PDF_A_2U" \
-F "file=@briefing.html;type=text/html" \
-F "resources=@page.css" \
-F "resources=@sigwx.svg" \
-F "resources=@wind.png" \
-F "resources=@logo-font.ttf" \
-o briefing.pdfAttached files live for that request only. They are never copied as a whole: each one is read when
the renderer needs it. By default they stay in memory and nothing is written to disk; set
PDFBOX_UPLOAD_MEMORY_THRESHOLD to send larger parts to a temporary file (deleted at the end of the
request) when RAM is tighter than disk. A name with /, \,
.. or a control character, a duplicate name, an unknown part or a file whose content does not match
its type is a 400; above PDFBOX_UPLOAD_MAX_PART_SIZE / PDFBOX_UPLOAD_MAX_TOTAL_SIZE it is a
413. WebP is converted to PNG (PDF cannot carry WebP). A request with only file behaves exactly
as before.
A link with a download attribute embeds the file it points to in the PDF (an attached file or a
data: URI), shown as a paperclip annotation where the link is:
<a href="factur-x.xml" download="factur-x.xml" title="Structured invoice">Invoice data (XML)</a>| Attribute | Becomes |
|---|---|
download |
the embedded file name |
title |
its description |
relationship |
its PDF/A-3 relationship: Source, Data, Alternative, Supplement or Unspecified (the default) |
data-content-type |
its MIME type (default: from the extension — .xml → text/xml, .csv → text/csv…) |
Embedding is allowed in PDF/A-3 (PDF_A_3A/3B/3U), PDF_UA_1 and NONE. PDF/A-1 forbids
embedded files and PDF/A-2 only allows PDF/A documents, so there the link is refused like any other
unresolvable resource: a 422, or the X-Pdfbox-Unresolved-* headers with
onMissingResource=report. Every embedded file is associated with the document (catalog /AF) and
listed in the EmbeddedFiles name tree, where viewers and invoice tools look for it.
Factur-X / ZUGFeRD / XRechnung. In PDF/A-3, an embedded file named factur-x.xml (or
xrechnung.xml) is a hybrid invoice: the service reads its profile from
GuidelineSpecifiedDocumentContextParameter/ID (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED,
XRECHNUNG) and declares it in the XMP metadata (fx:DocumentType, fx:DocumentFileName,
fx:Version, fx:ConformanceLevel, with the PDF/A extension schema). The relationship defaults to
Data for MINIMUM / BASIC WL and Alternative otherwise; set relationship to override it. A
factur-x.xml without a known profile is a 400. The XML itself is embedded as is — validate it
against the Factur-X schematron on your side.
curl -X POST "http://localhost:8080/api/v1/pdf?standard=PDF_A_3B" \
-F "file=@invoice.html;type=text/html" \
-F "resources=@factur-x.xml" \
-o invoice.pdfEverything the document cites — stylesheets, @font-face, images, SVG files and the references inside
SVGs — is resolved in this order:
- an attached file, by plain name (
logo.png,./logo.png); - a
data:URI; - an
http(s)URL, only if its host is inPDFBOX_FETCH_ALLOWED_HOSTS(empty by default: nothing is fetched). Every redirect hop is re-checked, the fetch is bounded byPDFBOX_FETCH_TIMEOUTandPDFBOX_FETCH_MAX_BYTES, and a resource cited several times is fetched once.
Everything else is refused: file:, jar:, classpath:, relative paths that name no attached file,
unlisted hosts. The bundled fonts are not concerned. By default an unresolved resource fails the
render with a 422 listing each one and why (not-allowed, not-found, timeout, too-large,
fetch-error):
2 resource(s) could not be resolved:
- sigwx.svg : not-found — no attached file named 'sigwx.svg'
- https://tiles.example.org/fir.png : not-allowed — host 'tiles.example.org' is not in PDFBOX_FETCH_ALLOWED_HOSTS (empty: nothing is fetched)
With ?onMissingResource=report the PDF is returned anyway and the list travels in response headers
(an RFC 8941 list; % and non-ASCII bytes of each reference are percent-encoded):
X-Pdfbox-Unresolved-Count: 2
X-Pdfbox-Unresolved-Resources: "sigwx.svg";reason=not-found, "https://tiles.example.org/fir.png";reason=not-allowed
Every PDF response carries the versions of the libraries that laid it out, read from the jars that actually run. Record it next to the PDF: a layout that changes after an upgrade can be traced to it. The same versions are written in the PDF's Producer, so they also travel with the file.
X-Pdfbox-Engine: openhtmltopdf/1.1.114 pdfbox/3.0.8 batik/1.20
Inline <svg> and attached / fetched .svg files are drawn as vector art (Apache Batik). Scripts and
on* handlers are removed and never run; Batik itself may only read data: URIs — every other
reference inside an SVG goes through the rules above. SVG text is drawn with the bundled fonts, never
with host fonts. PDF/A-2/3 keep SVG transparency; for PDF/A-1, which forbids it, it is flattened
over white (see the conformance notes below).
An invalid standard returns a plain-text 400 that names the bad value and lists the accepted
ones, so you never have to guess:
curl "http://localhost:8080/api/v1/pdf-info?standard=foo"
# Invalid value 'foo' for parameter 'standard'. Supported values: NONE, PDF_A_1A, PDF_A_1B, ...All error bodies are UTF-8 plain text: 400 bad input, 413 upload too large, 422
unresolved resources, 503 + Retry-After when every render slot stays busy longer than
PDFBOX_RENDER_QUEUE_TIMEOUT.
GET /api/v1/pdf-info?standard=<STANDARD> returns a PDF that is both an example of and a
description of that standard: the file conforms to the requested standard and its content lists the
constraints that standard enforces (conformance level, rules common to every PDF/A part, and the
part-specific rules). Handy as a reference and as a quick conformance check.
# A PDF/A-1a document that explains PDF/A-1a:
curl "http://localhost:8080/api/v1/pdf-info?standard=PDF_A_1A" -o pdf-info-1a.pdf
verapdf --flavour 1a pdf-info-1a.pdf # and it validatesThe OpenAPI 3 description is always served at /v3/api-docs (handy for generating clients).
The interactive Swagger UI is a dev-only convenience and is disabled by default. Enable it by
activating the dev profile, then browse to http://localhost:8080/swagger-ui.html:
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# or, on the packaged jar / Docker:
SPRING_PROFILES_ACTIVE=dev java -jar target/pdfbox.jar
docker run --rm -p 8080:8080 -e SPRING_PROFILES_ACTIVE=dev softwarity/pdfbox:latestIn Swagger UI, POST /api/v1/pdf/upload renders a file picker for the HTML and an “add item” list of
pickers for resources: pick the files, a standard, and the response download is your PDF.
All glyphs are embedded (required for PDF/A), so output is reproducible offline. A very broad Noto
set ships with the service: Noto Sans (Latin/Vietnamese/Cyrillic/Greek), Noto Serif, Noto Sans Mono, and per-script faces for Hebrew, Arabic, Thaana, all the major Indic scripts (Devanagari,
Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Sinhala), Thai, Lao, Myanmar,
Khmer, Georgian, Armenian, Ethiopic, Japanese, Korean, Chinese (Simplified & Traditional), plus
symbols/math and monochrome emoji. The CSS generic families sans-serif/serif/monospace resolve
to Noto Sans/Noto Serif/Noto Sans Mono, so a stack ending in a generic (the usual
font-family: Arial, sans-serif) always lands on a real embedded face.
You normally write nothing: a single document can mix scripts freely and the right faces are chosen automatically. To force a family explicitly, use CSS:
<p style="font-family:'Noto Sans Hebrew'">שלום עולם</p>
<p style="font-family:'Noto Sans JP'">日本語のテキスト</p>Per-document font selection. openhtmltopdf re-parses every font it is told about on every
render, so registering the whole set each time would re-parse tens of MB per request. Instead the
service scans the source for the Unicode blocks it actually contains and only registers the matching
faces — a Latin-only PDF never pays to parse Thai, Devanagari or CJK. Shared CJK Han ideographs are
disambiguated to Japanese / Korean / Simplified / Traditional from the document lang
(ja / ko / zh-Hans / zh-Hant), defaulting to Japanese. So declare lang on elements
mixing Chinese/Japanese/Korean to get the correct Han shapes.
Where the fonts live. The light faces are bundled in the jar. The big CJK faces (Korean, Chinese
SC/TC) are shipped as filesystem fonts in the Docker image under /usr/share/fonts instead, to keep
the jar small — running the bare jar therefore covers everything except CJK unless you add CJK
.ttf files yourself. Need another script, or CJK when running the jar directly? Drop extra .ttf
files into /app/fonts (Docker) or any directory in PDFBOX_FONTS_DIRECTORIES; they are indexed at
startup. Two caveats: the PDFBox renderer only embeds TrueType outlines, so OpenType/CFF .otf files
are skipped (convert to .ttf first); and a variable font is embedded at its default master, so
freeze it to a static instance first (the image does this for the Noto CJK variable fonts, forcing
wght=400, otherwise they would embed as Thin).
B(visual) andU(Unicode) levels are the recommended, fully-supported targets. Output carries the proper PDF version (1.4 for part 1, 1.7 for parts 2/3), an embedded sRGB output intent, embedded fonts and a PDF/A XMP identification block; PDF/A-1 is written with a classic cross-reference table.A(accessible/tagged) levels additionally enable tagged/PDF-UA output, whose validity depends on the input HTML being accessible (document language, imagealttext, proper heading order…). As a safety net the service injects a<title>,<html lang>and<meta name="subject">(the PDF/UA description maps to the PDF Subject, i.e.<meta name="subject">, notdescription) when the source omits them (seePDFBOX_DEFAULT_LANG/PDFBOX_DEFAULT_TITLE), but for genuinely accessible output you should supply accurate ones — generic defaults satisfy the validator, not a screen-reader user.PDF_UA_1produces accessible, tagged PDF 1.7 identified as PDF/UA-1 (ISO 14289-1), without the PDF/A archiving constraints — validated against veraPDF's PDF/UA-1 profile. The same safety net applies, and an inline<svg>gets its alternate text fromaria-labelor its<title>. For accessible and archival output, use anAlevel (PDF_A_1A,PDF_A_2A,PDF_A_3A).- Transparency and PDF/A-1. PDF/A-1 forbids transparency, so for part 1 it is flattened over
white: images with an alpha channel (PNG, GIF, WebP — attached, fetched,
data:or inside SVG) are composited on white, and SVGopacity/fill-opacity/stroke-opacity/stop-opacityare folded into solid colours (a 50 % red becomes#ff8080). It is a simple flattening: content over a non-white background is approximated as if over white, and what cannot be folded (a gradient under a transparent group, an opacity set in an SVG<style>rule, an unusual named colour) is drawn opaque. CSSrgba()/opacityare neutralised by the engine itself. PDF/A-2 and PDF/A-3 keep real transparency. - Always validate critical output with veraPDF:
verapdf --flavour 1b document.pdf # or 3b, ua1…
Sensible defaults mean you normally configure nothing. If needed, override via environment variables:
| Property | Default | Purpose |
|---|---|---|
PDFBOX_DEFAULT_STANDARD |
PDF_A_1B |
Standard used when the request omits standard. |
PDFBOX_FONTS_DIRECTORIES |
/app/fonts,/usr/share/fonts,fonts |
Comma-separated font scan directories. |
PDFBOX_DEFAULT_FONT_FAMILY |
Noto stack | CSS font stack applied when the HTML sets none. |
PDFBOX_DEFAULT_LANG |
en |
<html lang> injected when the source omits it (required by the accessible "A" levels / PDF/UA). |
PDFBOX_DEFAULT_TITLE |
Document |
<title> injected when the source has none and no usable <h1>/<h2>/<h3> (required by PDF/UA). |
PDFBOX_FETCH_ALLOWED_HOSTS |
(empty) | Exact host names (optional :port) remote resources may be fetched from. Empty = nothing is fetched. No port = default port (80/443) only. |
PDFBOX_FETCH_TIMEOUT |
10s |
Overall time per remote resource (connection, redirects, body). |
PDFBOX_FETCH_MAX_BYTES |
10MB |
Maximum size of one remote resource. |
PDFBOX_UPLOAD_MAX_PART_SIZE |
20MB |
Maximum size of one multipart part (the HTML or one attached file). |
PDFBOX_UPLOAD_MAX_TOTAL_SIZE |
50MB |
Maximum size of a whole multipart request. |
PDFBOX_UPLOAD_MEMORY_THRESHOLD |
(unset = max part size) | Parts above this size go to a temporary file for the duration of the request instead of memory. Unset: nothing is ever written to disk. |
PDFBOX_RENDER_MAX_CONCURRENT |
0 (= CPUs) |
Renders running at once; others wait for a slot. Bounds CPU and memory (≈ this × upload total). |
PDFBOX_RENDER_QUEUE_TIMEOUT |
10s |
Longest wait for a render slot before a 503 + Retry-After. |
PDFBOX_BASE_PATH |
(empty) | Base path prefixed to every route, set at startup. Must start with /. |
SPRING_PROFILES_ACTIVE |
(none) | Set to dev to enable Swagger UI. |
JAVA_OPTS |
(empty) | Extra JVM flags. |
The base path is a startup parameter, fixed for the lifetime of the process — not a per-request value. Provide it at launch as an environment variable or a Spring command-line argument:
# Environment variable
PDFBOX_BASE_PATH=/pdfbox java -jar target/pdfbox.jar
docker run --rm -p 8080:8080 -e PDFBOX_BASE_PATH=/pdfbox softwarity/pdfbox:latest
# ...or as a launch argument
java -jar target/pdfbox.jar --server.servlet.context-path=/pdfboxEvery route then lives under that prefix, e.g. POST http://localhost:8080/pdfbox/api/v1/pdf,
GET http://localhost:8080/pdfbox/v3/api-docs, GET http://localhost:8080/pdfbox/actuator/health.
A minimal Helm chart ships under helm/pdfbox. It deploys the multi-arch image with a
Deployment + Service, health probes on /actuator/health, and an optional Ingress.
helm install pdfbox ./helm/pdfbox
# pin a release and run two replicas
helm install pdfbox ./helm/pdfbox --set image.tag=1.0.0 --set replicaCount=2See the chart README and the Kubernetes docs page for values (Ingress, base path, extra fonts, autoscaling).
The published artifact is the multi-arch Docker image (docker.io/softwarity/pdfbox), and the
git tag is the source of truth for the version. Releases are cut by the
softwarity/release-flow action.
- Keep
RELEASE_NOTES.mdup to date as you merge: write user-facing changes under the## NEXT RELEASEheading. That section becomes the published release notes. - Run the Release workflow (Actions → Release → Run workflow) and pick
patch/minor/major. It first runsmvn verify(a redmainis never tagged), then release-flow, in one commit onmain: computes the nextvX.Y.Zfrom the latest tag, syncspom.xml's<version>(maven_dockermode,mvn versions:setin amaven:3-eclipse-temurin-25container), syncs the Helm charthelm/pdfbox/Chart.yaml(versionandappVersion, soimage.tag: ""deploys the released image), renames## NEXT RELEASE→## X.Y.Z, tags and pushes, publishes the GitHub Release, and reopens a fresh## NEXT RELEASE. - The pushed tag triggers Docker release, which runs
mvn verifythen builds and publishes theamd64+arm64image, taggedlatest,X.Y.ZandX.Y.
The tag is pushed with a PAT (the
PAT_TOKENsecret, used byactions/checkout), not the defaultGITHUB_TOKEN— GitHub does not re-trigger workflows forGITHUB_TOKENpushes, so the Docker release would otherwise never start.
HTML ──jsoup──► well-formed W3C DOM ──openhtmltopdf (+ Batik for SVG)──► PDF (PDFBox) ──► PDF/A post-pass ──► bytes
▲ every resource: attached file │ data: │ allowed http(s) host — or refused & reported
- jsoup parses arbitrary/malformed HTML into a clean DOM; inline SVG is sanitized there.
- openhtmltopdf renders the DOM to PDF/A on top of Apache PDFBox, SVG through Apache Batik.
- One per-request resolver serves every stylesheet, font, image and SVG reference (see Resources).
- A small PDFBox pass fixes the PDF/A header version and cross-reference table and clears image interpolation flags (forbidden in every PDF/A part).
This project stands on the shoulders of these open-source projects — thank you:
- openhtmltopdf — HTML/CSS → PDF/A & PDF/UA engine (LGPL-2.1), a fork of
- Flying Saucer (LGPL-2.1)
- Apache PDFBox — PDF library (Apache-2.0)
- Apache Batik — SVG rendering (Apache-2.0)
- TwelveMonkeys ImageIO — WebP decoding (BSD-3-Clause)
- jsoup — HTML parser (MIT)
- Spring Boot (Apache-2.0)
- Noto fonts (SIL Open Font License 1.1)
- PDF/A validation by veraPDF
Apache-2.0



