Getting Started Guide

ComPDF Self-hosted is a Docker Compose based private PDF processing platform. It serves ComPDF Web, Dashboard, and /api/v1 APIs from the unified application entry on port 8080.

Requirements

• A 64-bit Linux server or Docker Desktop environment.
• At least 4 GB RAM.
• Docker Engine and Docker Compose v2.
• A valid ComPDF License Key for production use.

Quick Start

git clone https://github.com/ComPDFKit/compdf-self-hosted.git
cd compdf-self-hosted
cp .env.example .env
docker compose up -d

After startup, open:

Entry	URL
ComPDF Web	http://localhost:8080/
Dashboard	http://localhost:8080/admin
Health check	http://localhost:8080/api/v1/status

To use an Enterprise license, replace COMPDF_LICENSE_KEY in .env and restart the services.

Dashboard Console

ComPDF Self-hosted provides a unified management console for viewing API Key details, API usage, and License status, as well as supporting operation log auditing, account management, and core system configuration. It is available at /admin.

• Overview Panel: Displays API Key details, API usage statistics, License scope, and usage status.
• Operation Logs: Track, search, and export all the operation logs.
• Account Management: Set the user name and password.
• System Settings: Set the name, logo, theme color of the system.

On the first visit, the Dashboard guides you through creating the initial admin account. After setup, sign in with that account to manage the deployment.

API Key

Conversion, PDF tool, and async task APIs require x-api-key. Set API_KEY in .env for a fixed key. If it is empty, the application generates one on first boot and saves it to STORAGE_DIR/.api-key-plaintext; ComPDF Web and Dashboard use this key automatically.

curl -X POST "http://localhost:8080/api/v1/process/pdf/docx" \
  -H "x-api-key: your_api_key_here" \
  -F "[email protected]"

Configuration

Variable	Default	Description
PORT	8080	Application listening port.
JWT_SECRET	change-me-in-prod	Dashboard admin-session JWT secret. Change it in production.
API_KEY	empty	Plaintext key for protected APIs. If empty, first startup generates one automatically.
CORS_ORIGINS	*	Allowed CORS origins. Use commas for multiple origins.
COMPDF_TOOLS_ENABLED	false	ComPDF Web configuration flag. Only literal true enables it.
DATABASE_HOST / DATABASE_PORT	compdf-infra / 3306	MySQL host and port used by the application.
DATABASE_USER / DATABASE_PASSWORD / DATABASE_NAME	compdfkit / compdfkit-pass-2026 / compdfkit	MySQL credentials and database name.
REDIS_HOST / REDIS_PORT	compdf-infra / 6379	Redis host and port used by the application.
LICENSE_TOKEN_PATH	/app/configs/license.jwt	License token file path.
COMPDF_LICENSE_KEY	empty	ComPDF License Key.
COMPDF_LICENSE_SECRET	empty	Optional License Secret.
COMPDF_AI_MODEL	/opt/compdf_sdk/models/documentai.model	Document AI model path.
PUBLIC_DIR	/app/public	Frontend static asset directory in the production image.
SETTINGS_PATH	/app/configs/settings.yml	Dashboard system settings file path.
STORAGE_DIR	/app/storage	Storage directory for task results and generated API key file.

Operations

docker compose ps
docker compose logs -f compdf-server
docker compose restart compdf-server

Development Mode

For development, follow the README in the project repository. The common flow is to start Docker Compose services, run the server locally, and run the Web UI with hot reload.