How To Set Up Stirling PDF In Your Home Lab For Use With AI Agents

Outcome

Deploy Stirling PDF as a local PDF service that AI agents can use to create PDFs, OCR scanned files, and extract text through an HTTP API.

Audience and Scope

Audience	First-time home lab users who want a beginner-friendly setup path
Difficulty	Beginner
Estimated Time	20 to 30 minutes
Assumptions	You have Docker, Docker Compose support, terminal access to your Docker host, and an existing Docker network named `llmnet`

Before You Start

Confirm Docker is installed and running.
Confirm Docker Compose is available.
Choose a persistent folder for the Stirling PDF stack.
Confirm the Docker network below already exists.

llmnet

Hardware and Software

Hardware

A Docker host on your local network
Enough disk space for OCR data, logs, and PDFs

Software

Docker
Docker Compose
Stirling PDF container image

Step-by-Step

Step 1: Create a working folder

Objective: Create a clean folder for the Stirling PDF deployment.

Actions:

mkdir -p ~/docker/stirling-pdf
cd ~/docker/stirling-pdf

Verification: Your shell should now be in the new working directory.

Common failure and fix: If the folder path is wrong, remove it and recreate it in the location you want to keep long-term.

Step 2: Create the Compose file

Objective: Define the Stirling PDF container and its persistent storage.

Actions: Create this file:

docker-compose.yml

Use this baseline:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
    environment:
      - SECURITY_ENABLELOGIN=false
      - LANGS=en_US
    restart: unless-stopped

Verification: Save the file and confirm the YAML indentation is intact.

Common failure and fix: If Docker Compose reports a YAML parse error, recheck spaces and list indentation in the file.

Step 3: Create the data folders

Objective: Create the folders that will hold OCR data, settings, logs, and pipeline files.

Actions:

mkdir -p stirling-data/tessdata
mkdir -p stirling-data/configs
mkdir -p stirling-data/logs
mkdir -p stirling-data/pipeline

Verification: Confirm all four folders exist in your working directory.

Common failure and fix: If the container starts without these folders, create them and restart the container.

Step 4: Add OCR language files

Objective: Populate the OCR language directory so mounted storage does not hide the container’s OCR files.

Actions: Download the minimum English OCR files:

cd stirling-data/tessdata
curl -fsSLO https://github.com/tesseract-ocr/tessdata_fast/raw/main/eng.traineddata
curl -fsSLO https://github.com/tesseract-ocr/tessdata_fast/raw/main/osd.traineddata

Minimum file set:

eng.traineddata
osd.traineddata

Verification: Confirm both files are present before starting the container.

Common failure and fix: If OCR later fails with language errors, re-download the files into the mounted OCR directory.

Step 5: Start Stirling PDF

Objective: Launch the service and confirm the container is running.

Actions:

docker compose up -d

Check the container:

docker ps --filter name=stirling-pdf

Verification: The stirling-pdf container should appear in the output.

Common failure and fix: If the container exits immediately, inspect the logs and verify the volume paths and YAML content.

Step 6: Open the web interface

Objective: Confirm the web UI is reachable.

Actions: Open the web UI in your browser:

http://YOUR_DOCKER_HOST:8080/

If you are testing on the same machine, you can also use:

http://127.0.0.1:8080/

Verification: The Stirling PDF interface should load in your browser.

Common failure and fix: If the page does not load, confirm the container is running and that port 8080 is not blocked or already in use.

Step 7: Verify the API

Objective: Confirm Stirling PDF exposes the API schema that AI tools can use.

Actions:

curl -fsS http://YOUR_DOCKER_HOST:8080/v1/api-docs >/dev/null && echo openapi_ok

Use this schema path:

/v1/api-docs

Do not use this path for this deployment:

/v3/api-docs

Verification: The command should print openapi_ok.

Common failure and fix: If the API check fails, verify the container is healthy and that you are using the correct schema path.

Step 8: Test a basic AI workflow

Objective: Validate the three core AI-agent tasks: create a PDF, OCR it, and extract text.

Actions: Useful API routes:

POST /api/v1/convert/img/pdf
POST /api/v1/misc/ocr-pdf
POST /api/v1/convert/pdf/text
GET  /v1/api-docs

Example OCR request:

curl -X POST http://YOUR_DOCKER_HOST:8080/api/v1/misc/ocr-pdf 
  -F "fileInput=@scan.pdf" 
  -F "languages=eng" 
  -o scan-searchable.pdf

Example text extraction request:

curl -X POST http://YOUR_DOCKER_HOST:8080/api/v1/convert/pdf/text 
  -F "fileInput=@scan-searchable.pdf" 
  -F "outputFormat=txt" 
  -o scan.txt

Verification: You should be able to OCR a scanned file and extract readable text from the result.

Common failure and fix: If OCR succeeds but text extraction is empty, verify the OCR output file was created and the input file is actually image-based.

Step 9: Connect AI agents

Objective: Point your AI tools at the Stirling PDF API.

Actions: Direct base URL:

http://YOUR_DOCKER_HOST:8080

OpenAPI discovery URL:

http://YOUR_DOCKER_HOST:8080/v1/api-docs

Verification: Your AI client should be able to discover the schema or call the endpoints directly.

Common failure and fix: If the AI client cannot see the service, confirm the host, port, and any internal gateway configuration.

Validation Checklist

The stirling-pdf container is running.
The web UI opens in a browser.
The OpenAPI document responds.
OCR works with at least one installed language.
You can extract text from a searchable PDF.

Operations and Maintenance

Keep OCR language files in sync with the languages you actually need.
Review container image updates before upgrading production or shared AI workflows.
Add authentication and proxy hardening after the base workflow is working.

Troubleshooting and Rollback

OCR fails with language errors: your mounted OCR folder is empty or missing the required language files.

eng.traineddata
osd.traineddata

The UI loads but API calls fail: verify the service responds on the schema path below.

/v1/api-docs

The container keeps restarting: inspect the container logs.

docker logs stirling-pdf

Rollback: Stop the stack if you need to back the deployment out.

docker compose down

Source Links

My Implementation Notes

This public guide stays beginner-friendly and generic. Internal Home Lab documentation can be more specific about local paths, gateway routes, hostnames, and operational decisions for one environment.