Docker & Kubernetes Deployment

In 4.x every parsing endpoint of tika-server (/tika, /rmeta, /meta, /unpack, /detect) runs its work in a forked JVM managed by Tika Pipes. So one container is not one JVM: it is a light parent JVM that owns the HTTP ports, and up to pipes.numClients forked JVMs that parse one document each at a time. A document that crashes, exhausts memory or times out kills one fork; the request gets a 503, the fork is restarted, and the parent stays up. That model drives most of this page: the container memory and CPU limits must cover the forks, not just the parent.

The figure shows the Kubernetes deployment built at the end of the page: two replicas of a pod with 8 CPUs and 8 GiB, each running three forks with a 1.5 GB heap. The same shape applies to a single docker run on a laptop, with the container limits playing the role of the pod limits.

Source: Apache Tika 4.1.x, Tika Server and Apache Tika 4.1.x, Forked-JVM CPU and Heap Sizing.

The project publishes two repositories on Docker Hub: apache/tika (the REST server, port 9998, in a minimal and a -full variant) and apache/tika-grpc (the gRPC server, port 9090). Since 4.0.0-alpha-1 the Dockerfiles live in the main source tree, under tika-server/docker-build/ and tika-grpc/docker-build/; the older apache/tika-docker repository still builds 3.x patch images and its README still describes the pre-4.x tags.

Which one for Bookshelf? The intake service receives scanned-loan-form.pdf and book-cover.jpg, which need OCR, so it runs -full. A deployment that only receives born-digital files (manuscript.docx, catalogue.pdf, novel.epub, reviews-es.html) should take the minimal image: a third of the size, a smaller attack surface, and nothing that shells out to native programs. Choose -full when you OCR scanned documents, parse geospatial rasters with GDAL, or feed audio and video to a MEDIA inference binding (ffmpeg); see OCR with Tesseract and VLM Parsers & Inference. Choose apache/tika-grpc only when your clients speak gRPC; it is a different server with its own configuration, covered in Tika gRPC.

OMP_THREAD_LIMIT=1 in the -full and gRPC images stops each Tesseract process from starting one OpenMP thread per core. With several forks each running OCR, unlimited OpenMP threads would oversubscribe the CPU the same way unlimited GC threads do (see Memory and CPU inside a container). Keep it unless you have measured a reason not to.

If none of the variants fits (for example you need Tesseract language packs the -full image does not install), build your own image FROM one of them rather than from scratch. The full/Dockerfile accepts a LANGUAGES build argument for the Tesseract packs, but it downloads the signed release zip from an Apache mirror and verifies it against the project KEYS file, so it builds only released versions, never your working tree.

The USER root / USER 35002:35002 pair matters: the base image ends with USER 35002:35002, so apt-get would fail without switching, and forgetting to switch back would run your image as root. This Dockerfile was not built for this page; the package names are the Ubuntu ones the official full/Dockerfile composes from its LANGUAGES argument.

Source: Apache Tika 4.1.x, Running Tika in Docker, tika-server/docker-build at 4.1.0, tika-grpc/docker-build at 4.1.0 and Docker Hub, apache/tika.

Starting with 4.0.0-alpha-1 every image is published under three kinds of tag:

Snapshot tags (4.2.0-SNAPSHOT, 4.1.1-SNAPSHOT and their -full twins) are rebuilt from development branches and must not be deployed either.

On the baseline date Docker Hub showed these tags for 4.1.0, all published on 29 September 2026:

So latest now points at 4.1.0. The README of the old apache/tika-docker repository still says latest tracks the 3.x line; that text predates 4.0.0 and is no longer true.

For a reproducible deployment pin the immutable tag and the digest. The tag documents intent for humans, the digest is what the runtime actually checks:

To read the same metadata without pulling, ask the registry for the manifest. docker buildx imagetools inspect prints the platforms and digests; the configuration (user, entry point, environment) is in the image config:

These two commands were not run here; the values on this page were read with plain HTTP calls to the Docker Hub tag API and to registry-1.docker.io (token, image index, manifest, config blob), which is what those commands do.

Platforms. apache/tika 4.x is published for linux/amd64, linux/arm64 and linux/s390x, and docker pull picks the right one, so the same tag works on an x86 build server, an Apple Silicon laptop and an AWS Graviton node. apache/tika-grpc is published for linux/amd64 and linux/arm64 only. 32-bit ARM (linux/arm/v7) was dropped: on Docker Hub the last tag that carries it is 3.3.0.0.

The 3.x line uses a different scheme: four-part tags <tika-version>.<docker-build> such as 3.3.1.0 and 3.3.1.0-full, still built from apache/tika-docker. On the baseline date the newest 3.x image was 3.3.1.0 (27 May 2026); there was no image for 3.3.2 on Docker Hub, although 3.3.2 was released on 16 July 2026. If you must stay on 3.x, build your own image from the 3.3.2 zip or accept 3.3.1, and read Security before choosing.

