Stirling-PDF Administrator & Developer Guide

Stirling-PDF is a self-hosted, enterprise-capable PDF manipulation platform built on a multi-module architecture spanning Java (Spring Boot), TypeScript (React/Mantine), Rust (Tauri), and Python (FastAPI). This guide covers every operational and development concern for administrators, DevOps engineers, and contributors working with Stirling-PDF version 2.9.2.

1. Architecture Overview

Stirling-PDF follows a modular monorepo structure with four distinct runtime components that can be deployed together or independently.

1.1 Component Map

┌─────────────────────────────────────────────────────────────┐
│                     Stirling-PDF v2.9.2                      │
├──────────────┬──────────────┬───────────────┬───────────────┤
│   Backend    │   Frontend   │    Desktop    │   AI Engine   │
│ Spring Boot  │ React/Vite   │  Tauri/Rust   │ Python/FastAPI│
│  4.0.5       │ Mantine UI   │              │  pydantic-ai  │
│  Java 21     │ TypeScript   │              │              │
├──────────────┼──────────────┼───────────────┼───────────────┤
│  app/common  │ frontend/src │ frontend/    │ engine/src/   │
│  app/core    │   /core      │  src-tauri/  │  stirling/    │
│  app/        │   /proprietary│             │   api/        │
│  proprietary │   /saas      │              │   agents/     │
│              │   /desktop   │              │              │
└──────────────┴──────────────┴───────────────┴───────────────┘

1.2 Backend Modules

The Spring Boot backend is split into three Gradle subprojects:

The application entry point is stirling.software.SPDF.SPDFApplication. The embedded servlet container is not Tomcat — the build explicitly excludes spring-boot-starter-tomcat in favor of Jetty/Undertow.

1.3 Frontend Architecture

The React frontend uses Vite as the build tool and is organized into four feature domains:

Note

The frontend uses PDFium compiled to WebAssembly for client-side PDF rendering and manipulation. This means many operations execute entirely in the browser without round-tripping to the backend.

1.4 Desktop Application (Tauri)

The desktop app wraps the React frontend in a native Rust shell (frontend/src-tauri/). Tauri commands expose:

• Auth: save/get/clear tokens for enterprise auth
• Backend management: spawn, monitor, and manage a local backend process
• Connection modes: local backend, remote server, or hybrid
• File handling: native file dialogs, drag-and-drop, default PDF handler registration
• Native print: OS-level print integration
• Platform detection: Windows/macOS/Linux-specific behavior

A Windows thumbnail handler DLL (stirling_thumbnail_handler.dll) implements the COM IThumbnailProvider interface, enabling PDF preview thumbnails directly in Windows Explorer. A provisioner tool supports enterprise deployment by locking the server URL in configuration.

1.5 AI Engine

The Python FastAPI service (engine/src/stirling/api/app.py) provides AI-powered PDF operations using pydantic-ai:

API routes: /draft, /revise, /next-action, /examine, /deliberate, /orchestrate, /pdf_edit, /pdf_questions, /health.

1.6 Dependency Stack

2. Requirements & Prerequisites

2.1 Hardware Requirements

2.2 Software Requirements

For Docker deployment (recommended):

• Docker Engine 20.10+
• Docker Compose v2

For bare-metal / development:

• Java 21 JDK (compilation requires Java 25 toolchain)
• Node.js (for frontend build)
• Gradle (wrapper included)
• Optional external tools: LibreOffice, qpdf, Ghostscript, Tesseract OCR, OpenCV, Python 3.x, unoconvert

Important

The fat Docker image bundles all external tools. The standard image requires you to install LibreOffice, Tesseract, and other CLI tools separately if you need endpoints that depend on them. The ultra-lite image intentionally excludes all external dependencies.

3. Configuration Mastery

3.1 settings.yml

The primary configuration file is mounted at /configs/settings.yml inside the container. It controls all runtime behavior. Configuration keys map to Spring properties via relaxed binding.

3.2 Environment Variables — Complete Reference

All configuration can be set via environment variables, which override settings.yml values.

System Configuration

Security Configuration

UI Configuration

Container & Process Configuration

Feature Toggles

OCR & Language Configuration

Storage Configuration

LibreOffice / UNO Server Configuration

AI Engine Configuration

Tip

