Paperless-ngx Supercharged: How to Automatically Convert and Index Office Documents with Apache Tika and Gotenberg

Paperless-ngx is hands down one of the most useful self-hosted services you can run on a home server. Out of the box, it handles PDFs and scanned images brilliantly—running OCR, applying tags, and making every invoice or tax letter searchable in seconds.

However, if you drop a Word document (.docx), an Excel spreadsheet (.xlsx), or a saved email (.eml) into your consume folder, a standard Paperless-ngx installation simply shrugs and ignores it. In real life, important documentation doesn’t always arrive as a clean PDF.

What does this mean for your setup? Instead of manually converting files before uploading them, you can extend Paperless-ngx with two lightweight sidecar containers: Apache Tika and Gotenberg. Together, they turn your instance into a true universal archive—completely local, automated, and easy to maintain in Docker.

How the Pipeline Works: Tika vs. Gotenberg

Before adding the containers to your stack, it helps to understand why Paperless-ngx needs both services rather than just one:

• Apache Tika (The Content Extractor): Tika analyzes non-PDF files (such as Word, Excel, PowerPoint, LibreOffice, and .eml files) and extracts their raw text and metadata so Paperless-ngx can index and search the content.
• Gotenberg (The PDF Converter): Gotenberg provides a stateless API around Chromium and LibreOffice. While Tika extracts the text for search, Gotenberg converts the original Office file or HTML email into a clean archival PDF so you can view it directly in the Paperless-ngx web interface.

Step 1: Extending Your Docker Compose Stack

If you are already running Paperless-ngx via docker compose or managing your stack in Portainer, integrating both services takes less than five minutes. You only need to add the gotenberg and tika service definitions and pass three environment variables to your webserver container.

Here is the clean configuration for your docker-compose.yml:

YAML

services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-webserver
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - paperless_data:/usr/src/paperless/data
      - paperless_media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_DBHOST=db
      - PAPERLESS_OCR_LANGUAGE=deu+eng
      # --- Enable Tika & Gotenberg Integration ---
      - PAPERLESS_TIKA_ENABLED=true
      - PAPERLESS_TIKA_ENDPOINT=http://tika:9998
      - PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.7
    container_name: paperless-gotenberg
    restart: unless-stopped
    # The chromium route is used to convert .eml files. We disable
    # javascript and local file access for security.
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    container_name: paperless-tika
    restart: unless-stopped

(Note: Make sure to keep your existing db and broker services in the file as well.)

Apply the changes from your terminal or redeploy the stack in Portainer:

Bash

docker compose up -d

Notice that neither gotenberg nor tika needs a ports: mapping to the host. Because they share the internal Docker network with paperless-webserver, communication happens strictly container-to-container.

Step 2: Verifying the Setup

Once the containers are up and running, test the pipeline:

1. Drop a .docx or .xlsx test file into your consume folder (or upload it via drag-and-drop in the Web UI).
2. Watch the task queue in Paperless-ngx. Behind the scenes, the consumer sends the file to Gotenberg to render a PDF copy and simultaneously queries Tika to extract the text layer.
3. Open the processed document in Paperless-ngx. You now have both the rendered PDF view in the browser and the original .docx file preserved for download.

If a conversion fails, you can check the container logs directly to see whether Gotenberg or Tika threw an error:

Bash

docker logs -f paperless-gotenberg
docker logs -f paperless-tika

Practical Tips for Daily Operation

To keep your server running smoothly over the long haul, keep these three points in mind:

• Pin the Gotenberg Version: Unlike many containers where :latest is fine for homelab use, Gotenberg introduces breaking CLI flag changes between major versions (such as moving from v7 to v8). Pinning the image to a specific minor release like gotenberg/gotenberg:8.7 prevents surprise startup failures after a container update.
• Watch Your RAM Usage: Both Tika (Java-based) and Gotenberg (which spins up headless LibreOffice and Chromium instances during conversion) need a bit of breathing room. Expect around 500 MB to 1 GB of additional RAM usage during active document processing.
• Archiving .eml Emails Cleanly: By passing --chromium-disable-javascript=true to Gotenberg, HTML emails exported from your mail client are rendered safely into clean PDFs without executing external tracking scripts.

Conclusion

All in all, adding Apache Tika and Gotenberg removes the last major friction point in Paperless-ngx. You no longer have to think about file formats before archiving—whether it is a scanned receipt, a contract draft in Word, or an important email, your server handles the conversion and indexing automatically inside your local network.

What’s your take on this? Are you running Paperless-ngx solely for PDFs, or have you already integrated Office and email pipelines into your archive?