ComPDF Generation: a self-hosted HTML-to-PDF SDK with a visual template editor

What ComPDF Generation replaces, and for whom

Most teams that generate invoices, contracts, reports or certificates end up with one of two arrangements. The first is a library wired directly into the application, where the document layout lives in code and every design change is a deployment. The second is a SaaS rendering API, where the layout can be edited by someone else but the document data leaves the network. ComPDF Generation is aimed at the gap between those two: the README describes it as an "open-source, self-hosted PDF generation SDK and platform" where templates are authored in a visual editor, bound to structured JSON data, and rendered by an engine you run yourself.

The intended user is a developer or a small platform team, not an end user. Templates are stored as files and metadata under TEMPLATE_STORAGE_DIR, the Web UI and the Express API are served from the same container, and the repository ships a docker-compose.yml rather than a package on a registry. If you want to call a function from your Node process and get a Buffer back, this is a heavier answer than a library. If you want a place where a non-developer can adjust a contract layout without a release, the architecture starts to make sense.

The two-container split: engine on 7001, web and API on 8090

The Compose file defines two services on a private bridge network called compdf-internal. Only one of them publishes a port to the host.

The first service, compdf-app, runs the image compdfkit/pdf-generation:1.0.0 and listens on 7001. Its healthcheck curls http://localhost:7001/livez every 10 seconds, with 12 retries and a 30 second start period. It carries a mem_limit of 16g, which is the most concrete constraint in the repository: the generation engine is expected to be given a large memory ceiling. The second service, compdf-generation, is built from the repository's multi-stage Dockerfile and is the only one with a host port, mapped from APP_PORT (default 8090) to 8090 inside the container. It waits for the engine to report healthy before starting, and talks to it through COMPDF_PDF_BASE_URL, set to http://compdf-app:7001.

The Dockerfile builds the Vite frontend and the Express server in separate stages, installs production-only dependencies in a third, and copies the compiled server to dist and the built frontend to public in a final image that runs as the node user. The container healthcheck is notable: it fetches /api/templates/search, and the comment above it says that endpoint is available without a ComPDF generation request. That means the container can report healthy before the engine has ever rendered anything, so a green health status is not proof that licensing and generation work end to end.

Installing ComPDF Generation with Docker Compose

The README gives the same three steps for every platform: clone, copy the environment file, start the stack. Docker Desktop (macOS and Windows) or Docker Engine with the Compose plugin (Linux) must be installed, and the machine must be able to pull compdfkit/pdf-generation:1.0.0 from Docker Hub.

On macOS or Linux:

git clone https://github.com/ComPDFKit/compdf-generation.git
cd compdf-generation
cp .env.example .env
docker compose up -d --build
docker compose ps

The Windows equivalent swaps the copy command for Copy-Item .env.example .env. The README states that you should wait until compdf-app becomes healthy, then open http://localhost:8090. On a remote Linux server, the same address works from any browser that can reach the server's 8090 port.

The .env.example file ships a working trial license in COMPDF_LICENSE_KEY, and the README is explicit that this key adds a watermark to generated PDFs. For production you replace it with a formal license. The Compose file enforces this: the engine's environment sets COMPDFKIT_LICENSE from COMPDF_LICENSE_KEY with a required-variable expansion, so the stack refuses to start if the value is missing.

environment:
  COMPDFKIT_LICENSE: ${COMPDF_LICENSE_KEY:?COMPDF_LICENSE_KEY must be set in .env}

The other variables worth knowing before the first start are COMPDF_IMAGE_PLATFORM (default linux/amd64), APP_PORT (8090), COMPDF_TIMEOUT_MS (120000, the time the Web and API services wait for the engine), and TEMPLATE_STORAGE_DIR, which defaults to ./data/templates on the host and is mounted at /data/templates in the container. The README notes that rebuilding the application container does not remove template data, because that directory is a volume.

Where the deployment model works against you

