Self-hosted Generation

ComPDF Generation is a self-hosted HTML template management and PDF generation service. It provides a web interface and HTTP API for managing HTML templates, optional JSON data sources, and PDF output generated by the ComPDF PDF Generation engine.

Use ComPDF Generation when you need to keep templates and document-generation workflows within your own environment.

Features

• A browser-based interface for creating, editing, searching, downloading, and deleting templates.
• Optional JSON data sources for dynamic template content.
• A Template to PDF HTTP API for programmatic PDF generation.
• Docker Compose deployment with persistent template storage.

Architecture

────────────────────────────────────
    Browser / API Client
    http://localhost:${APP_PORT}
────────────────────────────────────
        │ HTML / CSS / JS
        │ HTTP /api/*
        ▼
────────────────────────────────────
    compdf-generation container
    Vue 3 static files + Express API
    port 8090
────────────────────────────────────
- Express serves frontend static assets and falls back to `index.html` for SPA routes.
- `/api/templates/*` manages template HTML, JSON data sources, and metadata.
- `/api/v1/process/pdf/generation/template-to-pdf` proxies PDF generation requests.
- Handles uploads, timeouts, error responses, download filenames, and trace IDs consistently.
────────────────────────────────────
      │ HTTP
      │ compdf-internal
      ▼
────────────────────────────────────
 compdf-app container
 ComPDF PDF Generation engine
 port 7001
────────────────────────────────────

Request Flow

1. The browser loads the built Vue single-page application from compdf-generation and calls Express through same-origin /api, so production deployments do not require a separate static file server.
2. Express reads and writes template-management requests directly to /data/templates. This directory is bound to TEMPLATE_STORAGE_DIR on the host, so data remains after the container is rebuilt.
3. Express forwards PDF-generation requests to http://compdf-app:7001/v1/sync/generation/template-to-pdf. It prepares multipart requests, passes through PDF responses, and standardizes error messages and traceId values.
4. compdf-generation starts after the compdf-app health check passes. The two services communicate through the private compdf-internal bridge network.

Deployment and Local Development

• The production image uses a multi-stage Docker build: it separately builds the Vue frontend and Express backend, then copies only the frontend dist, backend dist, and production dependencies into the final non-root Node.js container. Version 1.1.0 optimizes the underlying image by removing the unnecessary database dependency and reducing image size.
• Docker Compose maps APP_PORT (default 8090) to the web/API container. It also publishes the engine's 7001 port to the host for local backend development and connectivity checks.
• During local development, Vite runs in a separate process and proxies /api to http://localhost:8090. Express accesses the ComPDF engine in Docker through http://localhost:7001 by default.

Key Frameworks and Third-Party Components

Layer	Framework or Component	Purpose
Frontend	Vue 3, Vue Router, Vue I18n	Single-page interface, routing, and six-language internationalization.
Frontend build	Vite, TypeScript, Less	Development server, type checking, and style builds.
Frontend UI	TDesign Vue Next, tdesign-icons-vue-next	UI components and icons.
Template editing	WangEditor (@wangeditor/editor-for-vue)	HTML rich-text template editing.
HTTP client	Axios	Calls same-origin /api endpoints and handles file downloads.
Backend	Node.js 22, Express, TypeScript	Provides the HTTP API, static files, and ComPDF proxy.
Upload and archiving	Multer, Archiver	Handles multipart file uploads and template ZIP downloads.
PDF generation	compdfkit/pdf-generation:1.1.0	Performs synchronous HTML/template-to-PDF generation.
Deployment	Docker Compose, multi-stage Docker builds	Orchestrates the ComPDF engine and web/API container.
Data persistence	Host filesystem	Persists template HTML, JSON, and metadata.

Next Steps

• Deploy the service with How to Use.
• Generate a document through the Template to PDF API.