Deploy and Host PDFMathTranslate on Sealos

PDFMathTranslate translates PDF documents while preserving formulas, tables, and page layout. This template runs the upstream WebUI on Sealos with persistent configuration, model caches, and generated files.

About Hosting PDFMathTranslate

The template deploys:

• PDFMathTranslate 1.9.11 from an immutable multi-architecture image digest
• One WebUI replica in a StatefulSet on port 7860
• Runtime-generated credentials for the Gradio sign-in flow
• A 1Gi persistent volume mounted at /data
• Authenticated HTTPS through a Sealos-managed Service and Ingress protected by PDFMathTranslate login credentials
• Startup, readiness, and liveness probes on the WebUI root
• A restricted container context running as UID and GID 1000

The WebUI requires the username and password supplied during deployment. PDFMathTranslate has no registration flow, so share these credentials only with people who should access uploaded documents and saved translation-provider settings. The upstream runtime is a single service and has no database or object-storage dependency.

Common Use Cases

• Translate research papers while retaining their visual structure
• Produce monolingual and bilingual PDF outputs
• Review foreign-language technical documents
• Translate selected pages from large documents
• Connect PDF translation to Google, Bing, DeepL, OpenAI-compatible, or self-hosted services

Dependencies for PDFMathTranslate Hosting

• A Sealos account and workspace
• Outbound internet access for the selected translation service
• Outbound internet access during the first start if PDFMathTranslate needs to fetch layout models or fonts
• Provider credentials when using a service that requires an API key

Google and Bing work from the WebUI without user-supplied API keys. Provider availability and rate limits remain subject to their public endpoints.

Implementation Details

The template injects the required deployment credentials as container environment values. A small ConfigMap startup script applies umask 077, writes /tmp/pdf2zh-auth.csv, and executes pdf2zh -i --authorized /tmp/pdf2zh-auth.csv. The resulting mode-0600 authentication file stays outside the persistent volume and disappears with the container. Setting the working directory to /data keeps generated PDFs on the persistent volume, while HOME=/data/home keeps configuration, fonts, models, and translation caches across restarts.

Why Deploy PDFMathTranslate on Sealos?

• One-click deployment: Sealos creates the workload, storage, HTTPS route, and application link from one template.
• Persistent working data: Configuration, downloaded assets, caches, and generated PDFs survive Pod replacement.
• Built-in observability: Inspect status, events, resource use, and logs from Sealos.
• Simple resource tuning: Increase CPU for faster document processing without rebuilding the image.

Deployment Guide

1. Open the PDFMathTranslate template and click Deploy Now.
2. Enter a WebUI username and a strong, unique WebUI password, then start the deployment.
3. Wait for the StatefulSet to become ready. The first deployment usually takes 2-3 minutes while Sealos pulls the image and PDFMathTranslate loads its layout model.
4. Open the HTTPS application address shown by Sealos.

Both WebUI credential fields are required. Keep them in a password manager because PDFMathTranslate does not provide registration or password recovery. Upstream parses the credential file as comma-separated values, so use a username and password without commas or line breaks.

Sign In

1. Open the HTTPS application address shown by Sealos.
2. Enter the WebUI username and password supplied during deployment.
3. Continue to the translation interface.

Every user shares the same deployment-level credentials. Changing either value requires updating the StatefulSet environment through a new deployment or template update.

Translate Your First PDF

1. Sign in to the deployed WebUI.
2. Keep File selected and upload a PDF, or select Link and enter a direct PDF URL.
3. Choose a translation service, source language, target language, and page range.
4. Click Translate.
5. Download Translation (Mono) for the translated document or Translation (Dual) for a bilingual document.

The Experimental Options panel controls thread count, translation-cache bypass, font subsetting, custom formula-font matching, and BabelDOC mode.

Translation Services and API Keys

The service selector reveals the fields required by the chosen provider. Common examples include:

PDFMathTranslate stores provider settings in /data/home/.config/PDFMathTranslate/config.json. The WebUI credentials protect this persistent configuration, uploaded documents, and the ability to spend paid-provider quota. Use a strong, unique password, limit credential sharing to trusted users, and use provider keys with the narrowest practical scope.

Persistence

All three locations share the template's 1Gi ReadWriteOnce persistent volume. Monitor storage use when processing many or large documents.

Resource Defaults

Live cold-start and uncached translation tests established these defaults. A 512Mi container was OOM-killed while loading the ONNX model, and 1024Mi reached 92.93% of its cgroup limit. The 2048Mi tier provides operating headroom. The lowest CPU tier completed the official one-page uncached sample in 77.69 seconds.

Increase CPU to 200m or 500m for faster translations, concurrent users, larger PDFs, or BabelDOC workloads.

Scaling

The template uses one replica because configuration, caches, and generated files share a ReadWriteOnce volume. Vertical CPU scaling is the direct path for improving throughput. Multi-replica operation requires a shared storage design and upstream-aware job coordination.

Troubleshooting

The application is still starting

Check the Pod logs in Sealos. A first start can download the DocLayout ONNX model and fonts before Gradio begins listening on port 7860.

Translation fails with a provider error

Try Google or Bing to verify the PDF pipeline without a user-supplied key. For another provider, reopen its service fields and confirm the endpoint, key, and model.

The WebUI rejects the credentials

Use the exact username and password entered during deployment. PDFMathTranslate has no registration or password-recovery flow; update the StatefulSet environment through a new deployment or template update when credentials need to change.

Translation is slow

Increase the CPU limit in Sealos. PDF layout analysis is CPU-bound, and the default 100m tier favors a small resource footprint.

A large upload is rejected

The public Ingress accepts request bodies up to 32m. Reduce the PDF size or raise nginx.ingress.kubernetes.io/proxy-body-size in the Ingress for larger documents.

Generated files consume the volume

Remove old files from /data/pdf2zh_files and monitor the 1Gi persistent volume. Models and fonts under /data/home/.cache also use this volume.

Additional Resources

• PDFMathTranslate documentation
• PDFMathTranslate GitHub repository
• GUI guide
• Sealos App Store
• Sealos Discord

License

PDFMathTranslate is distributed under the GNU Affero General Public License v3.0. This repository provides the Sealos deployment template and does not change the upstream license.