What runs
The production stack in compose/docker-compose-pdf.yml has three services on one Compose network.
| Service | Port | Role |
|---|---|---|
| pdf-backend | 8080 (PDF_BACKEND_PORT on the host) | The Rust pdfx-server: REST API, OpenAPI description and the /mcp endpoint. |
| pdf-web | 3200 on the host (PDF_WEB_PORT), 3000 in the container | The Next.js portal. It forwards /api/* to the backend and /blog to the blog. |
| pdf-blog | 3002, internal only | The 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:downThe 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.
| Program | Tools it supports |
|---|---|
| LibreOffice (Writer, Calc, Impress, Draw) | File to PDF, PDF to Word, text, XML and PowerPoint |
| qpdf | Compress, decompress, repair, split by page count, size or document count |
| Ghostscript | PDF to images, extract scanned photos |
| Tesseract, English plus 11 other language packs | Searchable PDF, OCR to text, OCR fallback for scanned tables |
| poppler-utils | PDF to CSV, Excel and HTML |
| WeasyPrint | HTML to PDF, Markdown to PDF, URL to PDF |
| Calibre | eBook to PDF |
| OpenJDK 21 runtime and OpenSSL | Signing 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
| Service | Variable | Effect |
|---|---|---|
| pdf-backend | SERVER_PORT | Port the API listens on. Default 8080. |
| pdf-backend | PUBLIC_URL | Origin written into the OpenAPI servers list, without /api. Set it to your own address, or the API reference shows ours. |
| pdf-backend | PDFX_OCR_MAX_PAGES | Pages that need recognition per OCR request. Default 50. |
| pdf-web | BACKEND_URL | Where the portal forwards /api/*. In the compose file, http://pdf-backend:8080. |
| pdf-web | BLOG_ORIGIN | Where the portal forwards /blog. In the compose file, http://pdf-blog:3002. |
| pdf-web | SITE_URL | Public origin of your portal. Without it the portal publishes https://pdf123.xyz in canonical links, the sitemap and llms.txt. |
| pdf-web | AUTH_SECRET, PORTAL_BRIDGE_SECRET | Needed 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/statusThe 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 bothThis is the development setup: install the programs from the table above on your machine first.