AGENT SKILL

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

  • 500 with an empty body from /tika or /rmeta: the response tells you nothing — go straight to docker logs <container>. A log line like Unknown fetcher type: 'file-system-fetcher' ... Available types: [] plus a pf4j No 'plugins' root warning 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/version rather 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

apache
apache/tika

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.

文档处理图像与多媒体
★ 4.1k
apache
apache/tika

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."

文档处理
★ 4.1k
apache
apache/tika

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".

★ 4.1k
apache
apache/tika

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.

电子表格后端与接口
★ 4.1k
apache
apache/tika

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.

★ 4.1k
apache
apache/tika

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".

★ 4.1k