For resource-constrained environments, set STIRLING_JVM_PROFILE=balanced and PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT=1 to prevent LibreOffice from consuming excessive memory during concurrent conversions.

3.3 Volume Mounts

4. Deployment

4.1 Docker Images

Stirling-PDF provides four Dockerfile variants targeting different use cases:

4.2 Standard Deployment (Docker Compose)

version: "3.8"
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./customFiles:/customFiles
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - SYSTEM_MAXFILESIZE=100
      - SYSTEM_DEFAULTLOCALE=en-US
    restart: unless-stopped

4.3 Fat Docker Deployment

version: "3.8"
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest-fat
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./tessdata:/usr/share/tessdata
      - ./pipeline:/pipeline
    environment:
      - FAT_DOCKER=true
      - TESSERACT_LANGS=eng,fra,deu,spa
      - SYSTEM_MAXFILESIZE=500
    restart: unless-stopped

Note

The fat image bundles LibreOffice, Tesseract, qpdf, Ghostscript, OpenCV, and Python. Set FAT_DOCKER=true so the endpoint configuration system knows all tool dependencies are satisfied.

4.4 Ultra-lite Deployment

version: "3.8"
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest-ultra-lite
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
    environment:
      - DISABLE_ADDITIONAL_FEATURES=true
    restart: unless-stopped

The ultra-lite image supports only Java-native PDF operations: merge, split, rotate, rearrange, remove pages, add watermark, encrypt/decrypt, metadata editing, flatten, and similar operations that use PDFBox directly without external CLI tools.

4.5 Unified Container — Split Frontend/Backend

The unified Dockerfile supports three operating modes via the MODE environment variable:

Mode: BOTH (default) — runs frontend and backend in a single container:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:unified
    environment:
      - MODE=BOTH
      - BACKEND_INTERNAL_PORT=8081
    ports:
      - "8080:8080"

Mode: FRONTEND — serves only the React UI, proxying API calls to a separate backend:

services:
  frontend:
    image: stirlingtools/stirling-pdf:unified
    environment:
      - MODE=FRONTEND
      - VITE_API_BASE_URL=http://backend:8080
    ports:
      - "3000:3000"

Mode: BACKEND — runs only the Spring Boot API:

services:
  backend:
    image: stirlingtools/stirling-pdf:unified
    environment:
      - MODE=BACKEND
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs

Full split deployment example:

version: "3.8"
services:
  backend:
    image: stirlingtools/stirling-pdf:unified
    environment:
      - MODE=BACKEND
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./tessdata:/usr/share/tessdata

  frontend:
    image: stirlingtools/stirling-pdf:unified
    environment:
      - MODE=FRONTEND
      - VITE_API_BASE_URL=http://backend:8080
    ports:
      - "3000:3000"
    depends_on:
      - backend

Important

When using MODE=FRONTEND, the VITE_API_BASE_URL must be set at build time or via the unified container's entrypoint script. This URL is baked into the frontend JavaScript bundle. Changing it requires a container restart.

4.6 Remote UNO Server (Scalable LibreOffice)

For high-throughput document conversion, deploy LibreOffice as remote UNO servers to distribute the load:

version: "3.8"
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    environment:
      - PROCESS_EXECUTOR_AUTO_UNO_SERVER=false
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST=uno-server-1
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_PORT=2003
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_HOST_LOCATION=remote
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_0_PROTOCOL=http
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST=uno-server-2
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_PORT=2003
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_HOST_LOCATION=remote
      - PROCESS_EXECUTOR_UNO_SERVER_ENDPOINTS_1_PROTOCOL=http
    volumes:
      - shared-tmp:/tmp/stirling-pdf
    ports:
      - "8080:8080"

  uno-server-1:
    image: libreoffice-uno-server:latest
    volumes:
      - shared-tmp:/tmp/stirling-pdf

  uno-server-2:
    image: libreoffice-uno-server:latest
    volumes:
      - shared-tmp:/tmp/stirling-pdf

volumes:
  shared-tmp:

Warning

Remote UNO servers require a shared /tmp/stirling-pdf volume between the Stirling-PDF container and all UNO server containers. Without this shared filesystem, file-to-pdf and other LibreOffice-dependent conversions will fail silently because the UNO server cannot access the temporary files created by Stirling-PDF.

Key configuration:

