Przejdź do głównej treści
PPDF123

Self-host PDF123

Run the PDF123 API, portal and blog on your own machines with Docker Compose. Files stay inside your network, and the backend image carries the programs behind the conversion tools.

Na tej stronie

What runs

The production stack in compose/docker-compose-pdf.yml has three services on one Compose network.

ServicePortRole
pdf-backend8080 (PDF_BACKEND_PORT on the host)The Rust pdfx-server: REST API, OpenAPI description and the /mcp endpoint.
pdf-web3200 on the host (PDF_WEB_PORT), 3000 in the containerThe Next.js portal. It forwards /api/* to the backend and /blog to the blog.
pdf-blog3002, internal onlyThe blog. Visitors reach it through the portal at /blog.

Start the stack

# from the repository root
task docker:build:base   # environment image, once
task docker:build        # backend image
task docker:build:web    # portal image
task docker:up           # API :8080, portal :3200
task docker:logs
task docker:down

The backend has a health check on /api/v1/info/status and the portal waits for it. Anonymous use needs no account; calling the API from code is described under Developers.

Programs in the backend image

Most conversions call a system program. The environment image installs these, and the backend reports a tool as disabled when its program is missing instead of failing at startup.

ProgramTools it supports
LibreOffice (Writer, Calc, Impress, Draw)File to PDF, PDF to Word, text, XML and PowerPoint
qpdfCompress, decompress, repair, split by page count, size or document count
GhostscriptPDF to images, extract scanned photos
Tesseract, English plus 11 other language packsSearchable PDF, OCR to text, OCR fallback for scanned tables
poppler-utilsPDF to CSV, Excel and HTML
WeasyPrintHTML to PDF, Markdown to PDF, URL to PDF
CalibreeBook to PDF
OpenJDK 21 runtime and OpenSSLSigning a PDF with a certificate

PDF to Markdown runs inside the Rust process. For scanned pages it uses an OCR model of about 31 MB (PP-OCRv6 Small) that is downloaded the first time it is needed, unless you place it beforehand with PDF_INSPECTOR_MODEL_CACHE.

Settings

ServiceVariableEffect
pdf-backendSERVER_PORTPort the API listens on. Default 8080.
pdf-backendPUBLIC_URLOrigin written into the OpenAPI servers list, without /api. Set it to your own address, or the API reference shows ours.
pdf-backendPDFX_OCR_MAX_PAGESPages that need recognition per OCR request. Default 50.
pdf-webBACKEND_URLWhere the portal forwards /api/*. In the compose file, http://pdf-backend:8080.
pdf-webBLOG_ORIGINWhere the portal forwards /blog. In the compose file, http://pdf-blog:3002.
pdf-webSITE_URLPublic origin of your portal. Without it the portal publishes https://pdf123.xyz in canonical links, the sitemap and llms.txt.
pdf-webAUTH_SECRET, PORTAL_BRIDGE_SECRETNeeded only if you turn on portal login, together with the sign-in provider IDs and secrets.

Upload limits are the ones listed on Limits, because they are set in the backend itself.

Check that every tool is on

curl -s http://localhost:8080/api/v1/settings/get-endpoints-status
curl -s http://localhost:8080/api/v1/info/status

The first call lists every tool with true or false. A request to a disabled tool returns HTTP 403. The second reports the OCR languages that are installed and the page limit for OCR. After you change the list of installed programs, rebuild the environment image and check both again.

Run without Docker

task pdfx:dev          # API on :8080
task web-portal:dev    # portal, or: task dev for both

This is the development setup: install the programs from the table above on your machine first.