file-to-markdown-docker
Run Apache Tika as a Docker container when you need guaranteed OCR (scanned PDFs, images) or geospatial raster support with zero local install — `apache/tika:<version>-full` bundles Tesseract, GDAL, ImageMagick, and fonts. Also covers the minimal image, port/volume/memory conventions, the path-identity mount gotcha, and how to confirm OCR actually ran rather than silently returning no text. Powered by Apache Tika. Use when a local `tika-app`/`tika-server` doesn't have Tesseract installed, or you want a disposable, self-contained parsing environment. Companion to the `file-to-markdown` skill, which covers the parsing calls themselves once a server is up.
- License 许可
- Apache-2.0
- 所属仓库
- apache/tika
- 最近更新
- 2026-11-13
- Stars
- ★ 4.1k
- Forks
- 1.0k
01 前言 Front Matter
- name
- file-to-markdown-docker
- description
- Run Apache Tika as a Docker container when you need guaranteed OCR (scanned PDFs, images) or geospatial raster support with zero local install — `apache/tika:<version>-full` bundles Tesseract, GDAL, ImageMagick, and fonts. Also covers the minimal image, port/volume/memory conventions, the path-identity mount gotcha, and how to confirm OCR actually ran rather than silently returning no text. Powered by Apache Tika. Use when a local `tika-app`/`tika-server` doesn't have Tesseract installed, or you want a disposable, self-contained parsing environment. Companion to the `file-to-markdown` skill, which covers the parsing calls themselves once a server is up.
03 SKILL.md 正文
<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
Local override: $TIKA_SKILLS_LOCAL/file-to-markdown-docker/LOCAL.md (default ~/.tika-skills),
read after this file, wins on conflict.
Running Apache Tika via Docker
Two images on Docker Hub: apache/tika (REST server, port 9998) and
apache/tika-grpc (gRPC, port 9090). This skill covers apache/tika; the
file-to-markdown companion skill covers the parsing calls in more depth once the
container is up (same HTTP API either way), but the examples below are
enough to parse on their own.
The Docker route needs no local Java at all — the container brings its own. If the host lacks Java 17+ (Tika 4.x's requirement), this is the easiest path, not just the OCR path. This skill describes Tika 4.x images; on a 3.x image the default output is XHTML, not Markdown.
Minimal vs -full — the choice that matters
apache/tika:<version> # JRE + tika-server-standard, pure-Java parsers only
apache/tika:<version>-full # + Tesseract OCR, GDAL, ImageMagick, font sets
Take -full if the task involves OCR (scanned PDFs, photos of documents,
image-only PDFs) or geospatial rasters — otherwise take minimal. A scanned
PDF parsed against the minimal image doesn't error; it just silently returns
little or no text, because there's no Tesseract to run. If output looks
suspiciously short for a document that's clearly a scan, that's the signal
you're on the wrong image, not that the file has no text — see Confirming
OCR actually ran, below.
Tag forms: <version> rolls forward on rebuild of the same release,
<version>-<N> is immutable (pin this in anything long-lived), latest
tracks newest stable. Published for linux/amd64, linux/arm64,
linux/s390x — docker pull/docker run picks the right one automatically.
Starting it
docker run -d -p 127.0.0.1:9998:9998 apache/tika:latest-full
# or pin a real version: apache/tika:4.0.0-full
curl -T document.pdf http://localhost:9998/tika
Bind to 127.0.0.1, not 0.0.0.0 or a bare port mapping, unless you
specifically mean to expose it. Docker writes its own iptables rules, so
-p 9998:9998 (no host part) can publish the server past your host
firewall onto the network — a real, easy-to-hit surprise, not a theoretical
one. Tika parses untrusted input by design; the server itself does no
authentication, so treat network exposure as a deliberate decision, not a
default.
Give it a few seconds to start before the first request — curl -sf http://localhost:9998/version is a simple readiness check to poll in a
script.
Mounting files: get the path identity right
Plain curl -T uploads need no mount at all — the document travels in
the HTTP body. Mounts matter when the container must read paths itself: a
-c config file, pipes fetchers reading from a directory, extra jars. The
path-identity rule below applies to directories of documents that callers
reference by path; a single config or jar mounted at a fixed container
path (-v .../my.json:/my.json:ro) is fine and normal — nothing translates
those paths back and forth. When a caller (an agent, a script) passes
filesystem paths, mount the directory at the same absolute path inside
the container that the caller uses outside it:
docker run -d -p 127.0.0.1:9998:9998 \
-v "/home/me/project:/home/me/project:ro" \
apache/tika:<version>-full
Don't remap to something like /data — if you do, every path the caller
passes needs translating before Tika can see it, and every response
(embedded-file paths from /unpack, resource names) needs translating back.
Matching the host path exactly makes the container a transparent stand-in
for a locally-installed Tika: paths just work in both directions. :ro is
worth defaulting to — Tika only needs to read the input, and a read-only
mount is a real containment boundary if a parse goes wrong, on top of (not
instead of) the process isolation Tika's own forked workers already give
you.
The container runs as a non-root user, UID/GID 35002:35002. Mounted
input files must be readable, and any directory Tika writes to must be
writable, by that UID — a mount that's 0600 owned by your host user will
fail inside the container even though it works fine outside it.
Confirming OCR actually ran
Don't assume the -full image means OCR fired on a given file — confirm it,
especially the first time you stand one up.
The signal is tk:parsed-by-full-set: it lists
org.apache.tika.parser.ocr.TesseractOCRParser when Tesseract was run on the
file (a PDF page or an image), and leaves it out when it wasn't:
curl -T scanned.pdf http://localhost:9998/rmeta | jq '.[0]."tk:parsed-by-full-set"'
Do not use pdf:ocr-page-count for this. It counts the pages that looked
like they needed OCR, whether or not an engine ran, so it is non-zero with OCR
turned off too. tk:ocr-warnings names input the engine was not given:
skipped:<reason> from an image check, skipped:max-pages once a
pages.ocr.maxPages cap is reached (4.3.0+).
No engine listed means OCR didn't run — check you're on -full (not
minimal), that the file actually needs it (a PDF with a real text layer
correctly skips OCR — that's not a bug), and that no mounted config turns it
off (see below). If you see camelCase keys (pdf:ocrPageCount) or X-TIKA:*
keys, your image predates the 4.0.0 metadata-key renames; upgrade the image
rather than adapting to the old spellings.
Configuration (turning OCR off, or anything else)
Mount a tika-config.json and point -c at it — anything after the image
name is appended to the entry point, which already sets -h 0.0.0.0 (don't
pass -h again):
docker run -d -p 127.0.0.1:9998:9998 \
-v "$(pwd)/tika-config.json:/tika-config.json" \
apache/tika:<version>-full -c /tika-config.json
Through 4.2.x the server refuses a config file without a server block
(Couldn't find 'server' element), so include one, even if empty; it is
harmless on later versions.
To keep -full's other parsers but disable OCR specifically (e.g. you only
wanted GDAL), empty the text-recognizers list (4.1.0+):
{
"server": {},
"text-recognizers": []
}
Since 4.2.0 an OCR engine under parsers fails the config load; engines go
under engines and are named in text-recognizers.
Memory
Size the container's --memory limit; don't pass -Xmx — the JVM sizes its
heap from the container's own limit. Tika Pipes forks additional JVMs
inside the same container for isolation, and each fork's heap comes out of
that same limit, so size for the forks, not just the parent:
docker run -d -p 127.0.0.1:9998:9998 --memory 4g apache/tika:<version>-full
Disposable / one-shot use
For a short-lived session, name the container so you can stop it
deterministically — backgrounding docker run does NOT stop the container
when your script exits, and a leaked container keeps port 9998 occupied for
your next attempt:
docker run -d --rm --name tika-tmp -p 127.0.0.1:9998:9998 apache/tika:latest-full
until curl -sf http://localhost:9998/version >/dev/null; do sleep 1; done
curl -T document.pdf http://localhost:9998/tika
docker stop tika-tmp # --rm removes it on stop
docker ps --filter name=tika-tmp # verify: should list nothing
For many parses in a session, start it once and reuse it — the JVM warm-up cost is worth paying only once, not per file.
Troubleshooting
500with an empty body from/tikaor/rmeta: the response tells you nothing — go straight todocker logs <container>. A log line likeUnknown fetcher type: 'file-system-fetcher' ... Available types: []plus a pf4jNo 'plugins' rootwarning means the server can't find its plugins directory — a symptom of an outdated or hand-built image whose working directory isn't the distribution root. Official 4.0.0+ images set the working directory correctly; upgrade the image (workaround for a broken one: add--workdir /opt/tika-server).- Old metadata key spellings (
pdf:ocrPageCount,X-TIKA:*): image predates 4.0.0 — upgrade (see the OCR section). - Connection refused right after start: the JVM is still booting; poll
curl -sf http://localhost:9998/versionrather than sleeping a fixed time. - Permission denied reading a mounted file: the container runs as UID 35002 — see the mount section.
What's not built yet
There is no apache/tika-app image and no MCP mode for the Tika Docker
images as of this writing — the container always runs tika-server. If a
task specifically wants a stdio-spoken tool (MCP) rather than an HTTP server,
that isn't available through Docker today; use the file-to-markdown skill's
tika-app path directly on the host instead.
04 同仓库更多 Skills
file-to-markdown
Turn almost any file into Markdown plus metadata — PDF, Office, HTML, email, archives, images, audio/video, 1000+ formats — powered by Apache Tika, either via the tika-app CLI (zero setup, one file) or a running tika-server (curl, warm process, many calls). Leads with rmeta (structured, embedded-item-aware output) as the default operation rather than flat concatenated text, since you can't tell whether a file has embedded content from its extension. Covers metadata-only triage, type and language detection, OCR, and output-size discipline for agent context. Use whenever a task involves reading the content of a file whose format you don't want to hand-parse.
file-forensics
Examine what a file claims about itself and what it actually contains — powered by Apache Tika. True content-based type detection (extensions lie), provenance claims (authors, dates, creating application), revision and tamper signals (PDF incremental updates, tracked changes, hidden slides, zip integrity), hidden and embedded content (attachments, macros), risk indicators (PDF JavaScript actions, encryption), and content digests. Evidence gathering, not verdicts: Tika reports what the file asserts and what parsing observed; it does not attribute authorship or validate signatures. Use for triaging suspicious files, provenance questions, e-discovery-style review, or "is this file what it claims to be."
update-site-for-release
Update/publish the Apache Tika website (tika-site SVN repo) for a release — step 17 of the Release Process. Handles the 4.x track (Changes page + aggregate javadoc + Antora docs branch) vs the 3.x maintenance track (full per-version apt docs + javadoc). Use for "update the site", "publish the site for X.Y.Z", "the website part of the release".
tika-eval-h2-query
Query the tika-eval H2 database directly for counts and joins the canned reports do not compute — connection gotchas, key tables, example queries. Use when the xlsx/summary.md reports are not enough.
tika-eval-encoding-regression
Condensed tika-eval pattern for charset-detector regression hunts ("A picks encoding X, B picks Y") using one build and two configs — encoding-pair flip queries, OOV/languageness/FFFD signals, per-file detector attribution.
tika-eval-compare
Compare extracts from two Tika builds over a corpus to detect regressions in content, encoding, exceptions, and embedded-document handling. Use for "compare before/after extracts", "eval this change against the corpus".