• Set PROCESS_EXECUTOR_AUTO_UNO_SERVER=false to disable the local UNO server
• Configure each remote endpoint with incrementing index (_0_, _1_, etc.)
• Set HOST_LOCATION=remote for each remote endpoint
• Use PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT to cap concurrent sessions per server

4.7 Reverse Proxy Configuration

When deploying behind a reverse proxy (Nginx, Traefik, Caddy), set SYSTEM_ROOTURIPATH to match the proxy's path prefix.

Nginx example (subpath):

location /stirling-pdf/ {
    proxy_pass http://stirling-pdf:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100M;  # Match SYSTEM_MAXFILESIZE
}

With environment: SYSTEM_ROOTURIPATH=/stirling-pdf

Traefik example (subdomain):

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.stirling.rule=Host(`pdf.example.com`)"
  - "traefik.http.routers.stirling.tls.certresolver=letsencrypt"
  - "traefik.http.services.stirling.loadbalancer.server.port=8080"

4.8 Health Check

The container health check endpoint:

curl -f http://localhost:8080${SYSTEM_ROOTURIPATH:-''}/api/v1/info/status | grep -q 'UP'

Docker Compose health check configuration:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

5. Endpoint Configuration System

The EndpointConfiguration class (in app/common) is the central mechanism for controlling which PDF operations are available at runtime. It evaluates three factors: explicit configuration, external tool availability, and group membership.

5.1 Functional Groups

Endpoints are organized into functional groups. Disabling a group disables all its member endpoints:

5.2 Tool Groups (External Dependencies)

Each tool group maps endpoints to the external binary they require:

5.3 Disable Reasons

When an endpoint is unavailable, the system reports one of three reasons:

5.4 Endpoint Alternatives

Some endpoints support multiple backends. For example, file-to-pdf can use either LibreOffice or Unoconvert. If one tool is missing, the system falls back to the alternative if available.

5.5 Disabling Endpoints

Disable entire functional groups:

# In settings.yml
endpoints:
  groupsToRemove:
    - CLI
    - Python

Or via environment variable:

ENDPOINTS_GROUPS_TO_REMOVE=CLI,Python

Disable all external-tool features at once:

DISABLE_ADDITIONAL_FEATURES=true

Disable individual endpoints in settings.yml:

endpoints:
  disabled:
    - ocr-pdf
    - compress-pdf

6. Security

6.1 Authentication Modes

Stirling-PDF supports multiple authentication mechanisms, all gated behind the DOCKER_ENABLE_SECURITY=true master switch:

Caution

Setting SECURITY_CUSTOMGLOBALAPIKEY creates a single shared API key for all API access. This is convenient for automation but bypasses per-user audit trails. In production, prefer per-user API keys issued through the user management system.

6.2 CSRF Protection

Spring Security CSRF protection is enabled by default when security is active. API endpoints that accept the X-API-KEY header bypass CSRF checks (they are stateless by nature).

6.3 User & Role Management

The proprietary module provides:

• User creation, modification, deletion
• Role-based access control
• Session management (timeout, concurrent session limits)
• Audit logging of user actions

6.4 Security Hardening Checklist

[ ] Set DOCKER_ENABLE_SECURITY=true
[ ] Enable login: SECURITY_ENABLELOGIN=true
[ ] Configure OAuth2 or SAML2 for SSO
[ ] Set per-user API keys (avoid global key in production)
[ ] Enable MFA for admin accounts
[ ] Set SYSTEM_MAXFILESIZE to prevent abuse
[ ] Deploy behind reverse proxy with TLS
[ ] Set SYSTEM_GOOGLEVISIBILITY=false to prevent indexing
[ ] Mount /configs read-only if settings won't change at runtime
[ ] Review audit logs regularly

7. Operations

7.1 JVM Tuning

Two JVM profiles are available via STIRLING_JVM_PROFILE:

Additional tuning via JAVA_CUSTOM_OPTS:

# Example: increase heap for large PDF processing
JAVA_CUSTOM_OPTS="-Xmx4g -Xms2g -XX:+HeapDumpOnOutOfMemoryError"

7.2 Logging

Application logs are written to the /logs volume mount. Configure log levels via Spring Boot properties in settings.yml or environment variables.

For the AI engine, use STIRLING_LOG_LEVEL and optionally STIRLING_LOG_FILE.