Source: tika-server/docker-build/CHANGES.md at 4.1.0, Docker Hub, apache/tika, Docker Hub, apache/tika-grpc and apache/tika-docker. For tag and digest mechanics in general, see Images, Layers and Tags and Registries and Docker Hub.

Everything you mount or override has to fit this layout. The values below come from the apache/tika:4.1.0-1 and 4.1.0-1-full image configurations and from the tika-server-standard-4.1.0.zip that the Dockerfile unzips:

Three consequences:

What a container actually runs looks like this. The process list below comes from the local run that reproduced the entry point, with the paths rewritten to the container layout; the forked JVMs read most of their arguments from an @-file in their temp directory:

Source: Apache Tika 4.1.x, Running Tika in Docker, What is inside, the minimal Dockerfile at 4.1.0 and the image configuration of apache/tika:4.1.0-1 on Docker Hub.

The smallest useful run publishes the port on the loopback interface only:

Output (from the local run of the same 4.1.0 distribution with the image’s classpath, no configuration file):

In 4.x the output format is chosen by the path (/tika/text, /tika/md, /tika/xml), not by an Accept header; see Tika Server (REST API).

The startup log shows what the server decided, which is the first thing to check after deploying:

On a host with 8 cores and no configuration, the server chose three forks, gave each fork a view of 2 CPUs, and capped each fork’s heap at 25% of the memory the JVM can see. Inside a container "the memory the JVM can see" is the container limit; without a limit it is the whole host, which is how three forks plus the parent can each believe they may take a quarter of a 64 GB node. Always set --memory and --cpus (or the Compose and Kubernetes equivalents):

--read-only with a tmpfs at /tmp works because /tmp is the only place the server writes. A tmpfs lives in RAM and counts towards the container memory, so size it to the uploads you accept (maxRequestSizeBytes) times the requests in flight, or mount a volume at /tmp instead.

Source: Apache Tika 4.1.x, Running Tika in Docker and Apache Tika 4.1.x, Tika Server, Basic Usage. For the docker run flags, see Running Containers and Docker Security.

Mount the file read-only and point the server at it with -c, after the image name:

The Bookshelf intake configuration used by the Compose file below:

What each part does in a container:

This file was loaded by the local 4.1.0 server, which parsed catalogue.pdf and manuscript.docx through /tika, /rmeta/text and /meta with it, and logged:

(slice=3 because the test host had 8 cores, not the 6 the Compose file grants.)

Points that bite in containers:

3.x images expect the XML format instead, with the fork settings inside <server>. The rough 3.x equivalent of the fork settings above (3.3.x, for comparison only):

Source: Apache Tika 4.1.x, Running Tika in Docker, Configuration, Apache Tika 4.1.x, Tika Server, Configuration, Apache Tika 4.1.x, Pipes Configuration and, for the 3.x form, tika-server-core/src/test/resources/configs/tika-config-server.xml at the 3.3.2 tag of apache/tika.

Mount a directory of jars at /tika-extras. It is already on the parent’s classpath, and Tika forwards it to the forked JVMs:

Typical contents are an optional component that the standard package leaves out (a tika-eval metadata filter, an extra parser module), an optional dependency such as jai-imageio-jpeg2000 (check its licence first), or your own component, for example the Bookshelf shelf-code metadata filter written in Configuration and the custom parsers of Extending Tika. Components registered through SPI or @TikaComponent are found the same way as on the plain zip, where the equivalent is the tika.extras.dir system property.

For production, bake the jars into your own image instead of mounting them, so the code that runs is versioned with the image digest:

COPY creates /tika-extras owned by root with world-readable files, which is what you want: UID 35002 can read the jars but not replace them. Treat this directory as trusted code: anything in it runs with the full privileges of the Tika process, in the parent and in every fork. Never make it writable by the server, by request handling, or by a less trusted team.

Jars on /tika-extras share one classpath with lib/. A jar that brings its own copy of POI, PDFBox, Jackson or Log4j will clash with the versions in lib/; ship only the component and the dependencies that lib/ does not already contain. See Setup & Installation for the dependency-clash discussion.

This page did not mount a real extras directory; the forwarding to forks is stated by the 4.1.x Docker page.

Source: Apache Tika 4.1.x, Running Tika in Docker, Extra jars and Apache Tika 4.1.x, Configuration.

