How to Use

Before You Begin

• Docker Desktop on Windows or macOS, or Docker Engine with the Docker Compose plugin on Linux.
• Access to the compdfkit/pdf-generation:1.1.0 image on Docker Hub.

Get the Project

Clone the repository and enter the project directory:

git clone https://github.com/ComPDFKit/compdf-generation.git
cd compdf-generation

Configure and Start

The project includes a trial license in .env.example. Copy and rename this file to .env before deployment to use the trial license. PDFs generated with the trial license include a watermark.

For production use without the trial watermark, replace COMPDF_LICENSE_KEY with a formal license. Contact sales to obtain one. Use the command for your operating system to copy the environment file:

# Windows PowerShell
Copy-Item .env.example .env

# macOS or Linux
cp .env.example .env

Start the services:

docker compose up -d --build
docker compose ps

When compdf-app shows healthy, open http://localhost:8090. If you deploy to a remote Linux server, open the URL from a browser that can reach the server's port 8090.

Environment Variables

Configure the following values in .env before starting the services:

Variable	Default	Description
COMPDF_LICENSE_KEY	Required	ComPDF License Key with PDF Generation or HTML-to-PDF permission. The trial key included in .env.example generates watermarked PDFs.
COMPDF_IMAGE_PLATFORM	linux/amd64	Platform used for the compdf-app image. Change this only when the image supports the platform required by the deployment host.
NODE_IMAGE	node:22-bookworm-slim	Node.js image used by the multi-stage Docker build for the web and API service.
APP_PORT	8090	Host port mapped to the ComPDF Generation web interface and API. Use another available port when 8090 is occupied.
COMPDF_TIMEOUT_MS	120000	Maximum time in milliseconds that the web/API service waits for a response from the ComPDF engine. Increase this value when large or complex templates need more processing time.
TEMPLATE_STORAGE_DIR	./data/templates	Host directory used to persist HTML templates, JSON data sources, and metadata. Use an absolute path when the deployment requires a specific data location.

Verify the Deployment

docker compose ps
docker compose logs --tail=100 compdf-generation compdf-app

Both services must be running, and compdf-app must be healthy before you generate a PDF. If the service is accessed from another machine, allow inbound TCP traffic on APP_PORT (default 8090) in the server firewall or security group.

Create and Generate a Template

1. Create a template from the template list, or import a .html, .htm, .zip, or .dito file to create one.
2. Open the template editor and write the HTML content.
3. Optionally add JSON data for dynamic values, then save the template.
4. Generate the PDF in the editor; the browser downloads the result.

Templates are stored in TEMPLATE_STORAGE_DIR, which defaults to ./data/templates on the host. This data remains when the application container is rebuilt.