7.3 Metrics

When METRICS_ENABLED=true (default), Stirling-PDF exposes Prometheus-compatible metrics. Integrate with Grafana for dashboarding:

# prometheus.yml scrape config
- job_name: 'stirling-pdf'
  metrics_path: '/actuator/prometheus'
  static_configs:
    - targets: ['stirling-pdf:8080']

7.4 Backup & Restore

Critical data to back up:

7.5 Scaling Considerations

Horizontal scaling is supported via the unified container's split mode:

                    ┌─── Frontend (MODE=FRONTEND) ──┐
Load Balancer ──────┤                                ├──► Backend Pool
                    └─── Frontend (MODE=FRONTEND) ──┘     (MODE=BACKEND)
                                                          ├── instance-1
                                                          ├── instance-2
                                                          └── instance-3

Tip

LibreOffice is the primary bottleneck in high-throughput deployments. Use remote UNO servers (Section 4.6) to scale document conversion independently from the core PDF operations. Set PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT to prevent a single instance from being overwhelmed.

7.6 OCR Language Management

Tesseract OCR languages are installed via TESSERACT_LANGS:

# Install multiple languages
TESSERACT_LANGS=eng,fra,deu,spa,ita,por,jpn,chi_sim,chi_tra,kor,ara

# Mount custom/additional traineddata files
volumes:
  - ./tessdata:/usr/share/tessdata

Language data files (.traineddata) can be downloaded from the tessdata repository and placed in the mounted volume.

8. Developer Reference

8.1 Build System

The project uses Gradle with the Spring Boot plugin:

# Build everything
./gradlew build

# Build backend only
./gradlew :app:core:build

# Run locally
./gradlew bootRun

# Run with specific profile
./gradlew bootRun --args='--spring.profiles.active=dev'

Build configuration:

• Java source/target: Java 21
• Compilation toolchain: Java 25
• Code formatter: Spotless (google-java-format 1.28.0)
• Code coverage: JaCoCo
• Static analysis: SonarQube integration
• License compliance: dependency-license-report plugin

Version sync: The syncAppVersion Gradle task synchronizes the version number across tauri.conf.json and simulation configuration files.

8.2 Frontend Build

cd frontend

# Install dependencies
npm install

# Development server
npm run dev

# Production build
npm run build

# Run tests
npm run test        # Vitest unit tests
npm run test:e2e    # Playwright E2E tests

8.3 AI Engine Development

cd engine

# Install dependencies
pip install -r requirements.txt

# Run locally
uvicorn stirling.api.app:app --reload --port 8000

# Run tests
pytest tests/

8.4 Code Formatting

Spotless enforces google-java-format 1.28.0:

# Check formatting
./gradlew spotlessCheck

# Auto-fix formatting
./gradlew spotlessApply

Note

The Spotless check runs as part of the build pipeline. Pull requests with formatting violations will fail CI. Run spotlessApply before committing.

9. Module Reference

9.1 Backend — app/common

Shared library consumed by both core and proprietary:

9.2 Backend — app/core

The core module contains all PDF operation implementations:

Controllers (app/core/src/main/java/stirling/software/SPDF/controller/api/): 19 controller files totaling ~201K characters of endpoint logic. Controllers are organized by functional domain (page operations, conversions, security, etc.) and delegate to service classes that use PDFBox for manipulation.

Configuration (app/core/.../config/): 19 configuration files handling Spring context setup, bean definitions, security filter chains, CORS, multipart file upload limits, and static resource serving.

Entry Point: stirling.software.SPDF.SPDFApplication — the @SpringBootApplication main class.

9.3 Backend — app/proprietary

Enterprise features under separate license:

9.4 Frontend Services

Page Editor Commands (command pattern):

9.5 Desktop Services

9.6 AI Engine Agents

Supporting classes:

• AppRuntime: Application lifecycle and configuration
• PostHogSpanProcessor: Telemetry span processing for AI agent traces

10. Supported Operations

The platform supports 38 distinct operation types (defined in engine/tool_models.py):

11. Testing

11.1 Test Infrastructure

11.2 Translation Validation

Stirling-PDF includes automated translation quality checks:

11.3 CI/CD Test Configuration

The test_cicd.yml Docker Compose file sets up a test environment with API key authentication enabled, allowing automated integration testing against a running container.

Tip

Run the full test suite before submitting PRs: ./gradlew build test spotlessCheck for backend, and cd frontend && npm run test && npm run lint for frontend.

12. Troubleshooting

12.1 Container Fails to Start

Error: Container exits immediately or health check fails.

Cause: Insufficient memory for JVM startup, misconfigured SYSTEM_ROOTURIPATH, or port conflict.

Solution:

1. Check logs: docker logs stirling-pdf
2. Verify memory: ensure at least 512 MB available
3. Check port availability: docker ps for conflicts on 8080
4. If using SYSTEM_ROOTURIPATH, ensure it starts with / and has no trailing slash

Prevention: Always configure healthcheck.start_period to at least 60 seconds to allow JVM warm-up.

12.2 LibreOffice Conversion Failures

Error: file-to-pdf, pdf-to-word, or similar endpoints return 500 errors.

Cause: LibreOffice not installed (standard/ultra-lite image), UNO server not running, or session limit exceeded.

Solution:

1. Verify image type: use fat image or install LibreOffice manually
2. Check UNO server: docker exec stirling-pdf ps aux | grep soffice
3. If remote UNO: verify shared /tmp/stirling-pdf volume and network connectivity
4. Increase session limit: PROCESS_EXECUTOR_SESSION_LIMIT_LIBRE_OFFICE_SESSION_LIMIT=4

Prevention: Use the fat Docker image for deployments requiring document conversion.

12.3 OCR Returns Empty Text

Error: ocr-pdf endpoint produces a PDF with no recognized text.

Cause: Missing Tesseract language data for the document's language.

Solution:

1. Install required language: TESSERACT_LANGS=eng,fra,deu (rebuild container)
2. Or mount traineddata files: -v ./tessdata:/usr/share/tessdata
3. Verify language availability inside container: ls /usr/share/tessdata/

Prevention: Pre-install all expected languages via TESSERACT_LANGS.

12.4 Large File Upload Fails

Error: 413 Request Entity Too Large or upload timeout.

Cause: SYSTEM_MAXFILESIZE too low, or reverse proxy body size limit.

Solution:

1. Increase SYSTEM_MAXFILESIZE (in MB)
2. Match reverse proxy limit: client_max_body_size 500M; in Nginx
3. Increase proxy timeout for large files

Prevention: Set consistent limits across Stirling-PDF config and reverse proxy.

12.5 Endpoints Show as Disabled

Error: UI shows certain operations as unavailable.

Cause: Missing external tool dependency, or group disabled via configuration.

Solution:

1. Check endpoint status via API: GET /api/v1/info/status
2. Review disable reason (CONFIG vs DEPENDENCY)
3. For DEPENDENCY: install the required tool or switch to fat image
4. For CONFIG: review settings.yml and ENDPOINTS_GROUPS_TO_REMOVE

Prevention: Use the fat Docker image to ensure all dependencies are present.

12.6 Split Frontend Cannot Reach Backend

Error: Frontend shows connection errors or blank pages.

Cause: VITE_API_BASE_URL not set or set to unreachable address.

Solution:

1. Verify VITE_API_BASE_URL points to the backend's actual URL
2. Ensure backend is running and healthy
3. Check network connectivity between frontend and backend containers
4. Verify CORS configuration if frontend and backend are on different domains

Prevention: Use Docker Compose networking (service names) for container-to-container communication.

Caution

When running in split mode, the backend URL must be accessible from both the frontend container (for SSR/proxying) and the end user's browser (for client-side API calls). Ensure the URL is publicly reachable or configure appropriate proxy rules.

12.7 Database Import Constraint Error

Error: Database import fails with constraint violation (relates to GitHub issue #4405).

Cause: Schema migration conflict or duplicate key in imported data.

Solution:

1. Back up existing database before import
2. Verify the import file matches the current schema version
3. If upgrading from an older version, let the application run its migrations first, then import

Prevention: Always export/import databases between matching application versions.

12.8 Windows SmartScreen Blocks Desktop Installer

Error: Windows SmartScreen prevents the desktop installer from running (GitHub issue #5600).

Cause: The executable is not yet widely distributed enough to build SmartScreen reputation, or code signing certificate is not recognized.

Solution:

1. Click "More info" then "Run anyway" in the SmartScreen dialog
2. Alternatively, right-click the installer, go to Properties, and check "Unblock"
3. For enterprise deployment, add the installer hash to your organization's allow list via Group Policy

Prevention: Enterprise administrators should pre-approve the installer via WDAC or AppLocker policies.

13. API Reference

13.1 Authentication

API requests can be authenticated via:

# Per-user API key
curl -H "X-API-KEY: your-api-key" http://localhost:8080/api/v1/info/status

# Global API key (if SECURITY_CUSTOMGLOBALAPIKEY is set)
curl -H "X-API-KEY: global-key" http://localhost:8080/api/v1/info/status

13.2 Core Endpoints

The API exposes endpoints matching the 38 operation types listed in Section 10. Each operation accepts multipart form data with the PDF file and operation-specific parameters.

General pattern:

# Example: Merge PDFs
curl -X POST http://localhost:8080/api/v1/general/merge-pdfs \
  -H "X-API-KEY: your-key" \
  -F "fileInput=@file1.pdf" \
  -F "fileInput=@file2.pdf"

# Example: Compress PDF
curl -X POST http://localhost:8080/api/v1/general/compress-pdf \
  -H "X-API-KEY: your-key" \
  -F "fileInput=@document.pdf" \
  -F "optimizeLevel=3"

# Example: OCR
curl -X POST http://localhost:8080/api/v1/misc/ocr-pdf \
  -H "X-API-KEY: your-key" \
  -F "fileInput=@scanned.pdf" \
  -F "languages=eng"

13.3 Info Endpoints

# Health/status check
GET /api/v1/info/status

# Application information
GET /api/v1/info

13.4 AI Engine Endpoints

When the AI engine is running:

# Orchestrate a natural language request
POST /orchestrate

# Ask questions about a PDF
POST /pdf_questions

# AI-guided PDF editing
POST /pdf_edit

# Draft a specification
POST /draft

# Revise a specification
POST /revise

# Get next action recommendation
POST /next-action

# Examine a document
POST /examine

# Deliberate on a complex request
POST /deliberate

# Health check
GET /health

14. Integration Points

14.1 PostHog Analytics

Both the frontend (SaaS module) and the AI engine support PostHog telemetry:

• AI Engine: Set STIRLING_POSTHOG_ENABLED=true, STIRLING_POSTHOG_API_KEY, and STIRLING_POSTHOG_HOST
• Frontend SaaS: PostHog is integrated in the SaaS deployment module for user behavior analytics

14.2 Google Drive

The GoogleDrivePickerService in the frontend core enables importing files directly from Google Drive into Stirling-PDF operations.

14.3 Stripe Billing

The proprietary frontend module includes Stripe checkout integration for SaaS billing scenarios.

14.4 Windows Shell Integration

The Windows thumbnail handler DLL (stirling_thumbnail_handler.dll) registers as a COM IThumbnailProvider for the .pdf file extension, providing native PDF thumbnails in Windows Explorer when the desktop app is installed.

14.5 Enterprise Provisioner

The Tauri provisioner tool allows enterprise IT to preconfigure desktop installations:

• Lock the server URL to a specific Stirling-PDF instance
• Prevent users from switching connection modes
• Deploy via standard MSI/MSIX enterprise deployment tools

15. Known Issues

Warning

Issue #6120 (false positive virus detection) affects v2.9.2 specifically. If your security software flags the Docker image or desktop binary, verify the checksum against the official release and add an exception if it matches.

16. Quick Reference

16.1 Minimal Docker Run

docker run -d -p 8080:8080 stirlingtools/stirling-pdf:latest

16.2 Production Docker Compose

version: "3.8"
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest-fat
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./tessdata:/usr/share/tessdata
      - ./customFiles:/customFiles
      - ./pipeline:/pipeline
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - FAT_DOCKER=true
      - SYSTEM_MAXFILESIZE=200
      - SYSTEM_DEFAULTLOCALE=en-US
      - TESSERACT_LANGS=eng,fra,deu,spa
      - METRICS_ENABLED=true
      - STIRLING_JVM_PROFILE=balanced
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

16.3 Key Paths Inside Container

16.4 Contributing Checklist

./gradlew spotlessApply   # Format Java code
./gradlew test            # Run backend tests
cd frontend && npm test   # Run frontend tests
./gradlew build           # Full build verification