Deploy and Host MinerU on Railway

MinerU is OpenDataLab's document parsing engine: PDFs, images and Office files in, LLM-ready Markdown and JSON out, with layout detection, OCR in 80+ languages, table-structure recognition and formula recognition. This template runs its mineru-api HTTP server on CPU — no GPU, no per-page cloud OCR fees, and no third-party service holding your documents.

It deploys as one service on a volume, from a prebuilt image, with the parsing models already inside it.

About Hosting MinerU

MinerU is normally packaged for a GPU box on a trusted network, and two of its defaults do not survive the move to a one-click public deploy. This template changes both, in the image, so the deployer never has to know about them.

The default request parses. MinerU 3.4's default backend is hybrid-engine, which expects a local VLM and a GPU. On a CPU container a request that simply omits backend= does not fail cleanly — it downloads roughly 2 GB of additional VLM weights and then runs vision-language inference on the CPU, taking tens of minutes for a paper-length PDF. Railway's edge gives up at about five minutes, so the caller sees Application failed to respond while the container keeps working, and keeps billing. Here pipeline is the server's default, so a plain POST /file_parse with a file and nothing else returns Markdown.

Threads match the container. MinerU's pipeline is torch end to end, and torch sizes its thread pool from the cores it can see — which inside a container is the host's core count, not your plan's quota. The entrypoint reads /sys/fs/cgroup/cpu.max and sets OMP_NUM_THREADS from it before Python imports torch, which is the only moment torch reads it.

Models are already in the image. The layout, OCR, table and formula models are baked in at build time and MINERU_MODEL_SOURCE=local is pinned, so the container needs no network to parse, the first request is as fast as the thousandth, and a redeploy never re-downloads 1.5 GB.

The API is not open to the internet. mineru-api ships no authentication of any kind. This template generates a MINERU_API_KEY and requires it on every parsing route, leaving /health and /docs public.

Why Deploy MinerU on Railway

Document parsing is bursty: heavy while a corpus is being ingested, idle in between. Railway bills what the container actually uses, gives the service a volume for its output and an HTTPS URL for your pipeline to call, and redeploys it without you rebuilding a 3 GB image. Because the image is prebuilt and the models are baked in, a deploy is a pull and a start — not a ten-minute torch build on your build minutes.

Common Use Cases

Ingesting PDFs into a RAG pipeline or vector store as clean Markdown, with headings, tables and formulas preserved rather than flattened.
Giving an agent or workflow (n8n, LangChain, LlamaIndex) a private POST /file_parse endpoint instead of a metered cloud OCR API.
Converting scanned or mixed-language archives — 80+ OCR languages, including Chinese, Japanese, Korean, Arabic, Cyrillic, Devanagari and Thai.

Dependencies for MinerU Hosting

A Railway service running the prebuilt image ghcr.io/bon5co/mineru-railway.
A Railway volume mounted at /data for async task output.
MINERU_API_KEY, generated per deploy, sent as Authorization: Bearer … or X-API-Key: ….

Deployment Dependencies

MinerU — the upstream engine (Apache-2.0 / AGPL components per upstream's notice)
MinerU documentation
bon5co/mineru-railway — the wrapper image built for this template

Implementation Details

Parse a document — no backend parameter needed:

curl -X POST https:///file_parse \
  -H "Authorization: Bearer $MINERU_API_KEY" \
  -F "files=@paper.pdf" \
  -F "lang_list=en" \
  -F "return_md=true"

Large documents are better submitted asynchronously — POST /tasks returns a task id, GET /tasks/{id} reports status and GET /tasks/{id}/result returns the output once it is ready. Results live on the volume under /data/output.

Interactive documentation is at https:///docs, and https:///health is the unauthenticated health endpoint Railway uses.