The most obvious limitation is licensing, not code. The repository badge reads "AGPL v3 + Commercial", and the GitHub licence field reports NOASSERTION, which usually means the file does not match a standard template that GitHub recognises. The README frames the split as "Open Source & Commercial Editions" but does not spell out in the text available here which features sit behind the commercial edition. Anyone planning to embed this in a product should read LICENSE and THIRD-PARTY-NOTICE.md directly rather than inferring from the badge.

Second, the platform default is linux/amd64, and the README says to change COMPDF_IMAGE_PLATFORM only if the image supports the target deployment platform. On Apple Silicon this means emulation unless a matching image exists, and the README does not document an arm64 variant.

Third, the 16 GB mem_limit is not a soft suggestion. If the host cannot give the engine container that ceiling, or shares it with other workloads, large batch jobs are the first thing to suffer. The README also lists COMPDF_TIMEOUT_MS with the note that you should increase it "for large or complex templates", which implies that long renders are an expected failure mode rather than an edge case. Raising the timeout does not raise the memory ceiling.

Finally, the healthcheck gap described above is a real operational trap. A container that reports healthy while the generation path is unlicensed or misconfigured will pass a naive readiness gate. If you put this behind a load balancer, test an actual generation request, not just the template search endpoint.

How it differs from assembling a PDF library yourself

The natural comparison is a JavaScript PDF library used directly inside the application, where you construct the document programmatically and write the bytes wherever you need them. That approach has no extra container, no licence key, no engine port, and no 16 GB memory line in a Compose file. It also has no visual editor: changing a layout means changing code.

ComPDF Generation inverts that. The template is a first-class artifact that lives in TEMPLATE_STORAGE_DIR, can be edited in the browser at port 8090, and is rendered by a separate engine process that the API reaches over HTTP. The README also describes batch import of DITO templates and ComPDF Generation templates, positioned as a migration path "from iText and other competing PDF generation solutions". That is a meaningful difference in kind: iText-style work is a library embedded in your build, while this is a service you deploy and operate.

The cost of that inversion is everything that comes with running a service. You gain a template lifecycle and a UI for people who do not write code. You take on a second container, a licence key, a storage directory that must survive container recreation, and a rendering engine whose memory footprint is measured in gigabytes.

Maintenance, upgrades and what the licence key actually controls

The last push to the repository was on 2026-08-21, the same day v1.1.0 was released; v1.0.0 was released on 2026-08-05. The repository is not archived. Two releases in roughly two weeks is a young project, and the README does not document a rollback procedure, a migration guide between versions, or a compatibility policy for templates created on an older release. Treat the template directory as data you own and back up, because the documentation does not promise that a future engine version will read today's templates unchanged.

Upgrades run through Docker Compose. The engine is pinned to a specific tag, compdfkit/pdf-generation:1.0.0, in docker-compose.yml, so the engine version is a deliberate edit rather than an implicit pull. The application image is built locally and tagged compdf-generation-web:latest, which means a rebuild picks up whatever the current Dockerfile produces. The README states that rebuilding the application container does not remove template data, which is the one upgrade guarantee the documentation does make.

On licensing, the practical question is what COMPDF_LICENSE_KEY grants. The README says it must be a key "with PDF Generation or HTML-to-PDF permissions", and that the trial key in .env.example adds a watermark. Nothing in the text available here describes per-document quotas or pricing tiers, and the README's own feature list claims "no document-generation quota" for high-volume processing. Whether that applies to the commercial edition, the open source edition, or both is not stated. That is a question for the vendor, not something to assume.

Editorial conclusion

Adopt ComPDF Generation if you want template authoring and PDF rendering to stay inside your own network and you can accept the AGPL v3 plus commercial licensing model. Do not adopt it if you need a permissive licence, if you cannot obtain a COMPDF_LICENSE_KEY, or if the host cannot give the engine container its 16 GB memory limit. Before committing, confirm what the trial key's watermark looks like on your own templates, verify that the linux/amd64 image matches your deployment platform, and check whether TEMPLATE_STORAGE_DIR is mounted on storage you actually back up.

Frequently asked questions

Official sources

1. ComPDFKit/compdf-generation on GitHub
2. Issues
3. Project website
4. README
5. Releases