The synchronous endpoints need no plugins. /pipes and /async (enabled with allowPipes), and the pipes-mode tika-app and tika-grpc, need the fetcher, emitter, iterator or reporter plugins for whatever they talk to. Plugins are pf4j plugins, one directory each, discovered under /opt/tika-server/plugins/. The image bundles only tika-pipes-file-system, whose directory shows the layout every plugin has:

The other 4.1.0 plugins are published as zips next to the release on the Apache download site (https://downloads.apache.org/tika/4.1.0/): tika-pipes-s3, tika-pipes-gcs, tika-pipes-az-blob, tika-pipes-http, tika-pipes-es, tika-pipes-opensearch, tika-pipes-solr, tika-pipes-jdbc, tika-pipes-kafka, tika-pipes-csv, tika-pipes-json, tika-pipes-google-drive, tika-pipes-microsoft-graph and tika-pipes-atlassian-jwt, each as <name>-4.1.0.zip. The jars on Maven Central are not the plugin packaging. The container cannot expand a zip in place, because /opt/tika-server is root-owned while the server runs as UID 35002, so unzip on the host and mount the directory:

Or bake it into an image, which is the better choice for Kubernetes:

The S3 zip is about 15.6 MB and the Elasticsearch one about 3 MB (from the download server’s Content-Length). They were not downloaded for this page, so whether a zip contains a top-level directory was not checked: run unzip -l first and make sure plugin.properties lands directly under plugins/<name>/. The plugin configuration itself, and the allowPipes gate, are explained in Tika Pipes and Tika Server (REST API).

Plugins are code too. The same trust rule as for /tika-extras applies.

Source: Apache Tika 4.1.x, Running Tika in Docker, Pipes plugins and Apache Tika 4.1.x, Pipes Plugins.

On JDK 17 and later the JVM reads the cgroup limits of its container: Runtime.availableProcessors() returns the CPU limit (--cpus, resources.limits.cpu) and the default heap is a fraction of the memory limit. Tika builds on that and sizes the forks from the same numbers. The rules, verified in the 4.1.0 source (PipesConfig, PerClientServerManager) and in the local runs:

The arithmetic, then, for a container with memory M and n forks:

A worked budget for the Bookshelf Kubernetes pod (8 CPUs, 8 GiB):

The official guidance suggests about 2 GB of heap per fork as a starting point for mixed corpora with pathological PDFs; Bookshelf uses 1.5 GB because its intake rejects files over 100 MB. Measure the post-GC live heap of your own corpus with -Xlog:gc* and set -Xmx to about 1.5 times that.

tika-server has no authentication. Anyone who can reach port 9998 can make it parse arbitrary bytes, and Tika parses untrusted input by design. Keep it reachable only by the services that need it.

Source: Apache Tika 4.1.x, Running Tika in Docker, Apache Tika 4.1.x, Monitoring with Prometheus and Apache Tika 4.1.x, Security. For Docker networking itself, see Networking.

The intake service (a Spring Boot 4 application, built from its own Dockerfile) talks to tika-server over a private network. The layout:

compose.yaml:

Notes on the choices:

Validate and start:

docker compose config -q passed on this file with Compose v5.5.1. The stack was not started for this page; the curl output is the one shown in Running a container. Inside the intake service, the client calls ${TIKA_URL}/rmeta/text with a PUT and treats 429 as "retry after the Retry-After delay" and 503 as "this file broke a fork, quarantine it"; Tika Server (REST API) shows the Java client.

The tika-server/docker-build/ directory of the source tree also has three worked Compose files: docker-compose-tika-vision.yml (a VLM parser against a local Ollama server), docker-compose-tika-grobid.yml and docker-compose-tika-customocr.yml, with their configurations under sample-configs/.

Source: Apache Tika 4.1.x, Running Tika in Docker, Docker Compose and tika-server/docker-build at 4.1.0. For Compose itself, see Docker Compose Fundamentals, Compose for Local Development and Storage: Volumes, Bind Mounts and tmpfs.

The manifests below run tika-server for the Bookshelf intake service in the bookshelf namespace: a ConfigMap with the configuration, a Deployment of two pods, a Service, a PodDisruptionBudget, a NetworkPolicy and a ServiceMonitor. They were written for Kubernetes 1.30 or later (the sleep pre-stop action) and parsed as YAML, but not applied to a cluster.

The threat model behind these items (why a parser is an attack surface, the XXE CVEs of 2025, what the forks do and do not protect against) is in Security.

Tika in Action (2011) was written for Tika 1.0, before container images existed; its advice to run Tika as a separate server process still holds, and 4.x makes the isolation per document instead of per server. The full list of server changes is in Tika Server (REST API).

Source: tika-server/docker-build/CHANGES.md at 4.1.0, apache/tika-docker README and CHANGES and Apache Tika 4.1.x, Migrating Tika Server to 4.x.

Verified for this page:

Not verified: