# Stirling-PDF User Guide

Stirling-PDF is a self-hosted, privacy-first PDF manipulation toolkit that runs entirely on your own hardware. Version **2.9.2** delivers over 50 distinct PDF operations through a modern web interface, a REST API, and an optional desktop application -- all without sending a single page to an external server.

This guide covers every operation Stirling-PDF provides, how to install and configure it for your environment, and how to solve the problems you will encounter along the way. Configuration details, deployment architectures, monitoring, and security hardening live in the companion [Admin Guide](Stirling-Tools__Stirling-PDF__AdminGuide.md).

---

## 1. Quick Start

Get Stirling-PDF running in under two minutes with Docker:

```bash
docker run -d \
  -p 8080:8080 \
  --name stirling-pdf \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
```

Open your browser to `http://localhost:8080`. The home screen presents every available tool organized by category. Click any tool, upload your PDF, adjust options, and download the result.

> [!TIP]
> The `:fat` image includes all dependencies (LibreOffice, Tesseract OCR, fonts). If you only need basic PDF operations and want a smaller image, use `:ultra-lite` instead -- it skips LibreOffice and OCR but still handles merging, splitting, rotating, watermarking, and most security operations.

---

## 2. Installation

### 2.1 Docker (Recommended)

Docker is the primary deployment method. Three image variants are available:

| Image Tag | Size | Dependencies Included | Memory Limit |
|---|---|---|---|
| `stirlingtools/stirling-pdf:latest` | Medium | Requires external LibreOffice + Tesseract | 4G recommended |
| `stirlingtools/stirling-pdf:fat` | Large | All dependencies bundled | 6G recommended |
| `stirlingtools/stirling-pdf:ultra-lite` | Small | No LibreOffice, no OCR | 2G recommended |

Images are available from Docker Hub and the project's own registry at `docker.stirlingpdf.com/stirlingtools/stirling-pdf`.

> [!IMPORTANT]
> The `:fat` image requires at least **6 GB of memory** allocated to Docker. On Docker Desktop (Windows/macOS), check Settings, then Resources, then Memory and increase it if necessary. Insufficient memory causes silent crashes during LibreOffice-based conversions.

#### Docker Compose (production setup)

Create a `docker-compose.yml` file:

```yaml
services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/data:/usr/share/tessdata:rw
      - ./stirling/config:/configs:rw
      - ./stirling/logs:/logs:rw
      - ./stirling/customFiles:/customFiles:rw
      - ./stirling/pipeline:/pipeline:rw
    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      DOCKER_ENABLE_SECURITY: "false"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      SYSTEM_MAXFILESIZE: "100"
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          memory: 6G
```

Start the stack:

```bash
docker compose up -d
```

> [!WARNING]
> Always create the volume directories before starting the container (`mkdir -p ./stirling/{data,config,logs,customFiles,pipeline}`). If Docker creates them as root-owned directories, the container may fail to write configuration or log files.

#### Volume Mounts

| Host Path | Container Path | Purpose |
|---|---|---|
| `./stirling/data` | `/usr/share/tessdata` | Tesseract OCR language data files |
| `./stirling/config` | `/configs` | Configuration files including `settings.yml` |
| `./stirling/logs` | `/logs` | Application logs |
| `./stirling/customFiles` | `/customFiles` | UI customization (logos, CSS, templates) |
| `./stirling/pipeline` | `/pipeline` | Pipeline automation configurations |

#### Docker Run (quick start)

```bash
docker run -d \
  -p 8080:8080 \
  -v ./stirling/data:/usr/share/tessdata:rw \
  -v ./stirling/config:/configs:rw \
  -v ./stirling/logs:/logs:rw \
  --name stirling-pdf \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
```

#### Unified Container Modes

The container supports three operating modes via the `MODE` environment variable:

| Mode | Behavior |
|---|---|
| `BOTH` (default) | Runs both frontend and backend in a single container |
| `FRONTEND` | Serves only the React frontend; requires `VITE_API_BASE_URL` pointing to a backend instance |
| `BACKEND` | Runs only the Spring Boot API backend on `BACKEND_INTERNAL_PORT` (default 8081) |

Split-mode deployment example:

```yaml
services:
  stirling-backend:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    environment:
      MODE: BACKEND
      BACKEND_INTERNAL_PORT: "8081"
    ports:
      - "8081:8081"

  stirling-frontend:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
    environment:
      MODE: FRONTEND
      VITE_API_BASE_URL: "http://stirling-backend:8081"
    ports:
      - "8080:8080"
```

#### Setting User/Group IDs

Control the process ownership inside the container with `PUID`, `PGID`, and `UMASK`:

```yaml
environment:
  PUID: "1000"
  PGID: "1000"
  UMASK: "022"
```

This ensures files written to mounted volumes have the correct ownership on the host.

### 2.2 Desktop Application (Tauri)

Stirling-PDF is available as a native desktop application for Windows, macOS, and Linux. The desktop app bundles the full Stirling-PDF backend and frontend into a single installable package.

**Windows:**

1. Download the `.msi` installer from the [GitHub Releases](https://github.com/Stirling-Tools/Stirling-PDF/releases) page
2. Run the installer -- it also registers a PDF thumbnail handler for Windows Explorer
3. Launch from the Start Menu

**macOS:**

1. Download the `.dmg` from GitHub Releases
2. Drag to Applications
3. On first launch, right-click then select Open to bypass Gatekeeper

**Linux:**

1. Download the `.AppImage` or `.deb` package from GitHub Releases
2. For AppImage: `chmod +x Stirling-PDF*.AppImage && ./Stirling-PDF*.AppImage`
3. For deb: `sudo dpkg -i stirling-pdf*.deb`

The desktop app opens a native window with the same web UI. All processing happens locally on your machine.

### 2.3 Building from Source

Requirements:
- Java 21 or later (JDK, not JRE)
- Node.js (for building the React frontend)
- Gradle (wrapper included in repository)

```bash
git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF
./gradlew build
java -jar app/core/build/libs/*.jar
```

The application starts on port 8080 by default.

For the frontend only (development):

```bash
cd frontend
npm install
npm run dev
```

### 2.4 Verifying the Installation

After starting Stirling-PDF by any method, verify it is running:

```bash
curl http://localhost:8080/api/v1/info/status
```

Expected response: `UP`

Open `http://localhost:8080` in a browser. You should see the Stirling-PDF home page with all available tools.

---

## 3. Understanding the Interface

### 3.1 Home Page

The home page displays all available PDF tools as cards organized by functional group. Each card shows the tool name and a brief description. Click any card to open that tool.

The top navigation bar provides:

- **Home** -- return to the tool grid
- **Search** -- find tools by name or description
- **Pipeline** -- access the automation pipeline builder
- **Settings** -- application configuration (when security is enabled, this requires login)

### 3.2 Tool Pages

Every tool page follows a consistent layout:

1. **File upload area** -- drag and drop PDFs or click to browse. Some tools accept multiple files.
2. **Options panel** -- tool-specific settings (page ranges, quality levels, formats, etc.)
3. **Submit button** -- processes the file(s) with the selected options
4. **Download** -- the result is automatically downloaded when processing completes

### 3.3 Page Selection Syntax

Many tools require you to specify which pages to operate on. Stirling-PDF supports a powerful page selection syntax:

| Expression | Meaning |
|---|---|
| `1-10` | Pages 1 through 10 |
| `1,3,5` | Pages 1, 3, and 5 |
| `odd` | All odd-numbered pages |
| `even` | All even-numbered pages |
| `2n` | Every 2nd page (2, 4, 6, ...) |
| `2n+1` | Pages 1, 3, 5, 7, ... |
| `3n+2` | Pages 2, 5, 8, 11, ... |
| `!(1-5)` | All pages EXCEPT 1 through 5 |
| `1-10 & even` | Even pages within the range 1-10 (i.e., 2, 4, 6, 8, 10) |
| `1-5, 10-15` | Pages 1-5 and 10-15 (OR with comma) |
| `1-5 | 10-15` | Same as above (OR with pipe) |
| `(1-10) & !(3,7)` | Pages 1-10 except 3 and 7 |

Operators:

- **OR**: `,` or `|` -- union of page sets
- **AND**: `&` -- intersection of page sets
- **NOT**: `!` -- exclusion (negate a page set)
- **Parentheses**: `()` -- group expressions for precedence

### 3.4 API Access

Every tool is accessible via REST API at `/api/v1/`. Interactive API documentation is available at:

```
http://localhost:8080/swagger-ui/index.html
```

The Swagger UI lets you explore all endpoints, view request/response schemas, and test operations directly from the browser.

Example API call -- merge two PDFs:

```bash
curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "fileInput=@file1.pdf" \
  -F "fileInput=@file2.pdf" \
  -o merged.pdf
```

When `SECURITY_CUSTOMGLOBALAPIKEY` is set, include the API key in requests:

```bash
curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -H "X-API-Key: your-api-key-here" \
  -F "fileInput=@file1.pdf" \
  -F "fileInput=@file2.pdf" \
  -o merged.pdf
```

---

## 4. Page Operations

Page operations restructure, reorder, and transform the pages within a PDF without altering page content.

### 4.1 Merge PDFs

Combine multiple PDF files into a single document.

**How to use:**

1. Navigate to **Page Operations > Merge PDFs**
2. Upload two or more PDF files
3. Drag to reorder the files in the desired sequence
4. Click **Merge**
5. Download the combined PDF

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "fileInput=@chapter1.pdf" \
  -F "fileInput=@chapter2.pdf" \
  -F "fileInput=@chapter3.pdf" \
  -o complete-book.pdf
```

> [!TIP]
> When merging many files, the order in the upload list determines the order in the output. Use drag-and-drop in the web UI to rearrange before merging.

### 4.2 Split Pages

Divide a PDF into multiple files, each containing a specified range of pages.

**How to use:**

1. Navigate to **Page Operations > Split Pages**
2. Upload a PDF
3. Enter page numbers or ranges where splits should occur (e.g., `1,5,10` splits into pages 1-4, 5-9, and 10-end)
4. Click **Split**
5. Download the resulting ZIP containing individual PDFs

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/general/split-pages" \
  -F "fileInput=@document.pdf" \
  -F "pages=1,5,10" \
  -o split-pages.zip
```

### 4.3 Remove Pages

Delete specific pages from a PDF.

**How to use:**

1. Navigate to **Page Operations > Remove Pages**
2. Upload a PDF
3. Enter the pages to remove using page selection syntax (e.g., `2,5,8-10`)
4. Click **Remove**
5. Download the PDF with those pages removed

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/general/remove-pages" \
  -F "fileInput=@document.pdf" \
  -F "pagesToDelete=2,5,8-10" \
  -o cleaned.pdf
```

### 4.4 Rearrange Pages

Reorder pages within a PDF by specifying the new page sequence.

**How to use:**

1. Navigate to **Page Operations > Rearrange Pages**
2. Upload a PDF
3. Specify the new order (e.g., `3,1,2,5,4` reorders so page 3 comes first)
4. Use the visual page editor to drag and drop page thumbnails into the desired sequence
5. Click **Rearrange**

The visual editor shows thumbnails of every page and supports drag-and-drop reordering, which is the easiest way to work with documents that have many pages.

### 4.5 Rotate PDF

Rotate all pages or specific pages by 90, 180, or 270 degrees.

**How to use:**

1. Navigate to **Page Operations > Rotate PDF**
2. Upload a PDF
3. Select rotation angle: 90 degrees, 180 degrees, or 270 degrees clockwise
4. Optionally specify which pages to rotate (default: all)
5. Click **Rotate**

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/general/rotate-pdf" \
  -F "fileInput=@document.pdf" \
  -F "angle=90" \
  -o rotated.pdf
```

### 4.6 Multi-Page Layout

Arrange multiple PDF pages onto a single page (N-up printing). Useful for creating handouts or reducing paper usage.

**How to use:**

1. Navigate to **Page Operations > Multi-Page Layout**
2. Upload a PDF
3. Select the layout: 2-up, 4-up, 9-up, 16-up, or custom grid
4. Choose page ordering (left-to-right then top-to-bottom, or alternatives)
5. Click **Submit**

Common configurations:

| Layout | Grid | Best for |
|---|---|---|
| 2-up | 1 x 2 | Booklet preparation, side-by-side comparison |
| 4-up | 2 x 2 | Presentation handouts, draft review |
| 9-up | 3 x 3 | Thumbnail overview, storyboarding |
| 16-up | 4 x 4 | Maximum density, miniature reference sheets |

### 4.7 Booklet Imposition

Rearrange pages for booklet-style printing. After double-sided printing and folding, pages appear in the correct reading order.

**How to use:**

1. Navigate to **Page Operations > Booklet Imposition**
2. Upload a PDF
3. The tool reorders pages for saddle-stitch binding
4. Print the output double-sided, flip on short edge, then fold in half

For a 16-page document, the tool rearranges pages so that when printed double-sided on 4 sheets and folded, the pages read 1, 2, 3, ... 16 in order.

### 4.8 Scale Pages

Resize all pages to a different paper size or scale by percentage.

**How to use:**

1. Navigate to **Page Operations > Scale Pages**
2. Upload a PDF
3. Select target page size (A4, Letter, Legal, A3, etc.) or enter a custom scale percentage
4. Choose scaling behavior: fit content within the new size, fill the page, or stretch
5. Click **Submit**

### 4.9 Crop

Remove margins or crop pages to a specific region.

**How to use:**

1. Navigate to **Page Operations > Crop**
2. Upload a PDF
3. Define the crop box by specifying margins to remove (top, bottom, left, right) in points or percentages
4. Optionally apply the crop to specific pages only using page selection syntax
5. Click **Crop**

### 4.10 PDF to Single Page

Merge all pages of a PDF into one continuous vertical page. Useful for web-style viewing, creating scrollable documents, or preparing content for continuous-feed printing.

**How to use:**

1. Navigate to **Page Operations > PDF to Single Page**
2. Upload a PDF
3. Click **Submit**
4. Download the single-page result

The output is one very tall page containing all original pages stacked vertically.

### 4.11 Auto-Split PDF

Automatically detect and split a PDF at logical boundaries using blank pages, QR codes, or barcodes as separators.

**How to use:**

1. Navigate to **Page Operations > Auto-Split PDF**
2. Upload a PDF that contains separator pages
3. Select the split method:
   - **Blank page detection** -- splits at blank or near-blank pages
   - **QR code** -- splits when a QR code is detected on a page
   - **Barcode** -- splits at barcode-bearing pages
4. Configure detection sensitivity if applicable
5. Click **Split**
6. Download the ZIP containing the split PDFs

This is particularly useful for processing batches of scanned documents that use blank separator sheets.

### 4.12 Split by Size or Count

Split a PDF into chunks of a specified file size or page count.

**How to use:**

1. Navigate to **Page Operations > Split by Size or Count**
2. Upload a PDF
3. Choose split mode:
   - **By page count**: Enter the number of pages per output file (e.g., 10 pages each)
   - **By file size**: Enter the maximum size per output file (e.g., 5 MB)
4. Click **Split**
5. Download the ZIP of resulting files

This is useful for email attachment size limits or systems that cap individual file sizes.

### 4.13 Overlay PDF

Overlay one PDF on top of another. Common uses include adding a letterhead template to every page, applying a form template, or compositing two documents.

**How to use:**

1. Navigate to **Page Operations > Overlay PDF**
2. Upload the base PDF (the document to apply the overlay to)
3. Upload the overlay PDF (the template or layer to place on top)
4. Select overlay mode:
   - **Overlay** -- the overlay PDF renders on top of the base PDF content
   - **Underlay** -- the overlay PDF renders behind the base PDF content
5. Choose whether the overlay repeats (same page applied to every base page) or maps page-by-page
6. Click **Submit**

### 4.14 Split PDF by Sections

Split a PDF based on page sections -- dividing each page into regions (halves, quadrants, or custom grids) and producing separate pages for each region.

**How to use:**

1. Navigate to **Page Operations > Split PDF by Sections**
2. Upload a PDF
3. Define how to divide each page:
   - Horizontal splits (number of rows)
   - Vertical splits (number of columns)
4. Click **Submit**
5. Each section of each page becomes its own page in the output

This is useful for separating multi-column layouts or extracting individual panels from composite pages.

### 4.15 Split PDF by Chapters

Split a PDF using its existing table of contents or bookmark structure. Each top-level bookmark becomes a separate output file.

**How to use:**

1. Navigate to **Page Operations > Split PDF by Chapters**
2. Upload a PDF that contains bookmarks/outlines
3. Select the bookmark level at which to split (level 1 for top-level chapters, level 2 for sub-chapters, etc.)
4. Click **Split**
5. Download the ZIP containing one PDF per chapter

> [!NOTE]
> This tool requires the PDF to have embedded bookmarks/outlines. If the PDF has no bookmarks, the split will not produce meaningful results. Use **Edit Table of Contents** (in Other Tools) first to add bookmarks if needed.

### 4.16 Add Page Numbers

Add page numbers to every page (or selected pages) of a PDF.

**How to use:**

1. Navigate to **Page Operations > Add Page Numbers**
2. Upload a PDF
3. Configure the numbering:
   - **Position**: top or bottom of page; left, center, or right alignment
   - **Starting number**: which number the first page receives
   - **Font size**: size of the page number text
   - **Margin offset**: distance from the edge of the page
4. Optionally select which pages receive numbers using page selection syntax
5. Click **Submit**

### 4.17 Extract Pages

Extract specific pages from a PDF into a new file. Unlike Remove Pages (which removes specified pages and keeps the rest), Extract Pages keeps only the specified pages.

**How to use:**

1. Navigate to **Page Operations > Extract Pages**
2. Upload a PDF
3. Enter the pages to extract using page selection syntax (e.g., `1-5, 10, 15-20`, `odd`, `!(1-3)`)
4. Click **Extract**
5. Download the PDF containing only the selected pages

---

## 5. Format Conversion

Convert PDFs to and from dozens of formats. Some conversions require LibreOffice or other dependencies available in the `:fat` image or via manual installation.

### 5.1 PDF to Image

Convert PDF pages to images in various formats.

**How to use:**

1. Navigate to **Convert > PDF to Image**
2. Upload a PDF
3. Select output format: PNG, JPEG, GIF, TIFF, BMP, or WebP
4. Set DPI/resolution:
   - 72 DPI -- screen viewing
   - 150 DPI -- standard print quality
   - 300 DPI -- high-quality print
   - 600 DPI -- professional/archival quality
5. Choose to produce one image per page or all pages in a single file
6. Click **Convert**

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/convert/pdf/img" \
  -F "fileInput=@document.pdf" \
  -F "imageFormat=png" \
  -F "dpi=150" \
  -o pages.zip
```

### 5.2 Image to PDF

Convert one or more images into a PDF document.

**How to use:**

1. Navigate to **Convert > Image to PDF**
2. Upload one or more images (PNG, JPEG, TIFF, BMP, GIF, WebP)
3. Optionally set page size and orientation
4. Arrange image order by dragging
5. Click **Convert**

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/convert/img/pdf" \
  -F "fileInput=@photo1.jpg" \
  -F "fileInput=@photo2.jpg" \
  -o photos.pdf
```

### 5.3 PDF to PDF/A

Convert a PDF to PDF/A format for long-term archival compliance. PDF/A is an ISO-standardized version of PDF designed for digital preservation.

**How to use:**

1. Navigate to **Convert > PDF to PDF/A**
2. Upload a PDF
3. Select PDF/A conformance level:
   - **PDF/A-1b** -- basic conformance, widest reader compatibility
   - **PDF/A-2b** -- adds JPEG 2000, transparency, layers
   - **PDF/A-3b** -- allows embedded files of any type
4. Click **Convert**

> [!NOTE]
> PDF/A conversion may strip interactive elements (JavaScript, multimedia, external links) to comply with archival standards. Verify the output if your PDF contains forms or annotations that must be preserved.

### 5.4 File to PDF (Office Documents)

Convert DOCX, XLSX, PPTX, ODT, ODS, ODP, and other office formats to PDF using LibreOffice.

**How to use:**

1. Navigate to **Convert > File to PDF**
2. Upload a document in any supported format
3. Click **Convert**

**Supported input formats:** DOCX, DOC, XLSX, XLS, PPTX, PPT, ODT, ODS, ODP, RTF, TXT, CSV, HTML, XML, and other formats supported by LibreOffice.

> [!IMPORTANT]
> This feature requires LibreOffice. It is included in the `:fat` Docker image. If using `:ultra-lite` or `:latest` without LibreOffice installed, this conversion will not be available. Tools that require missing dependencies appear grayed out on the home page.

### 5.5 PDF to Word

Convert a PDF to DOCX format. The conversion preserves text content and attempts to maintain formatting, though complex layouts may not transfer perfectly.

**How to use:**

1. Navigate to **Convert > PDF to Word**
2. Upload a PDF
3. Click **Convert**
4. Download the `.docx` file

### 5.6 PDF to Presentation

Convert a PDF to PPTX format. Each page becomes a slide.

**How to use:**

1. Navigate to **Convert > PDF to Presentation**
2. Upload a PDF
3. Click **Convert**
4. Download the `.pptx` file

### 5.7 PDF to Text

Extract all text content from a PDF as a plain text file.

**How to use:**

1. Navigate to **Convert > PDF to Text**
2. Upload a PDF
3. Click **Convert**
4. Download the `.txt` file

For scanned PDFs that contain images of text rather than actual text, run OCR first (see Section 7.1) to make the text extractable.

### 5.8 PDF to HTML

Convert a PDF to an HTML document, preserving layout where possible.

**How to use:**

1. Navigate to **Convert > PDF to HTML**
2. Upload a PDF
3. Click **Convert**
4. Download the HTML file

### 5.9 PDF to XML

Export PDF content as structured XML.

**How to use:**

1. Navigate to **Convert > PDF to XML**
2. Upload a PDF
3. Click **Convert**

### 5.10 HTML to PDF

Convert an HTML file to PDF. The rendering engine processes CSS and produces a paginated PDF.

**How to use:**

1. Navigate to **Convert > HTML to PDF**
2. Upload an HTML file (with or without inline CSS/images)
3. Click **Convert**

### 5.11 URL to PDF

Capture a web page as a PDF by providing its URL.

**How to use:**

1. Navigate to **Convert > URL to PDF**
2. Enter the full URL of the web page (e.g., `https://example.com/article`)
3. Click **Convert**
4. Download the rendered PDF

The page is rendered as it appears in a browser, including CSS styling. JavaScript-rendered content is captured as well.

### 5.12 Markdown to PDF

Convert a Markdown file to a formatted PDF with proper headings, lists, code blocks, and other Markdown elements rendered visually.

**How to use:**

1. Navigate to **Convert > Markdown to PDF**
2. Upload a `.md` file
3. Click **Convert**

### 5.13 PDF to CSV

Extract tabular data from a PDF into CSV format. Works best with PDFs that contain clearly structured tables.

**How to use:**

1. Navigate to **Convert > PDF to CSV**
2. Upload a PDF containing tables
3. Click **Convert**
4. Download the `.csv` file

For best results, the source PDF should have clean, grid-based tables. Complex or multi-column layouts may produce less accurate results.

### 5.14 PDF to Markdown

Convert PDF content to Markdown format, preserving headings, lists, and basic formatting.

**How to use:**

1. Navigate to **Convert > PDF to Markdown**
2. Upload a PDF
3. Click **Convert**

### 5.15 Email to PDF (EML to PDF)

Convert email files in EML format to PDF, preserving headers, body, and formatting.

**How to use:**

1. Navigate to **Convert > EML to PDF**
2. Upload an `.eml` file
3. Click **Convert**

### 5.16 PDF to EPUB

Convert a PDF to EPUB format for e-readers like Kindle, Kobo, and Nook.

**How to use:**

1. Navigate to **Convert > PDF to EPUB**
2. Upload a PDF
3. Click **Convert**
4. Transfer the resulting `.epub` to your e-reader

Text-heavy PDFs (novels, articles) convert well. Image-heavy or layout-intensive PDFs may lose formatting in the EPUB conversion.

### 5.17 PDF to Vector and Vector to PDF

Convert between PDF and vector image formats (SVG).

**PDF to Vector:**

1. Navigate to **Convert > PDF to Vector**
2. Upload a PDF
3. Click **Convert**
4. Download the SVG output

**Vector to PDF:**

1. Navigate to **Convert > Vector to PDF**
2. Upload an SVG file
3. Click **Convert**

### 5.18 PDF to Video

Convert PDF pages into a video slideshow where each page is displayed for a configurable duration.

**How to use:**

1. Navigate to **Convert > PDF to Video**
2. Upload a PDF
3. Configure the duration each slide is displayed (seconds per page)
4. Click **Convert**

### 5.19 CBZ to PDF and PDF to CBZ

Convert between PDF and CBZ (Comic Book ZIP) format, commonly used for digital comic books.

**CBZ to PDF:**

1. Navigate to **Convert > CBZ to PDF**
2. Upload a `.cbz` file
3. Click **Convert**

**PDF to CBZ:**

1. Navigate to **Convert > PDF to CBZ**
2. Upload a PDF
3. Click **Convert**

### 5.20 PDF to JSON and JSON to PDF

Convert PDF structure and content to JSON representation, and reconstruct PDFs from JSON.

**PDF to JSON:**

1. Navigate to **Convert > PDF to JSON**
2. Upload a PDF
3. Click **Convert**

**JSON to PDF:**

1. Navigate to **Convert > JSON to PDF**
2. Upload a JSON file conforming to the expected schema
3. Click **Convert**

### 5.21 PDF to RTF

Convert a PDF to Rich Text Format, which is widely supported by word processors.

**How to use:**

1. Navigate to **Convert > PDF to RTF**
2. Upload a PDF
3. Click **Convert**

---

## 6. Security Operations

Protect, encrypt, sign, redact, and validate PDFs. All security operations happen locally -- no certificates, passwords, or document content leave your server.

### 6.1 Add Password

Encrypt a PDF with a password. You can set both a **user password** (required to open the document) and an **owner password** (required to modify permissions).

**How to use:**

1. Navigate to **Security > Add Password**
2. Upload a PDF
3. Enter the password
4. Select encryption strength (128-bit AES or 256-bit AES)
5. Optionally set separate owner and user passwords for different access levels
6. Click **Encrypt**

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/security/add-password" \
  -F "fileInput=@document.pdf" \
  -F "password=MySecurePass123" \
  -o encrypted.pdf
```

### 6.2 Remove Password

Remove password protection from a PDF. You must know the current password.

**How to use:**

1. Navigate to **Security > Remove Password**
2. Upload the encrypted PDF
3. Enter the current password
4. Click **Remove**
5. Download the unencrypted PDF

### 6.3 Change Permissions

Modify the permission flags on a PDF to control what actions readers can perform.

**How to use:**

1. Navigate to **Security > Change Permissions**
2. Upload a PDF
3. Select which permissions to allow or deny:
   - Printing (full quality or degraded)
   - Content copying and extraction
   - Document modification
   - Annotation and form editing
   - Form filling
   - Page assembly
4. Set the owner password to enforce the permissions
5. Click **Apply**

### 6.4 Add Watermark

Add a text or image watermark to PDF pages.

**How to use:**

1. Navigate to **Security > Add Watermark**
2. Upload a PDF
3. Choose watermark type:
   - **Text watermark**: enter the text (e.g., "CONFIDENTIAL", "DRAFT", a company name)
   - **Image watermark**: upload an image file
4. Configure appearance:
   - **Position**: center, corner, or custom coordinates
   - **Rotation**: typically 0 degrees (horizontal) or 45 degrees (diagonal)
   - **Opacity**: 0-100% (10-20% for subtle, 50-80% for visible stamps)
   - **Font size**: for text watermarks
5. Choose which pages to watermark (all pages or specific pages)
6. Click **Apply**

> [!TIP]
> For a subtle "CONFIDENTIAL" watermark, set the text to light gray, 45-degree rotation, 15% opacity, and position it centered. For a visible header stamp, use 100% opacity, 0-degree rotation, and position it at the top of the page.

### 6.5 Certificate Signing

Digitally sign a PDF with an X.509 certificate for legal and authenticity purposes.

**How to use:**

1. Navigate to **Security > Certificate Sign**
2. Upload a PDF
3. Upload your certificate file (`.p12` or `.pfx` format)
4. Enter the certificate password
5. Optionally configure:
   - Signature appearance (visible or invisible)
   - Signature location on the page
   - Reason for signing
6. Click **Sign**

### 6.6 Remove Certificate Signature

Remove digital certificate signatures from a PDF.

**How to use:**

1. Navigate to **Security > Remove Certificate Sign**
2. Upload a signed PDF
3. Click **Remove**
4. Download the unsigned version

### 6.7 Sanitize PDF

Remove potentially dangerous or privacy-compromising content from a PDF. This is a security-focused tool that strips elements that could pose risks.

**How to use:**

1. Navigate to **Security > Sanitize PDF**
2. Upload a PDF
3. Select what to remove:
   - **Embedded JavaScript** -- could execute malicious code in PDF readers
   - **Embedded files and attachments** -- could contain malware
   - **Metadata** -- author name, creation software, GPS coordinates, timestamps
   - **Actions** -- auto-open URLs, form submission actions, print triggers
4. Click **Sanitize**

> [!WARNING]
> Sanitization is irreversible and permanently removes selected content. Always keep a backup of the original file. Removing JavaScript will break interactive PDF forms that rely on calculated fields or validation scripts.

### 6.8 Timestamp PDF

Add a trusted timestamp to a PDF to provide cryptographic proof that the document existed in a specific form at a specific time. This is useful for legal compliance and intellectual property protection.

**How to use:**

1. Navigate to **Security > Timestamp PDF**
2. Upload a PDF
3. Enter the TSA (Time Stamp Authority) URL (e.g., `http://timestamp.digicert.com`)
4. Click **Timestamp**

### 6.9 Auto-Redact

Automatically detect and redact sensitive information using pattern matching. The tool scans for common patterns like email addresses, phone numbers, social security numbers, and credit card numbers.

**How to use:**

1. Navigate to **Security > Auto-Redact**
2. Upload a PDF
3. Select the types of information to redact:
   - Email addresses
   - Phone numbers
   - Social security numbers
   - Credit card numbers
   - Custom patterns (regular expressions)
4. Configure redaction appearance (black box, colored box, or replacement text)
5. Click **Redact**

### 6.10 Redact

Manually redact specific text or areas in a PDF. Unlike covering text with a shape, proper redaction permanently removes the underlying text data.

**How to use:**

1. Navigate to **Security > Redact**
2. Upload a PDF
3. Enter text strings to search and redact, or use the visual editor to select areas
4. Configure the redaction appearance
5. Click **Apply**

> [!CAUTION]
> Redaction permanently and irreversibly removes content from the PDF. Unlike a black highlight marker (which can be removed digitally), redaction eliminates the underlying text data. Always verify redacted documents by attempting to search for the redacted terms -- no matches should be found.

### 6.11 Validate Signature

Check whether digital signatures in a PDF are valid and trustworthy.

**How to use:**

1. Navigate to **Security > Validate Signature**
2. Upload a signed PDF
3. The tool displays:
   - Signature status (valid/invalid/unknown)
   - Signer information
   - Certificate chain details
   - Whether the document was modified after signing

### 6.12 Add Stamp

Add a visual stamp to PDF pages. Stamps are opaque labels placed on top of page content, commonly used for document status indicators.

**How to use:**

1. Navigate to **Security > Add Stamp**
2. Upload a PDF
3. Choose a predefined stamp (CONFIDENTIAL, APPROVED, DRAFT, FINAL, etc.) or enter custom text
4. Configure position, size, color, and rotation
5. Select which pages receive the stamp
6. Click **Apply**

### 6.13 Unlock PDF Forms

Remove restrictions on PDF form fields, making them editable when they have been locked or flattened by form creators.

**How to use:**

1. Navigate to **Security > Unlock PDF Forms**
2. Upload a PDF with locked form fields
3. Click **Unlock**
4. Download the PDF with editable form fields

### 6.14 Verify PDF

Verify the structural integrity of a PDF file. This tool checks the PDF for conformance issues, structural errors, and potential corruption.

**How to use:**

1. Navigate to **Security > Verify PDF**
2. Upload a PDF
3. Review the verification results, which report any structural issues found

### 6.15 Sign (Visual Signature)

Add a handwritten-style visual signature to a PDF. This is distinct from certificate signing -- it places a visual representation of your signature on the page.

**How to use:**

1. Navigate to **Security > Sign**
2. Upload a PDF
3. Create your signature using one of three methods:
   - **Draw** -- use your mouse or touchscreen to draw your signature
   - **Type** -- type your name and select a script font
   - **Upload** -- upload an image of your signature (PNG with transparent background works best)
4. Position the signature on the desired page and location
5. Click **Apply**

---

## 7. Other Tools

### 7.1 OCR PDF

Apply Optical Character Recognition to make scanned PDFs searchable and text-selectable. OCR converts images of text into actual machine-readable text embedded in the PDF.

**How to use:**

1. Navigate to **Other Tools > OCR PDF**
2. Upload a scanned PDF
3. Select the document language(s) -- accuracy depends heavily on correct language selection
4. Choose OCR mode:
   - **Force OCR**: OCR all pages regardless of whether they already contain extractable text
   - **Skip text**: Only OCR pages that have no existing extractable text (faster for mixed documents)
   - **Normal**: Default behavior
5. Click **Apply**

**Adding OCR Languages:**

The default installation includes English. To OCR documents in other languages, add Tesseract language data files.

Using the environment variable (recommended for Docker):

```yaml
environment:
  TESSERACT_LANGS: "deu,fra,spa,jpn,chi_sim,kor,ara"
```

The container downloads the specified language data on startup.

Manually downloading language files:

```bash
# Download German language data into the tessdata volume
wget -P ./stirling/data/ \
  https://github.com/tesseract-ocr/tessdata/raw/main/deu.traineddata
```

Common language codes:

| Code | Language | Code | Language |
|---|---|---|---|
| `eng` | English | `jpn` | Japanese |
| `deu` | German | `chi_sim` | Chinese (Simplified) |
| `fra` | French | `chi_tra` | Chinese (Traditional) |
| `spa` | Spanish | `kor` | Korean |
| `ita` | Italian | `ara` | Arabic |
| `por` | Portuguese | `hin` | Hindi |
| `nld` | Dutch | `rus` | Russian |

> [!IMPORTANT]
> OCR accuracy depends heavily on selecting the correct language. For multilingual documents, specify all relevant languages. The `:ultra-lite` image does not include Tesseract -- OCR is unavailable on that variant.

### 7.2 Extract Images

Extract all embedded images from a PDF as individual image files.

**How to use:**

1. Navigate to **Other Tools > Extract Images**
2. Upload a PDF
3. Select output format (PNG or JPEG)
4. Click **Extract**
5. Download the ZIP containing all extracted images

Each image embedded in the PDF (photos, diagrams, logos) is extracted at its original resolution.

### 7.3 Update Metadata

View and modify PDF metadata fields such as title, author, subject, keywords, creator, and producer.

**How to use:**

1. Navigate to **Other Tools > Update Metadata**
2. Upload a PDF
3. The current metadata is displayed for review
4. Edit any field:
   - **Title** -- the document title
   - **Author** -- the document author
   - **Subject** -- a brief subject description
   - **Keywords** -- comma-separated keywords
   - **Creator** -- the application that created the original content
   - **Producer** -- the application that produced the PDF
5. Click **Save**

### 7.4 Flatten PDF

Flatten form fields, annotations, comments, and layers into the page content. The result is a static PDF where all interactive elements become part of the page image.

**How to use:**

1. Navigate to **Other Tools > Flatten**
2. Upload a PDF
3. Click **Flatten**

Flattening is commonly used:
- Before printing, to ensure annotations appear as intended
- Before sharing, to prevent form field modification
- Before applying operations that do not preserve form fields (such as certain split operations)
- To reduce file complexity

### 7.5 Remove Blank Pages

Detect and remove blank or near-blank pages from a PDF. Useful for cleaning up scanned documents that include separator sheets or accidental blank pages.

**How to use:**

1. Navigate to **Other Tools > Remove Blanks**
2. Upload a PDF
3. Adjust the blank detection threshold -- the sensitivity control determines how much content a page can have and still be considered "blank" (increase the threshold to catch pages with minor artifacts like scan noise)
4. Click **Remove**

### 7.6 Remove Annotations

Strip all annotations from a PDF, including comments, highlights, sticky notes, strikethroughs, underlines, ink annotations, and other markup.

**How to use:**

1. Navigate to **Other Tools > Remove Annotations**
2. Upload a PDF
3. Click **Remove**
4. Download the annotation-free PDF

### 7.7 Get PDF Info

Display comprehensive information about a PDF file.

**How to use:**

1. Navigate to **Other Tools > Get Info on PDF**
2. Upload a PDF
3. Review the information display, which includes:
   - Page count and individual page sizes
   - PDF version
   - Encryption status and method
   - Metadata (title, author, creation date, etc.)
   - Font list (embedded and referenced)
   - Producer and creator applications
   - File size and structure details

### 7.8 Add Attachments

Embed files as attachments within a PDF. Attached files travel with the PDF and can be extracted by the recipient.

**How to use:**

1. Navigate to **Other Tools > Add Attachments**
2. Upload a PDF
3. Upload the files you want to attach (any file type)
4. Click **Add**
5. Download the PDF with embedded attachments

### 7.9 Replace/Invert Colors

Replace or invert colors in a PDF. This tool processes the visual content of each page.

**How to use:**

1. Navigate to **Other Tools > Replace/Invert PDF**
2. Upload a PDF
3. Choose the color operation:
   - **Full inversion** -- inverts all colors (creates a "dark mode" version)
   - **Custom color mapping** -- replace specific colors with others
4. Click **Apply**

This is useful for creating dark-background versions of documents for comfortable screen reading, or for accessibility adjustments.

### 7.10 Edit Table of Contents

Add, modify, or remove the bookmark/outline structure of a PDF. Bookmarks appear as a navigable tree in PDF readers, allowing quick jumps to specific sections.

**How to use:**

1. Navigate to **Other Tools > Edit Table of Contents**
2. Upload a PDF
3. The existing bookmark tree is displayed in an editable form
4. Edit the structure:
   - **Add** new bookmarks with a title and target page number
   - **Rename** existing bookmarks
   - **Delete** unwanted bookmarks
   - **Reorder** or **nest** bookmarks to create a hierarchy
5. Click **Save**

### 7.11 Text Editor

Edit text directly within a PDF. This tool provides a visual editor for modifying existing text content.

**How to use:**

1. Navigate to **Other Tools > Text Editor**
2. Upload a PDF
3. Select text on the page to edit
4. Modify the text content
5. Click **Save**

Text editing in PDFs is inherently limited compared to word processors. Complex layout changes may not be possible, but simple text corrections (fixing typos, updating dates, changing names) work well.

### 7.12 Add Image

Insert an image into a PDF at a specified position and page.

**How to use:**

1. Navigate to **Other Tools > Add Image**
2. Upload a PDF
3. Upload the image to insert (PNG, JPEG, etc.)
4. Select the target page
5. Position the image by specifying coordinates or dragging in the preview
6. Adjust size and rotation as needed
7. Click **Apply**

### 7.13 Compare PDFs

Compare two PDF files side by side and highlight differences. Useful for reviewing document revisions.

**How to use:**

1. Navigate to **Other Tools > Compare**
2. Upload two PDF files (the original and the modified version)
3. View the comparison results, which highlight:
   - Added content
   - Deleted content
   - Changed content
   - Moved content

### 7.14 View PDF

View a PDF directly in the browser using the built-in PDF.js viewer, without needing a separate PDF reader.

**How to use:**

1. Navigate to **Other Tools > View PDF**
2. Upload a PDF
3. Use the viewer controls:
   - Page navigation
   - Zoom in/out
   - Full-text search
   - Bookmark navigation
   - Print

---

## 8. Advanced Tools

### 8.1 Compress PDF

Reduce PDF file size by optimizing images, removing duplicate objects, and streamlining the document structure.

**How to use:**

1. Navigate to **Advanced > Compress PDF**
2. Upload a PDF
3. Select compression level:
   - **Low (1-2)**: Minimal quality loss, moderate size reduction
   - **Medium (3-4)**: Balanced quality and size -- good default for most uses
   - **High (5)**: Maximum compression, noticeable quality reduction in images
4. Click **Compress**
5. The output shows both original and compressed file sizes

**API:**

```bash
curl -X POST "http://localhost:8080/api/v1/general/compress-pdf" \
  -F "fileInput=@large-document.pdf" \
  -F "optimizeLevel=3" \
  -o compressed.pdf
```

### 8.2 Extract Image Scans

Split a scanned page containing multiple photos or documents into individual images. This is designed for flatbed scanning workflows where you scan multiple physical photos on a single pass.

**How to use:**

1. Navigate to **Advanced > Extract Image Scans**
2. Upload a PDF containing scanned pages with multiple photos/documents per page
3. The tool automatically detects individual image boundaries
4. Download the extracted, separated images

### 8.3 Repair PDF

Attempt to repair a corrupted or malformed PDF that fails to open correctly in PDF readers.

**How to use:**

1. Navigate to **Advanced > Repair**
2. Upload the damaged PDF
3. Click **Repair**
4. Download the repaired version

Not all corrupted PDFs can be repaired. The tool fixes common structural issues like broken cross-reference tables, missing end-of-file markers, and damaged object streams.

### 8.4 Auto-Rename

Automatically generate descriptive filenames for PDFs based on their content. The tool analyzes titles, dates, and subject matter to suggest meaningful names.

**How to use:**

1. Navigate to **Advanced > Auto-Rename**
2. Upload one or more PDFs
3. The tool analyzes each document and generates a suggested filename
4. Download the renamed files

### 8.5 Scanner Effect

Apply visual effects that make a digital PDF look like it was scanned from a physical copy. Adds subtle imperfections such as slight rotation, noise, reduced contrast, and border darkening.

**How to use:**

1. Navigate to **Advanced > Scanner Effect**
2. Upload a PDF
3. Adjust effect parameters:
   - **Rotation randomness** -- how much each page tilts (simulates manual scanning)
   - **Noise level** -- grain/speckle added to the image
   - **Border darkening** -- shadow at page edges
4. Click **Apply**

### 8.6 Adjust Contrast

Modify the contrast, brightness, and saturation of pages in a PDF. Useful for improving readability of faded scans or adjusting visual appearance.

**How to use:**

1. Navigate to **Advanced > Adjust Contrast**
2. Upload a PDF
3. Adjust the sliders:
   - **Contrast** -- increase to sharpen the difference between light and dark areas
   - **Brightness** -- increase to lighten, decrease to darken
   - **Saturation** -- increase for more vivid colors, decrease toward grayscale
4. Click **Apply**

---

## 9. Automation: Pipelines

Pipelines let you chain multiple Stirling-PDF operations into automated workflows. Instead of running each tool manually one at a time, define a sequence of operations that executes in a single step.

### 9.1 Creating a Pipeline

1. Navigate to **Pipeline** in the top navigation bar
2. Click **Create New Pipeline**
3. Add operations in sequence by selecting tools from the dropdown
4. Configure each operation's parameters (the same options available in each tool's individual page)
5. Save the pipeline with a descriptive name

### 9.2 Pipeline Structure

A pipeline consists of an ordered list of operations. Each operation specifies:

- **Tool**: Which Stirling-PDF operation to run
- **Parameters**: The configuration for that operation
- **Input**: Automatically connected -- the output of the previous operation feeds into the next (the initial upload feeds into the first step)

**Example pipeline -- prepare a document for archival:**

| Step | Operation | Purpose |
|---|---|---|
| 1 | OCR PDF | Make scanned text searchable |
| 2 | Remove Blank Pages | Clean up separator sheets |
| 3 | Flatten | Lock in annotations and form data |
| 4 | Compress PDF | Reduce storage size |
| 5 | PDF to PDF/A | Convert to archival format |

**Example pipeline -- secure a document for distribution:**

| Step | Operation | Purpose |
|---|---|---|
| 1 | Auto-Redact | Remove sensitive patterns |
| 2 | Sanitize PDF | Strip metadata and scripts |
| 3 | Flatten | Make redactions permanent |
| 4 | Add Watermark | Apply "CONFIDENTIAL" watermark |
| 5 | Add Password | Encrypt with password |

### 9.3 Running a Pipeline

1. Open a saved pipeline
2. Upload one or more input PDFs
3. Click **Run Pipeline**
4. Each operation executes in sequence, with progress shown
5. Download the final output

### 9.4 Pipeline API

Pipelines can be triggered via the API for integration with external systems:

```bash
curl -X POST "http://localhost:8080/api/v1/general/handleData" \
  -F "fileInput=@document.pdf" \
  -F "pipelineConfig=@my-pipeline.json" \
  -o result.pdf
```

### 9.5 Watched Folder Automation

Place pipeline configuration files in the `/pipeline` directory (mapped to `./stirling/pipeline` on the host). Stirling-PDF can monitor this directory and automatically process files placed in designated input folders.

> [!TIP]
> Combine watched-folder pipelines with cron jobs or file watchers on the host system to build fully automated document processing workflows. For example, scan a network share for incoming PDFs, route them through a standardize-and-archive pipeline, and save results to an output directory -- all without manual intervention.

---

## 10. Developer Tools

### 10.1 Show JavaScript

View embedded JavaScript within a PDF. This is a diagnostic tool for developers and security auditors who need to inspect what scripts are bundled inside a PDF.

**How to use:**

1. Navigate to **Developer Tools > Show JavaScript**
2. Upload a PDF
3. Any embedded JavaScript is displayed in a syntax-highlighted code viewer
4. Review the scripts for functionality or potential security issues

PDFs can contain JavaScript for form calculations, field validation, and interactive features. This tool surfaces all such scripts without executing them.

---

## 11. Configuration Reference

### 11.1 Environment Variables

Configure Stirling-PDF behavior through environment variables. Set these in `docker-compose.yml`, pass them with `docker run -e`, or configure them in the desktop app's settings.

**Application identity:**

| Variable | Default | Description |
|---|---|---|
| `UI_APPNAME` | `Stirling-PDF` | Application name displayed in the browser tab and header |
| `UI_HOMEDESCRIPTION` | (built-in) | Custom descriptive text for the home page |
| `UI_APPNAMENAVBAR` | (same as `UI_APPNAME`) | Name displayed in the navigation bar |

**System behavior:**

| Variable | Default | Description |
|---|---|---|
| `SYSTEM_DEFAULTLOCALE` | `en-US` | Default UI language (ISO locale code) |
| `SYSTEM_MAXFILESIZE` | `100` | Maximum file upload size in megabytes |
| `SYSTEM_ROOTURIPATH` | `/` | Root URI path for reverse proxy deployments |
| `SYSTEM_GOOGLEVISIBILITY` | `false` | Whether to allow search engine indexing |

**Security:**

| Variable | Default | Description |
|---|---|---|
| `DOCKER_ENABLE_SECURITY` | `false` | Master switch for security features in Docker |
| `SECURITY_ENABLELOGIN` | `false` | Enable the login/authentication screen |
| `SECURITY_CUSTOMGLOBALAPIKEY` | (none) | Set a global API key required for all API requests |

**Features and tools:**

| Variable | Default | Description |
|---|---|---|
| `DISABLE_ADDITIONAL_FEATURES` | `false` | Disable features that require external tools |
| `ENDPOINTS_GROUPS_TO_REMOVE` | (none) | Comma-separated list of endpoint groups to disable |
| `TESSERACT_LANGS` | (none) | OCR languages to download on startup (comma-separated codes) |

**Performance:**

| Variable | Default | Description |
|---|---|---|
| `STIRLING_JVM_PROFILE` | `balanced` | JVM profile: `balanced` (G1GC) or `performance` (Shenandoah) |
| `JAVA_CUSTOM_OPTS` | (none) | Additional JVM flags (e.g., `-Xmx4g -Xms2g`) |
| `FAT_DOCKER` | `false` | Indicates fat Docker image (set automatically in `:fat` images) |
| `METRICS_ENABLED` | `true` | Enable Prometheus-compatible metrics collection |

**Container configuration:**

| Variable | Default | Description |
|---|---|---|
| `MODE` | `BOTH` | Container mode: `BOTH`, `FRONTEND`, or `BACKEND` |
| `BACKEND_INTERNAL_PORT` | `8081` | Internal backend port when `MODE=BOTH` |
| `VITE_API_BASE_URL` | (none) | Backend URL for `MODE=FRONTEND` containers |
| `PUID` | `1000` | Process user ID inside the container |
| `PGID` | `1000` | Process group ID inside the container |
| `UMASK` | `022` | File creation mask |

### 11.2 Settings File

Beyond environment variables, Stirling-PDF reads configuration from `/configs/settings.yml` inside the container. Mount a volume to `/configs` to persist settings across restarts:

```yaml
# /configs/settings.yml
security:
  enableLogin: false
  initialLogin:
    username: admin
    password: stirling

system:
  defaultLocale: en-US
  maxFileSize: 100

ui:
  appName: "Stirling-PDF"
  homeDescription: "Your PDF tools"
```

### 11.3 Custom UI Files

The `/customFiles` volume mount supports customizing the UI appearance:

- Custom logos and branding images
- Additional CSS styling
- Custom HTML templates

Place files in the mounted directory and restart the container to apply changes.

### 11.4 Reverse Proxy Configuration

When running Stirling-PDF behind a reverse proxy, set `SYSTEM_ROOTURIPATH` if the application is not served at the root path.

```yaml
environment:
  SYSTEM_ROOTURIPATH: "/stirling-pdf"
```

**Nginx example:**

```nginx
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;
}
```

**Traefik label example:**

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

For full reverse proxy configuration details including Caddy, Apache, and advanced TLS settings, see the [Admin Guide](Stirling-Tools__Stirling-PDF__AdminGuide.md).

### 11.5 Authentication

Enable authentication by setting both `DOCKER_ENABLE_SECURITY` and `SECURITY_ENABLELOGIN`:

```yaml
environment:
  DOCKER_ENABLE_SECURITY: "true"
  SECURITY_ENABLELOGIN: "true"
```

Configure initial admin credentials in `settings.yml`:

```yaml
security:
  enableLogin: true
  initialLogin:
    username: admin
    password: change-me-immediately
```

Change the default password on first login. For detailed authentication configuration including OAuth and SSO, see the [Admin Guide](Stirling-Tools__Stirling-PDF__AdminGuide.md).

### 11.6 JVM Tuning

Two JVM profiles are available via `STIRLING_JVM_PROFILE`:

| Profile | Garbage Collector | Use Case |
|---|---|---|
| `balanced` (default) | G1GC | General use, predictable pause times, moderate throughput |
| `performance` | Shenandoah | High-throughput, low-latency for heavy concurrent workloads |

For additional tuning, use `JAVA_CUSTOM_OPTS`:

```yaml
environment:
  JAVA_CUSTOM_OPTS: "-Xmx4g -Xms2g -XX:MaxMetaspaceSize=512m"
```

### 11.7 Disabling Tool Groups

Remove specific tool groups from the UI and API:

```yaml
environment:
  ENDPOINTS_GROUPS_TO_REMOVE: "CLI"
```

This hides the specified groups from the home page and disables their API endpoints entirely.

---

## 12. Workflows and Use Cases

### 12.1 Digitize a Paper Archive

**Goal:** Convert a stack of scanned documents into searchable, compressed, archival-compliant PDFs.

1. Scan documents to PDF using any scanner
2. Upload to **OCR PDF** -- select the appropriate language(s)
3. Run through **Remove Blank Pages** to eliminate empty scanner separator pages
4. Apply **Compress PDF** at medium quality to reduce storage
5. Convert to **PDF/A** for long-term archival compliance
6. Use **Auto-Rename** to give files meaningful names based on detected content

Pipeline alternative: create a pipeline with steps 2-6 and batch-process the entire archive.

### 12.2 Prepare a Booklet for Printing

**Goal:** Print a document as a folded booklet on a standard printer.

1. Upload your PDF to **Booklet Imposition**
2. The tool reorders pages for saddle-stitch binding
3. Print the output double-sided, with "flip on short edge" selected
4. Fold the printed pages in half and staple in the center

### 12.3 Merge and Secure Meeting Minutes

**Goal:** Combine monthly meeting minutes into a single protected document.

1. Upload all monthly PDFs to **Merge PDFs** and reorder chronologically
2. Merge and download the combined document
3. Upload the merged file to **Add Page Numbers** (start from 1, bottom center)
4. Upload to **Update Metadata** -- set title, author, and keywords
5. Upload to **Add Password** -- set a strong password for distribution

### 12.4 Redact Sensitive Information for Public Release

**Goal:** Prepare documents for FOIA or public distribution by removing personal information.

1. Upload documents to **Auto-Redact** -- select SSN, phone, email, and credit card patterns
2. Review the output carefully to verify all sensitive content is redacted
3. Run through **Flatten** to ensure redactions are permanent and cannot be removed
4. Use **Sanitize PDF** to strip metadata that might contain sensitive information
5. Verify by opening the result and searching for redacted terms -- zero results expected

### 12.5 Convert a Photo Album to E-Reader Format

**Goal:** Turn a collection of images into an EPUB for reading on a Kindle or similar device.

1. Upload all images to **Image to PDF** and arrange in desired order
2. Download the combined PDF
3. Upload to **PDF to EPUB**
4. Transfer the `.epub` file to your e-reader

### 12.6 Standardize Documents for Legal Filing

**Goal:** Ensure all documents meet court filing requirements (consistent size, numbered, stamped).

1. Use **Scale Pages** to standardize all documents to Letter (8.5 x 11) or A4
2. Apply **Add Page Numbers** with consecutive numbering across all documents
3. Use **Add Stamp** to add exhibit numbers or confidentiality notices
4. Convert to **PDF/A** for long-term archival as required by many courts
5. Optionally **Certificate Sign** each document for digital authenticity

### 12.7 Extract Specific Content from a Large Document

**Goal:** Pull specific pages, images, or data from a large PDF.

| Need | Tool | Example |
|---|---|---|
| Specific pages | **Extract Pages** | `1-5, 10, 15-20` or `odd` |
| All images | **Extract Images** | Exports every embedded image |
| Full text | **PDF to Text** | Plain text extraction |
| Tables | **PDF to CSV** | Tabular data to spreadsheet |
| Chapters | **Split by Chapters** | One PDF per bookmark |
| Visual sections | **Split by Sections** | Divide each page into regions |

### 12.8 Batch Processing via API

**Goal:** Process hundreds of PDFs programmatically using the REST API.

```python
import requests
from pathlib import Path

API_BASE = "http://localhost:8080/api/v1"

def compress_pdf(input_path, output_path, level=3):
    """Compress a single PDF file."""
    with open(input_path, "rb") as f:
        response = requests.post(
            f"{API_BASE}/general/compress-pdf",
            files={"fileInput": f},
            data={"optimizeLevel": level}
        )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(response.content)

def ocr_pdf(input_path, output_path, languages="eng"):
    """Apply OCR to a scanned PDF."""
    with open(input_path, "rb") as f:
        response = requests.post(
            f"{API_BASE}/misc/ocr-pdf",
            files={"fileInput": f},
            data={"languages": languages, "ocrType": "skip-text"}
        )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(response.content)

# Compress all PDFs in a directory
input_dir = Path("./input")
output_dir = Path("./output")
output_dir.mkdir(exist_ok=True)

for pdf in input_dir.glob("*.pdf"):
    compress_pdf(pdf, output_dir / pdf.name)
    print(f"Compressed: {pdf.name}")
```

### 12.9 Create a Dark Mode PDF

**Goal:** Convert a white-background PDF to a dark-background version for comfortable nighttime reading.

1. Upload to **Replace/Invert Colors**
2. Select full color inversion
3. Download the dark-mode version

White text on a dark background is easier on the eyes for extended screen reading sessions.

### 12.10 Add a Letterhead to Every Page

**Goal:** Apply a company letterhead template to an existing document.

1. Create a PDF with just the letterhead design (logo, borders, header text) on a single page
2. Upload the document as the base PDF in **Overlay PDF**
3. Upload the letterhead PDF as the overlay
4. Select "Underlay" mode (so the letterhead appears behind the document content)
5. Select "Repeat" mode (so the single letterhead page applies to every document page)
6. Click Submit

### 12.11 Convert Scanned Multi-Photo Pages

**Goal:** You scanned a batch of physical photos on a flatbed scanner, with multiple photos per scan. Separate them into individual images.

1. Upload the scan PDF to **Extract Image Scans**
2. The tool detects individual photo boundaries on each page
3. Download the separated, cropped images

---

## 13. How It Works

### 13.1 Architecture Overview

Stirling-PDF uses a layered architecture:

- **Frontend**: React application built with TypeScript and the Mantine UI framework. In Docker, it is served by the container's web server. In the desktop app, it renders inside a Tauri webview.
- **Backend**: Spring Boot 4.0.5 application running on Java 21 that exposes the REST API at `/api/v1/` and handles all PDF processing.
- **Processing engines**: Apache PDFBox for core PDF manipulation, LibreOffice for office document conversion, Tesseract for OCR, Ghostscript and qpdf for specialized tasks, and various other libraries for specific operations.

### 13.2 Processing Flow

When you submit a PDF operation:

1. The frontend uploads the file(s) to the backend via multipart REST API call
2. The backend validates the request, checks file size limits, and verifies the operation is enabled
3. The appropriate processor handles the operation using in-memory buffers or temporary files
4. The result is streamed back as a file download response
5. No files are stored permanently on the server -- temporary files are cleaned up after the response

### 13.3 Privacy Model

All processing happens locally within your Docker container or desktop application:

- No files are transmitted to external servers under any circumstances
- No telemetry, analytics, or usage data is collected or phoned home
- When `METRICS_ENABLED` is true, it only enables local Prometheus-compatible metrics endpoints -- no data is sent externally
- No internet connection is required after initial installation (except for downloading OCR language packs via `TESSERACT_LANGS`)

### 13.4 Supported PDF Standards

Stirling-PDF processes:

- PDF versions 1.0 through 2.0
- PDF/A variants (1b, 2b, 3b) for archival compliance
- Encrypted PDFs (when the correct password is supplied)
- Tagged PDFs with accessibility structures
- PDFs containing embedded fonts, images, forms, annotations, JavaScript, and attachments

---

## 14. Troubleshooting

> [!WARNING]
> When troubleshooting any issue, always check container logs first: `docker logs stirling-pdf --tail 200`. The Java stack traces contain the specific error cause, which is often more informative than the message shown in the browser UI.

### Error: Container crashes immediately after starting

**Cause:** Insufficient memory allocated to Docker. The `:fat` image requires at least 6 GB.

**Solution:**
1. Check Docker resource limits: Docker Desktop, then Settings, then Resources, then Memory
2. Increase memory to at least 6 GB for `:fat`, 4 GB for `:latest`, 2 GB for `:ultra-lite`
3. Restart Docker Desktop after changing memory allocation
4. Restart the container: `docker compose up -d`

**Prevention:** Always set explicit memory limits in your `docker-compose.yml` under `deploy.resources.limits.memory`.

---

### Error: LibreOffice conversion fails or "File to PDF" tool is grayed out

**Cause:** LibreOffice is not installed in the container. The `:ultra-lite` image does not include LibreOffice, and `:latest` may require manual installation.

**Solution:**
- Switch to the `:fat` image, which bundles LibreOffice and all dependencies
- Or install LibreOffice manually in a custom Dockerfile extending `:latest`

**Prevention:** Use the `:fat` image from the start if you need any office document conversions (DOCX, XLSX, PPTX to PDF).

---

### Error: OCR produces empty or garbled text

**Cause:** Wrong language selected for the document, or the required language data files are missing.

**Solution:**
1. Verify the correct language is selected for your document
2. List available language data files:
   ```bash
   docker exec stirling-pdf ls /usr/share/tessdata/
   ```
3. Add missing languages via the `TESSERACT_LANGS` environment variable:
   ```yaml
   environment:
     TESSERACT_LANGS: "deu,fra,jpn"
   ```
4. Or manually download `.traineddata` files into the tessdata volume

**Prevention:** Pre-configure `TESSERACT_LANGS` in your compose file for all languages you regularly encounter.

---

### Error: Upload fails with "File too large"

**Cause:** The file exceeds the configured maximum upload size (default 100 MB).

**Solution:**
1. Increase `SYSTEM_MAXFILESIZE`:
   ```yaml
   environment:
     SYSTEM_MAXFILESIZE: "500"
   ```
2. If behind a reverse proxy, also increase the proxy's upload limit:
   - Nginx: `client_max_body_size 500M;`
   - Traefik: configure buffering middleware
   - Apache: `LimitRequestBody 524288000`
3. Restart the container after changing the variable

**Prevention:** Set `SYSTEM_MAXFILESIZE` appropriately for your largest expected files during initial setup.

---

### Error: "Permission denied" writing to mounted volumes

**Cause:** The container process runs as a different user than the host directory owner.

**Solution:**
1. Set `PUID` and `PGID` to match your host user's UID and GID:
   ```yaml
   environment:
     PUID: "1000"
     PGID: "1000"
   ```
2. Or fix host directory permissions:
   ```bash
   sudo chown -R 1000:1000 ./stirling/
   ```

**Prevention:** Always configure `PUID` and `PGID` in your compose file before first launch.

---

### Error: Health check failing or container shows "unhealthy"

**Cause:** The application has not finished starting up, or it encountered an error during initialization.

**Solution:**
1. Check container logs for startup errors:
   ```bash
   docker logs stirling-pdf --tail 100
   ```
2. If the application is still starting, increase `start_period`:
   ```yaml
   healthcheck:
     start_period: 120s
   ```
3. Verify port 8080 is not already in use on the host:
   ```bash
   ss -tlnp | grep 8080
   ```

**Prevention:** Set `start_period` to at least 60s on slower hardware or virtualized environments.

---

### Error: "Constraint already exists" during database import

**Cause:** Known issue (#4405) where importing a database backup encounters duplicate constraint definitions from schema evolution.

**Solution:**
1. Export the database from a clean, running instance of the same version
2. For cross-version migrations, perform a fresh install and re-configure rather than importing old backups

**Prevention:** Only import databases exported from the same Stirling-PDF version.

---

### Error: Split PDF into Sections removes input fields

**Cause:** Known issue (#1612). The section-splitting process renders pages as images, which does not preserve interactive form fields.

**Solution:**
- **Flatten** the PDF first if you need to preserve the visual appearance of filled form fields (the fields become static content)
- Or use **Extract Pages** instead if you only need specific pages with form fields intact

**Prevention:** Avoid section-splitting on PDFs that contain interactive form fields.

---

### Error: Windows SmartScreen blocks the desktop installer

**Cause:** Known false positive (#6120, #5600). Windows SmartScreen flags the installer because it has not yet built sufficient download reputation with Microsoft's threat intelligence systems.

**Solution:**
1. On the SmartScreen warning dialog, click **More info**
2. Click **Run anyway**
3. The application is safe -- this is a code-signing reputation issue, not malware

**Prevention:** This resolves automatically as more users install the application and SmartScreen's reputation database updates.

---

### Error: PDF conversion produces blank pages

**Cause:** The PDF uses fonts that are not available in the container, or contains complex vector graphics that fail to render during conversion.

**Solution:**
1. Install additional fonts:
   ```bash
   docker exec stirling-pdf apt-get update && \
     apt-get install -y fonts-liberation fonts-noto fonts-noto-cjk
   ```
2. Try a different conversion path (e.g., PDF to Image at high DPI, then Image to PDF)

**Prevention:** Use the `:fat` image, which includes a broader font selection.

---

### Error: OutOfMemoryError in Java logs

**Cause:** The PDF being processed requires more heap memory than the JVM is configured to use. Very large PDFs (1000+ pages, many high-resolution images) are the typical trigger.

**Solution:**
1. Increase JVM heap memory:
   ```yaml
   environment:
     JAVA_CUSTOM_OPTS: "-Xmx4g"
   ```
2. Increase the Docker container memory limit proportionally (JVM heap + overhead):
   ```yaml
   deploy:
     resources:
       limits:
         memory: 6G
   ```
3. For extremely large PDFs, split them into smaller chunks before processing

**Prevention:** Set `JAVA_CUSTOM_OPTS` with appropriate `-Xmx` values during initial deployment.

---

### Error: Slow startup time (more than 2 minutes)

**Cause:** Initialization tasks (loading fonts, warming up LibreOffice, checking dependencies, downloading OCR language packs) take time, especially on first launch or slower hardware.

**Solution:**
1. This is expected behavior on first start or after updates
2. Increase the health check `start_period` to avoid premature "unhealthy" status:
   ```yaml
   healthcheck:
     start_period: 120s
   ```
3. Use the `performance` JVM profile on capable hardware:
   ```yaml
   environment:
     STIRLING_JVM_PROFILE: "performance"
   ```

---

### Error: Cannot access the UI from another machine on the network

**Cause:** The container port mapping may be binding to localhost only, or a host firewall is blocking the port.

**Solution:**
1. Ensure the port mapping binds to all interfaces:
   ```yaml
   ports:
     - "0.0.0.0:8080:8080"
   ```
2. Check and open the host firewall:
   ```bash
   sudo ufw allow 8080/tcp
   ```
3. Verify the container is running and healthy:
   ```bash
   docker ps | grep stirling
   ```

---

### Error: Watermark not appearing on all pages

**Cause:** The watermark configuration targets specific pages instead of the entire document.

**Solution:** In the watermark tool, select "All pages" instead of specifying a page range. Alternatively, use the page selection `1-9999` to cover all pages.

---

### Error: Merge produces corrupted output

**Cause:** One or more input PDFs are malformed or use incompatible PDF features that conflict during merge.

**Solution:**
1. Run each input PDF through **Repair** first
2. Try merging a subset to identify the problematic file
3. Convert the problematic PDF to PDF/A first (which normalizes the structure), then merge

---

### Error: Certificate signing fails with "keystore" error

**Cause:** The certificate file is not in the expected `.p12`/`.pfx` format, or the certificate password is incorrect.

**Solution:**
1. Verify the certificate is in PKCS#12 format (`.p12` or `.pfx`)
2. Double-check the password (certificate passwords are case-sensitive)
3. If your certificate is in PEM format, convert it:
   ```bash
   openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12
   ```

---

### Error: PDF/A conversion fails

**Cause:** The source PDF contains elements incompatible with the PDF/A standard -- embedded multimedia, JavaScript, external font references, or non-embeddable fonts.

**Solution:**
1. Run **Sanitize PDF** first to remove JavaScript and multimedia
2. Run **Flatten** to resolve annotation and form issues
3. Retry the PDF/A conversion
4. If it still fails, the PDF likely has non-embeddable fonts -- try converting to images first, then back to PDF/A

---

### Error: Docker image pull fails with "manifest unknown"

**Cause:** The specified image tag does not exist on the registry, or there is a temporary registry issue.

**Solution:**
1. Verify the correct tag (`:latest`, `:fat`, or `:ultra-lite`):
   ```bash
   docker pull docker.stirlingpdf.com/stirlingtools/stirling-pdf:fat
   ```
2. Try Docker Hub as an alternative registry:
   ```bash
   docker pull stirlingtools/stirling-pdf:fat
   ```

---

### Error: Pipeline fails partway through

**Cause:** An operation in the pipeline produces output that is incompatible with the next operation's expected input.

**Solution:**
1. Run each pipeline step manually in sequence to identify which transition fails
2. Verify that each step's output format is accepted by the next step
3. Insert intermediate steps if needed (e.g., **Flatten** between form-related operations and image-related operations)

---

### Error: OCR is extremely slow (taking many minutes per page)

**Cause:** OCR is inherently CPU-intensive. Large pages, high resolution, or complex layouts increase processing time.

**Solution:**
1. Use "Skip text" mode to only OCR pages that lack existing text
2. Split large documents and process chunks separately
3. Allocate more CPU cores to the container:
   ```yaml
   deploy:
     resources:
       limits:
         cpus: "4"
   ```
4. Reduce input image resolution if acceptable for your use case

---

### Error: Fonts display incorrectly after conversion

**Cause:** The PDF references fonts that are not embedded in the file and are not available in the container's font library.

**Solution:**
1. Install the required fonts inside the container:
   ```bash
   docker exec -it stirling-pdf bash
   apt-get update && apt-get install -y fonts-liberation2 fonts-noto-cjk
   ```
2. For persistent font installations, mount a host fonts directory or extend the Dockerfile
3. Restart the container after installing fonts

---

### Error: API returns 413 (Request Entity Too Large)

**Cause:** The reverse proxy in front of Stirling-PDF has a lower upload size limit than the application itself.

**Solution:**
- **Nginx:** `client_max_body_size 500M;` in the location or server block
- **Traefik:** Configure buffering middleware with appropriate `maxRequestBodyBytes`
- **Apache:** `LimitRequestBody 524288000` in the virtual host or directory configuration
- **Caddy:** `request_body { max_size 500MB }` in the site block

---

### Error: "The document has no pages" after split or extract

**Cause:** The page selection expression evaluated to an empty set -- no pages matched the criteria.

**Solution:**
1. Check the total page count with **Get PDF Info**
2. Review the page selection expression for off-by-one errors or out-of-range page numbers
3. Test with a simple range first (e.g., `1-5`) before using complex expressions

---

### Error: Annotations lost after merge

**Cause:** Certain merge modes do not transfer interactive annotation data from all input documents.

**Solution:**
1. If annotations must remain visible, **Flatten** each input PDF before merging (annotations become permanent page content)
2. If annotations must stay interactive, try merging fewer files at a time

---

### Error: Cannot save settings -- "Read-only file system"

**Cause:** The `/configs` volume is not mounted, is mounted read-only, or the container user lacks write permission.

**Solution:**
1. Ensure the volume is mounted with `rw` access:
   ```yaml
   volumes:
     - ./stirling/config:/configs:rw
   ```
2. Verify host directory permissions and ownership:
   ```bash
   ls -la ./stirling/config/
   sudo chown -R 1000:1000 ./stirling/config/
   ```

---

> [!CAUTION]
> Auto-redact uses pattern matching and may miss sensitive data in unusual formats (international phone numbers, non-standard identifiers, handwritten text in scanned documents). Never rely solely on auto-redact for compliance-critical redactions. Always follow up with a manual review of the output document.

### Error: Auto-redact misses some sensitive data

**Cause:** Auto-redact relies on regular expression pattern matching. Unusual formats (international phone numbers, custom identifiers, abbreviations) may not match the built-in patterns.

**Solution:**
1. Run auto-redact first to catch standard patterns
2. Follow up with manual **Redact** to handle anything that was missed
3. Use custom regex patterns if the tool supports them for your specific data format
4. Always verify by searching the output PDF for the sensitive terms

**Prevention:** Build a pipeline that runs auto-redact followed by manual review for any compliance-critical use case.

---

### Error: PDF comparison shows no differences when differences exist

**Cause:** The comparison operates on text content. If differences are purely visual (font rendering, image quality, spacing) they may not be detected as text-level changes.

**Solution:** For visual comparison, convert both PDFs to images at the same DPI using **PDF to Image**, then use an external image comparison tool.

---

### Error: Booklet imposition produces incorrect page order

**Cause:** The source PDF page count is not a multiple of 4. Booklet printing requires page counts divisible by 4.

**Solution:** Add blank pages to make the total count a multiple of 4 before running booklet imposition. For example, for a 14-page document, add 2 blank pages to reach 16.

---

### Error: Downloaded file is 0 bytes or empty

**Cause:** The processing operation failed silently, or a browser extension intercepted the download.

**Solution:**
1. Check the container logs for errors during the failed operation
2. Try in a private/incognito browser window (disables extensions)
3. Try a different browser
4. Use the API directly with curl to bypass browser-related issues

---

### Error: Application language does not change after setting locale

**Cause:** The locale change may require a container restart, or the specified locale is not supported.

**Solution:**
1. Set `SYSTEM_DEFAULTLOCALE` to a supported locale code (e.g., `en-US`, `de-DE`, `fr-FR`, `ja-JP`)
2. Restart the container:
   ```bash
   docker compose restart stirling-pdf
   ```
3. Clear browser cache and cookies for the application

---

## 15. Frequently Asked Questions

**Q: Is Stirling-PDF really free?**
Stirling-PDF is open source. The self-hosted version includes all core features at no cost. Some advanced features in the SaaS/proprietary edition may have different licensing.

---

**Q: Does Stirling-PDF send my files to any server?**
No. All processing occurs locally within your Docker container or desktop application. No files, metadata, or telemetry are transmitted to external servers. This is a core design principle of the project.

---

**Q: What is the maximum file size I can process?**
The default limit is 100 MB, controlled by `SYSTEM_MAXFILESIZE`. You can increase this to any value your hardware supports. Very large files require proportional memory allocation.

---

**Q: Which Docker image should I use?**
- `:fat` if you need all features (office conversion, OCR, all fonts) and have 6+ GB memory
- `:latest` if you manage LibreOffice and Tesseract installations yourself
- `:ultra-lite` if you only need basic PDF operations and want the smallest, fastest image

---

**Q: How do I update to a new version?**
Pull the latest image and restart:
```bash
docker compose pull
docker compose up -d
```
Data persists in mounted volumes. No configuration or data is lost during updates.

---

**Q: Can I run multiple instances behind a load balancer?**
Yes. Processing is stateless -- each request is self-contained. Run multiple `MODE=BOTH` containers behind any load balancer, or use `MODE=FRONTEND` with multiple `MODE=BACKEND` instances for horizontal scaling.

---

**Q: How do I add OCR support for my language?**
Set `TESSERACT_LANGS` with comma-separated Tesseract language codes:
```yaml
environment:
  TESSERACT_LANGS: "deu,fra,spa,jpn,chi_sim,kor,ara"
```
The container downloads the language data automatically on startup.

---

**Q: Can I use Stirling-PDF without Docker?**
Yes. Build from source with Java 21 and Gradle, or install the desktop application (available for Windows, macOS, and Linux). The desktop app packages everything needed to run locally.

---

**Q: Does Stirling-PDF support batch processing?**
Yes, through multiple methods:
1. Multi-file upload in the web UI for supported tools
2. The REST API for scripted automation (any programming language that can make HTTP requests)
3. Pipelines for chaining multiple operations
4. Watched folder automation for file-drop processing

---

**Q: How do I enable HTTPS?**
Stirling-PDF serves HTTP on port 8080. Place a reverse proxy (Traefik, Nginx, Caddy) in front of it to terminate TLS/SSL. See Section 11.4 for proxy configuration examples and the [Admin Guide](Stirling-Tools__Stirling-PDF__AdminGuide.md) for complete deployment configurations.

---

**Q: What happens if the container crashes during processing?**
No files are permanently stored on the server. Re-upload the file and try again after restarting the container. Your original file is never modified by any Stirling-PDF operation.

---

**Q: Can I customize the UI appearance?**
Yes. Mount the `/customFiles` volume and add custom CSS, logos, and branding. Use environment variables `UI_APPNAME`, `UI_HOMEDESCRIPTION`, and `UI_APPNAMENAVBAR` for text customization.

---

**Q: Which browsers are supported?**
All modern browsers: Chrome, Firefox, Safari, Edge, and their derivatives. Internet Explorer is not supported.

---

**Q: Is there an API rate limit?**
The self-hosted version has no built-in rate limiting. For production deployments serving many users, configure rate limiting in your reverse proxy.

---

**Q: How do I secure my instance for multi-user access?**
1. Set `DOCKER_ENABLE_SECURITY=true` and `SECURITY_ENABLELOGIN=true`
2. Configure initial admin credentials in `settings.yml`
3. Set `SECURITY_CUSTOMGLOBALAPIKEY` if API access needs authentication
4. Place behind a reverse proxy with HTTPS
5. See the [Admin Guide](Stirling-Tools__Stirling-PDF__AdminGuide.md) for full security hardening.

---

**Q: What PDF versions does Stirling-PDF support?**
PDF 1.0 through 2.0, including all PDF/A archival variants. Encrypted PDFs are supported when the correct password is provided.

---

**Q: Can I process password-protected PDFs?**
Yes. Tools that operate on encrypted PDFs prompt for the password. Use **Remove Password** to permanently decrypt a file (requires the current password).

---

**Q: Does the desktop app have the same features as Docker?**
The desktop app includes all core features. Features dependent on LibreOffice or Tesseract require those tools to be available on your system. Some desktop builds bundle these dependencies, while others require separate installation.

---

**Q: How do I report a bug or request a feature?**
Open an issue on the [GitHub repository](https://github.com/Stirling-Tools/Stirling-PDF/issues). Include the Stirling-PDF version, Docker image variant, browser and OS information, and detailed steps to reproduce.

---

**Q: What is the difference between "Add Watermark" and "Add Stamp"?**
A **watermark** is typically semi-transparent text or an image placed as a background mark (behind or over content, usually at reduced opacity). A **stamp** is an opaque, clearly visible label placed on top of page content, such as "CONFIDENTIAL", "APPROVED", or "DRAFT".

---

**Q: Can I run Stirling-PDF on a Raspberry Pi or other ARM device?**
Yes, with limitations. Use the `:ultra-lite` image for the smallest resource footprint. ARM images are available. Expect slower performance on ARM devices, especially for OCR and office document conversions. The `:fat` image may exceed the memory available on most Raspberry Pi models.

---

**Q: How do I handle non-Latin scripts (Arabic, Chinese, Japanese, Korean, Hindi)?**
1. Install OCR language data for the relevant languages (see Section 7.1)
2. Install CJK and multilingual fonts inside the container:
   ```bash
   apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-noto
   ```
3. Set `SYSTEM_DEFAULTLOCALE` to match your primary audience

---

**Q: What is the Pipeline feature?**
Pipelines chain multiple PDF operations into a single automated workflow. Define a sequence like OCR, then compress, then watermark, then encrypt -- and run it with one click or one API call instead of four separate steps.

---

**Q: Can Stirling-PDF handle scanned images that are not yet PDFs?**
Yes. Use **Image to PDF** to convert scanned images (JPEG, PNG, TIFF) to PDF format. Then apply **OCR PDF** to make the text searchable. **Extract Image Scans** can also split a flatbed scan of multiple photos into individual cropped images.

---

**Q: How do I integrate Stirling-PDF into my existing application or workflow?**
Use the REST API. Every operation available in the web UI has a corresponding API endpoint. The Swagger documentation at `/swagger-ui/index.html` provides the complete API reference with request parameters, response formats, and interactive testing.

---

**Q: Does Stirling-PDF modify my original file?**
Never. Every operation produces a new output file. The uploaded original is processed in memory, used as input, and discarded after the result is generated. Your source file is never written to or altered.

---

**Q: What exactly does "sanitize" do?**
Sanitization removes potentially dangerous or privacy-leaking content: embedded JavaScript (malware risk), file attachments (malware delivery), metadata (author name, GPS coordinates, creation software, edit history), and automatic actions (URLs that open on document load, print triggers).

---

**Q: Can I use Stirling-PDF with a CI/CD pipeline?**
Yes. Run Stirling-PDF as a service in your CI environment and call its API endpoints from your pipeline scripts. For example, in a GitHub Actions workflow, start the container in the background, wait for the health check, then use curl to process documents.

---

**Q: What is the difference between "Extract Pages" and "Split Pages"?**
**Extract Pages** produces a single PDF containing only the pages you specify. **Split Pages** divides a PDF into multiple separate files at the page numbers you specify. For example, with a 20-page PDF: "Extract 5-10" gives you one 6-page PDF. "Split at 5, 10" gives you three PDFs (pages 1-4, 5-9, 10-20).

---

**Q: How do I process a large number of files efficiently?**
1. Use the API for parallel processing from a script
2. Create a pipeline for multi-step workflows and submit files via the pipeline API
3. Use watched folders for continuous automated processing
4. If running via API, you can make concurrent requests -- each is processed independently

---

**Q: Is the "Scanner Effect" tool the opposite of OCR?**
Not exactly. OCR converts images of text into machine-readable text. Scanner Effect makes a digital PDF look like it was scanned (adding visual noise, slight rotation, and other artifacts) but does not remove the underlying text. The text remains searchable after applying the scanner effect.

---

_Generated May 2026 from Stirling-Tools/Stirling-PDF at 79f4748. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._