Stirling PDF

https://docs.stirlingpdf.com/
Admin
Stirling PDF is a comprehensive open-source PDF manipulation tool providing 50+ features including...
Tokens:33,828
Snippets:488
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Frontend Dependencies

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Navigate to the frontend directory and install project dependencies using npm. Ensure Node.js and npm are installed.

```bash
# Navigate to frontend directory  

cd frontend  

# Install dependencies  

npm install  
```

--------------------------------

### Install Stirling PDF with Winget Parameters

Source: https://docs.stirlingpdf.com/Installation/Managed%20Deployment

Install Stirling PDF using winget, passing custom parameters for server URL and connection locking during a silent installation.

```bash
winget install StirlingTools.StirlingPDF \
  --custom "STIRLING_SERVER_URL=http://192.168.1.53:8080 STIRLING_LOCK_CONNECTION=1" \


```

--------------------------------

### Install Prerequisites on Fedora-based Systems

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs necessary development tools and libraries for Stirling PDF on Fedora-based Linux distributions.

```bash
sudo dnf install -y git automake autoconf libtool \ 
    leptonica-devel pkg-config zlib-devel make gcc-c++ \ 
    java-25-openjdk python3 python3-pip  
```

--------------------------------

### Install Tesseract OCR Languages (Fedora)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Searches for and lists installed Tesseract OCR language packs on Fedora systems. Uncomment the 'All languages' line to install all packs.

```bash
# All languages  

# sudo dnf install -y tesseract-langpack-*  

  

# Find languages:  

dnf search -C tesseract-langpack-  

  

# View installed languages:  

rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g'
```

--------------------------------

### Full Configuration Example

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Comprehensive configuration settings for security, system, and UI.

```yaml
security:
  enableLogin: true  # Only works with Stirling-PDF-with-login.jar or DISABLE_ADDITIONAL_FEATURES=false
  jwt:
    tokenExpiryMinutes: 1440
  validation:
    trust:
      serverAsAnchor: true
      useSystemTrust: true
      useMozillaBundle: true
    revocation:
      mode: ocsp
      hardFail: false
  
system:
  defaultLocale: 'en-US' # Set the default language (e.g. 'de-DE', 'fr-FR', etc)
  googlevisibility: false # 'true' to allow Google visibility (via robots.txt), 'false' to disallow
  serverCertificate:
    enabled: true
    organizationName: Stirling-PDF
    validity: 365
  
mail:
  enabled: false
  enableInvites: false
  
ui:
  logoStyle: classic  

```

--------------------------------

### Install Prerequisites on Debian-based Systems

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs essential development tools and libraries required for Stirling PDF on Debian-based Linux distributions.

```bash
sudo apt-get update  
sudo apt-get install -y git automake autoconf libtool \ 
    libleptonica-dev pkg-config zlib1g-dev make g++ \ 
    openjdk-25-jdk python3 python3-pip  
```

--------------------------------

### Docker Quick Start

Source: https://docs.stirlingpdf.com/

Run Stirling PDF using Docker with a quick start command. This maps port 8080 and mounts a local directory for configuration.

```bash
docker run -d \
  -p 8080:8080 \
  -v ./stirling-data:/configs \
  stirlingtools/stirling-pdf:latest  

```

--------------------------------

### Install Additional Software on Fedora-based Systems

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs LibreOffice, Tesseract OCR, and Python packages for Stirling PDF on Fedora-based systems.

```bash
sudo dnf install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseract  
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint  
```

--------------------------------

### Start unoserver for Stirling PDF

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Run this command to start the unoserver, which is required for certain Stirling PDF functionalities. It's recommended to add this to your startup script or systemd service file for automatic startup.

```shell
unoserver --port 2003 --interface 0.0.0.0
```

--------------------------------

### Install Additional Software using Nix Package Manager

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs LibreOffice, Tesseract, and necessary Python packages via Nix and pip.

```bash
nix-env -iA nixpkgs.libreoffice nixpkgs.tesseract nixpkgs.poppler_utils  
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint  
```

--------------------------------

### Install Optional Dependencies for Stirling PDF

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Installs various command-line tools and libraries via Homebrew and pip that enable advanced features in Stirling PDF, such as document conversion, OCR, and PDF compression. Homebrew is installed if it's not already present.

```bash
# Install Homebrew if needed  
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  

# Install dependencies as needed  
brew install openjdk@25          # Required  
brew install qpdf                # PDF compression  
brew install --cask libreoffice  # Document conversion  
brew install tesseract           # OCR functionality  
brew install tesseract-lang      # Additional OCR languages  
brew install poppler             # PDF to HTML conversion  
pip3 install weasyprint          # URL to PDF conversion  
pip3 install unoserver           # File to PDF conversion  
```

--------------------------------

### Install Stirling PDF Helm Chart

Source: https://docs.stirlingpdf.com/Installation/Kubernetes%20Install

Add the Stirling PDF Helm repository and install the chart. This command also creates the namespace if it doesn't exist.

```bash
helm repo add stirling-pdf https://stirling-tools.github.io/Stirling-PDF-chart  

helm repo update  

helm install stirling-pdf stirling-pdf/stirling-pdf-chart --namespace stirling-pdf --create-namespace  
```

--------------------------------

### Install Stirling PDF with MSI Parameters

Source: https://docs.stirlingpdf.com/Installation/Managed%20Deployment

Use this command to perform a silent MSI installation on Windows, configuring server URL, connection locking, and update mode for all users.

```bash
msiexec /i "Stirling-PDF-windows-x86_64.msi" /qn \

  STIRLING_SERVER_URL="http://192.168.1.53:8080" \

  STIRLING_LOCK_CONNECTION=1 \

  STIRLING_UPDATE_MODE=disabled \

  ALLUSERS=1  


```

--------------------------------

### Enable Stirling PDF Service

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Enable the Stirling PDF service to start automatically on system boot.

```bash
sudo systemctl enable stirlingpdf.service
```

--------------------------------

### Install Homebrew and Java 25 on Mac

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Installs Homebrew if not present, then installs Java 25 and configures the PATH environment variable. Add the export line to your ~/.zshrc file to make the PATH change permanent.

```bash
# Install Homebrew if you don't have it  
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  

# Install Java 25  
brew install openjdk@25  

# Add to your PATH (add to ~/.zshrc to make permanent)  
# Using `brew --prefix` keeps this correct on both Apple Silicon (/opt/homebrew) and Intel (/usr/local)  
export PATH="$(brew --prefix openjdk@25)/bin:$PATH"  
```

--------------------------------

### Basic Configuration Example

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

A minimal configuration file to change the server port and set logging levels for different packages. Useful for basic adjustments.

```yaml
# custom_settings.yml
server:
  port: 9000

logging:
  level:
    root: INFO
    org.springframework: WARN
    org.hibernate: WARN
    stirling.software.SPDF: INFO

```

--------------------------------

### Install jbig2enc using Nix Package Manager

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs the jbig2enc library directly using the Nix package manager.

```bash
nix-env -iA nixpkgs.jbig2enc  
```

--------------------------------

### Install JAR and Scripts (Nix Non-root)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Moves the Stirling-PDF.jar and the scripts folder to the user's home directory. This is for non-root installations on Nix systems.

```bash
mkdir -p ~/Stirling-PDF &&\

mv Stirling-PDF.jar ~/Stirling-PDF/ &&\

cp -r Stirling-PDF/scripts ~/Stirling-PDF/
```

--------------------------------

### macOS Configuration Example

Source: https://docs.stirlingpdf.com/Installation/Managed%20Deployment

Example JSON configuration for Stirling PDF on macOS to set a self-hosted server, lock connection mode, and disable updates.

```json
{ "serverUrl": "https://pdf.example.com", "lockConnectionMode": true, "updateMode": "disabled" }
```

--------------------------------

### Run Backend and Frontend Concurrently

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Use this command from the repository root to start both the backend and frontend development servers simultaneously.

```bash
# From the repository root - starts backend + frontend concurrently  
task dev  
```

--------------------------------

### Minimal V2 Configuration

Source: https://docs.stirlingpdf.com/Migration/Settings-Changes

This is a minimal configuration example for V2, demonstrating default settings that work out of the box. New V2 features utilize sensible defaults, reducing the need for extensive configuration.

```yaml
security:
  enableLogin: false
  
system:
  defaultLocale: en-US
  
ui:
  appNameNavbar: ''

```

--------------------------------

### Start Frontend Development Server

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Start the Vite development server from the repository root using the Task command runner. The frontend will be available at http://localhost:5173. Ensure the backend is running as the dev server proxies API requests to it.

```bash
# Start the Vite dev server (runs `npx vite editor` under the hood)  

task frontend:dev  
```

--------------------------------

### Install Stirling PDF on Proxmox LXC

Source: https://docs.stirlingpdf.com/Installation/Docker%20Install

Execute a one-line bash command to install Stirling PDF as an LXC container on Proxmox VE. This script installs necessary dependencies and sets up Stirling PDF as a systemd service.

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/stirling-pdf.sh)"  
```

--------------------------------

### Install Prerequisites using Nix Package Manager

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs required software packages using the Nix package manager, including Java, Git, and Python.

```bash
nix-channel --update  
nix-env -iA nixpkgs.jdk25 nixpkgs.git nixpkgs.python38 \ 
    nixpkgs.gnumake nixpkgs.libgcc nixpkgs.automake \ 
    nixpkgs.autoconf nixpkgs.libtool nixpkgs.pkg-config \ 
    nixpkgs.zlib nixpkgs.leptonica  
```

--------------------------------

### Install DEB Package

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Download and install the Stirling PDF desktop application using the DEB package for Debian/Ubuntu-based systems.

```bash
wget https://files.stirlingpdf.com/linux-installer.deb

sudo dpkg -i linux-installer.deb
```

--------------------------------

### Install via AUR Helper

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Install the Stirling PDF desktop application from the Arch User Repository (AUR) using an AUR helper like paru or yay.

```bash
paru -S stirling-pdf-desktop
# or: yay -S stirling-pdf-desktop
```

--------------------------------

### Install Additional Software on Debian-based Systems

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs LibreOffice, Tesseract OCR, and Python packages required for Stirling PDF on Debian-based systems.

```bash
sudo apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseract-ocr  
pip3 install uno opencv-python-headless unoserver pngquant WeasyPrint --break-system-packages  
```

--------------------------------

### Run Frontend Development Server

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Execute this command in a separate terminal to start the frontend development server.

```bash
task frontend:dev  
```

--------------------------------

### Install RPM Package

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Download and install the Stirling PDF desktop application using the RPM package for Fedora/RHEL-based systems.

```bash
wget https://files.stirlingpdf.com/linux-installer.rpm

sudo dnf install ./linux-installer.rpm
```

--------------------------------

### Install FUSE on Ubuntu

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Install the FUSE library on Ubuntu 22.04+ if you encounter 'fuse: device not found' errors when running the AppImage.

```bash
sudo apt-get install libfuse2
```

--------------------------------

### Install Calibre in Dockerfile

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

If Calibre is not found, you can install it directly within your Dockerfile by adding this command.

```dockerfile
# In your Dockerfile
RUN apt-get update && apt-get install -y calibre
```

--------------------------------

### Run Backend Development Server

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Execute this command in a separate terminal to start the backend development server.

```bash
./gradlew bootRun  
```

--------------------------------

### Install Stirling PDF via Homebrew

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Installs the Stirling PDF desktop application using Homebrew Cask. Ensure the tap has been added first.

```bash
brew install --cask stirling-pdf
```

--------------------------------

### V2 UI Configuration (YAML)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of the V2 configuration structure for UI settings in YAML. Note that 'appName' and 'homeDescription' are removed and must be configured in-app.

```yaml
ui:
  appNameNavbar: 'My PDF Tool'  # Still in YAML
  # appName and homeDescription REMOVED
  # Configure these in-app instead
```

--------------------------------

### Install Tesseract OCR (Nix)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Installs the Tesseract OCR package using the Nix package manager. Nix typically pre-installs most language packs with the base package.

```bash
nix-env -iA nixpkgs.tesseract
```

--------------------------------

### Install JAR and Scripts (Debian/Fedora Root)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Moves the Stirling-PDF.jar and the scripts folder to the /opt/Stirling-PDF directory. This is for systems requiring root privileges.

```bash
sudo mkdir -p /opt/Stirling-PDF &&\

sudo mv Stirling-PDF.jar /opt/Stirling-PDF/ &&\

sudo cp -r Stirling-PDF/scripts /opt/Stirling-PDF/ &&\

echo "JAR and scripts installed."
```

```bash
sudo mkdir -p /opt/Stirling-PDF &&\

sudo mv Stirling-PDF.jar /opt/Stirling-PDF/ &&\

sudo cp -r Stirling-PDF/scripts /opt/Stirling-PDF/ &&\

echo "JAR and scripts installed."
```

--------------------------------

### Start Stirling PDF with Docker Compose

Source: https://docs.stirlingpdf.com/Installation/Docker%20Install

Execute this command after creating the docker-compose.yml file to bring up the Stirling PDF service.

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

--------------------------------

### V1 UI Configuration (YAML)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of the V1 configuration structure for UI settings in YAML format. This format is no longer supported for certain UI parameters.

```yaml
ui:
  appName: 'My PDF Tool'
  homeDescription: 'Welcome to our PDF service!'
```

--------------------------------

### Install Tesseract OCR Languages (Debian)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Updates package lists and searches for available Tesseract OCR language packs on Debian-based systems. Uncomment the 'All languages' line to install all packs.

```bash
sudo apt update &&\

# All languages  

# sudo apt install -y 'tesseract-ocr-*'  

  

# Find languages:  

apt search tesseract-ocr-  

  

# View installed languages:  

dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g'
```

--------------------------------

### Build Desktop Application

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Build the Tauri desktop application from the repository root using the Task command runner. Requires Rust and Cargo to be installed.

```bash
# Build desktop application (runs `npx tauri build`)  

task desktop:build  
```

--------------------------------

### Run AppImage

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Download, make executable, and run the Stirling PDF desktop application using the AppImage format. No installation is required.

```bash
wget https://files.stirlingpdf.com/linux-installer.AppImage
chmod +x linux-installer.AppImage
./linux-installer.AppImage
```

--------------------------------

### Full Stirling PDF Docker Setup

Source: https://docs.stirlingpdf.com/Installation/Docker%20Install

This command sets up Stirling PDF with all features, including OCR, custom settings, and logging, by mounting necessary volumes and configuring environment variables.

```bash
docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data/tessdata:/usr/share/tessdata \
  -v ./stirling-data/configs:/configs \
  -v ./stirling-data/logs:/logs \
  -v ./stirling-data/pipeline:/pipeline \
  -e SECURITY_ENABLELOGIN=false \
  -e SYSTEM_DEFAULTLOCALE=en-GB \
  stirlingtools/stirling-pdf:latest
```

--------------------------------

### V1 Docker Compose Configuration

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of a V1 docker-compose.yml service configuration using the old image tag.

```yaml
services:
  stirling-pdf:
    image: stirlingtools/s-pdf:latest  # OLD
```

--------------------------------

### Environment Variables Configuration

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Example of environment variables for disabling features, enabling login, JWT keystore, and server certificates.

```yaml
environment:
  DISABLE_ADDITIONAL_FEATURES: false
  SECURITY_ENABLELOGIN: true
  SECURITY_JWT_ENABLEKEYSTORE: true
  SYSTEM_SERVERCERTIFICATE_ENABLED: true  

```

--------------------------------

### V1 Session Management Configuration (YAML)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of V1 session management configuration using YAML. This structure is replaced by a new format in V2.

```yaml
security:
  jwt:
    enabled: false
    keyCleanup: false
    secureCookie: true
```

--------------------------------

### Production HTTPS Configuration

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example configuration for enabling SSL/HTTPS in production, required for V2's secure cookie enforcement.

```yaml
server:
  ssl:
    enabled: true
    key-store: /path/to/keystore.p12
    key-store-password: ${SSL_PASSWORD}
```

--------------------------------

### Clone Stirling PDF Repository

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Clone the Stirling PDF repository and navigate into the project directory. Ensure Git is installed.

```bash
git clone https://github.com/Stirling-Tools/Stirling-PDF.git  

cd Stirling-PDF  
```

--------------------------------

### Update settings.yml for Endpoint Customization (V1)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of V1 endpoint customization in settings.yml, specifying tool IDs to remove.

```yaml
endpoints:
  toRemove: ['pdf-organizer']
```

--------------------------------

### Run Desktop App in Development

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Run the Tauri desktop application in development mode from the repository root using the Task command runner. Requires Rust and Cargo to be installed.

```bash
# Run desktop app in development mode (runs `npx tauri dev`)  

task desktop:dev  
```

--------------------------------

### Start V1 with Updated Docker Compose

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Update the Docker Compose file to specify the V1 image version and then restart the services to complete the rollback.

```yaml
# Update docker-compose.yml  
image: stirlingtools/stirling-pdf:1.5.0  
  
docker-compose up -d  
```

--------------------------------

### Customize Paths in settings.yml

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Example configuration for customizing paths in the 'settings.yml' file. This allows overriding default directories for pipeline watched/finished folders and executable paths for WeasyPrint and Unoconvert.

```yaml
system:
  customPaths:
    pipeline:
      watchedFoldersDir: "" #Defaults to /pipeline/watchedFolders  
      finishedFoldersDir: "" #Defaults to /pipeline/finishedFolders  
    operations:
      weasyprint: "" #Defaults to /opt/venv/bin/weasyprint  
      unoconvert: "" #Defaults to /opt/venv/bin/unoconvert  
```

--------------------------------

### V2 Docker Compose Configuration

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of a V2 docker-compose.yml service configuration using the new image tag. Update your compose file accordingly.

```yaml
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest  # NEW
```

--------------------------------

### Update settings.yml for Endpoint Customization (V2)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of V2 endpoint customization in settings.yml, using the new tool ID 'reorganize-pages'.

```yaml
endpoints:
  toRemove: ['reorganize-pages']
```

--------------------------------

### HTTPS Configuration with Custom Certificate

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

Configure HTTPS with a custom certificate and specify logging levels. This example combines SSL settings with logging configurations in a single settings file.

```yaml
# custom_settings.yml
server:
  port: 8443
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: your-keystore-password
    key-store-type: PKCS12
    key-alias: tomcat

logging:
  level:
    root: INFO
    org.springframework: WARN

```

--------------------------------

### Example Audit Log Entry

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

An example of a structured audit log entry detailing a database backup operation.

```json
{
  "timestamp": "2025-01-15T10:30:00Z",
  "user": "admin",
  "action": "database.backup",
  "status": "success",
  "details": {
    "size": "1.2 GB",
    "duration": "45s",
    "location": "/backups/db-2025-01-15.sql"
  }
}
```

--------------------------------

### Full Project Build with Frontend Bundled

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

This command performs a full build, including bundling the frontend into the backend JAR. Use the '-PbuildWithFrontend=true' flag.

```bash
# Full build with the frontend bundled into the backend JAR  
./gradlew clean build -PbuildWithFrontend=true  
```

--------------------------------

### V2 Session Management Configuration (YAML)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example of V2 session management configuration using YAML. Demonstrates renamed and new JWT settings, with 'secureCookie' removed.

```yaml
security:
  jwt:
    persistence: true           # was 'enabled'
    enableKeyCleanup: true      # was 'keyCleanup'
    enableKeyRotation: true     # NEW
    keyRetentionDays: 7         # NEW
    # secureCookie REMOVED
```

--------------------------------

### Verify Calibre Installation in Docker

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Use this command to verify if Calibre is installed and accessible within the Stirling PDF Docker container.

```bash
docker exec stirling-pdf which ebook-convert
```

--------------------------------

### Apply Code Formatting with Spotless

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Apply code formatting using Spotless via Gradle. It is recommended to run this before committing changes.

```bash
# Apply formatting (run before committing)  

./gradlew spotlessApply  
```

--------------------------------

### Example Authenticated API Request

Source: https://docs.stirlingpdf.com/API

Demonstrates an example of an authenticated POST request to the /api/v1/security/add-watermark endpoint, including the API key in the header.

```curl
curl -X POST "http://localhost:8080/api/v1/security/add-watermark" \
     -H "X-API-KEY: your-api-key-here" \
     -H "Content-Type: multipart/form-data" \
     ...
```

--------------------------------

### Create Stirling PDF Startup Script

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Creates a shell script named 'run-stirling.sh' in the user's home directory for easy launching of the Stirling PDF server. The script navigates to the Downloads folder and executes the JAR.

```bash
#!/bin/bash  
cd ~/Downloads  # Change to where your JAR is located  
java -jar Stirling-PDF.jar  
```

--------------------------------

### Configure HTTPS with Settings File

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

Enable HTTPS by configuring SSL settings in the application's settings file. Ensure the keystore file and its password are correctly specified.

```yaml
server:
  port: 8443
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: your-keystore-password
    key-store-type: PKCS12
    key-alias: tomcat

```

--------------------------------

### Build Backend Only

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

This command builds only the backend. The frontend is not bundled unless explicitly requested.

```bash
# Backend only (default - the frontend is not bundled unless asked for)  
./gradlew clean build  
```

--------------------------------

### Run All Tests

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Execute all unit and integration tests for the project using Gradle.

```bash
# Run all tests  

./gradlew test  
```

--------------------------------

### Configure via Environment Variables (Export)

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Set environment variables to enable login and disable additional features.

```bash
export DISABLE_ADDITIONAL_FEATURES=false
export SECURITY_ENABLELOGIN=true  
```

--------------------------------

### Manage Stirling PDF Service Lifecycle

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Manually control the Stirling PDF service by starting, stopping, or restarting it.

```bash
sudo systemctl start stirlingpdf.service
```

```bash
sudo systemctl stop stirlingpdf.service
```

```bash
sudo systemctl restart stirlingpdf.service
```

--------------------------------

### Configure Login Agreement via Environment Variables

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Set environment variables to configure the login agreement, including enabling it, showing it in anonymous mode, and providing fallback text.

```bash
LEGAL_LOGINAGREEMENT_ENABLED=true
LEGAL_LOGINAGREEMENT_SHOWINANONYMOUSMODE=true
LEGAL_LOGINAGREEMENT_FALLBACKTEXT="By signing in you agree to the terms..."
```

--------------------------------

### Enable User Login Configuration

Source: https://docs.stirlingpdf.com/Configuration

Configure user login by setting 'enableLogin' to true and defining initial username and password in the settings file. Alternatively, use environment variables.

```yaml
security:
  enableLogin: true
  initialLogin:
    username: admin
    password: changeme123
```

```env
SECURITY_ENABLELOGIN=true
SECURITY_INITIALLOGIN_USERNAME=admin
SECURITY_INITIALLOGIN_PASSWORD=changeme123
```

--------------------------------

### V1 to V2 Configuration Comparison

Source: https://docs.stirlingpdf.com/Migration/Settings-Changes

This comparison highlights the differences in configuration between V1 and V2. It shows deprecated settings, new sections, and changed values to aid in migration.

```yaml
security:
  jwt:
    enabled: false
    keyCleanup: false
    secureCookie: true
  
ui:
  appName: 'My PDF Tool'
  homeDescription: 'Welcome!'
  appNameNavbar: 'PDF Tool'
  
premium:
  proFeatures:
    googleDrive:
      enabled: false

```

```yaml
security:
  jwt:
    persistence: true  # Changed  
    enableKeyRotation: true  # NEW  
    enableKeyCleanup: true  # Changed  
    keyRetentionDays: 7
  validation:  # NEW section
    trust:
      serverAsAnchor: true
      useSystemTrust: true
  
system:
  serverCertificate:  # NEW section
    enabled: true
    organizationName: Stirling-PDF
  
ui:
  appNameNavbar: 'PDF Tool'
  logoStyle: classic  # NEW
  # appName and homeDescription removed - use in-app settings

```

--------------------------------

### Upgrade Stirling PDF via Homebrew

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Upgrades an existing Stirling PDF installation managed by Homebrew Cask to the latest version.

```bash
brew upgrade --cask stirling-pdf
```

--------------------------------

### Configure Email Service

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Set up SMTP details for sending emails. Enable 'enableInvites' to allow sending invitation links to users.

```yaml
mail:
  enabled: true
  enableInvites: true
  host: smtp.example.com
  port: 587
  username: noreply@example.com
  password: ${MAIL_PASSWORD}
  from: noreply@example.com
  startTlsEnable: true
```

--------------------------------

### Handling Unknown Configuration Key

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Remove deprecated settings from settings.yml to resolve 'Unknown configuration key' warnings.

```text
WARN: Unknown configuration key: premium.proFeatures.googleDrive  
```

--------------------------------

### Add Stirling PDF Homebrew Tap

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Adds the Stirling PDF Homebrew repository to your system. This is a prerequisite for installing the application via Homebrew.

```bash
brew tap Stirling-Tools/stirling-pdf
```

--------------------------------

### Run Stirling PDF Backend

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Build and run the Spring Boot backend application using Gradle. The backend will be accessible at http://localhost:8080.

```bash
# Build and run the Spring Boot application  

./gradlew bootRun  
```

--------------------------------

### Updating Tool IDs for API Calls

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Update tool IDs in API calls if they return a 404 error, for example, changing 'pdf-organizer' to 'reorganize-pages'.

```text
pdf-organizer → reorganize-pages
```

--------------------------------

### Docker Compose for Static File Overrides

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Example Docker compose configuration to mount the `customFiles` directory, enabling static file overrides in V2.

```yaml
volumes:
  - ./customFiles:/customFiles:rw  
```

--------------------------------

### Create Stirling PDF Desktop Icon

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Creates a .desktop file in ~/.local/share/applications to add Stirling PDF to the system's application menu. It configures the application to open the web GUI and run the JAR in the background.

```bash
location=$(pwd)/gradlew &&
image=$(pwd)/docs/stirling.svg &&

cat > ~/.local/share/applications/Stirling-PDF.desktop <<EOF
[Desktop Entry]
Name=Stirling PDF;
GenericName=Launch StirlingPDF and open its WebGUI;
Category=Office;
Exec=xdg-open http://localhost:8080 && nohup $location java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar &
Icon=$image;
Keywords=pdf;
Type=Application;
NoDisplay=false;
Terminal=true;
EOF
```

--------------------------------

### Configure HTTPS with Environment Variables

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

Set up HTTPS by defining environment variables for server port and SSL configurations. This method is useful for containerized deployments.

```env
SERVER_PORT=8443
SERVER_SSL_ENABLED=true
SERVER_SSL_KEY-STORE=classpath:keystore.p12
SERVER_SSL_KEY-STORE-PASSWORD=your-keystore-password
SERVER_SSL_KEY-STORE-TYPE=PKCS12
SERVER_SSL_KEY-ALIAS=tomcat

```

--------------------------------

### Configure Docker Container

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Run a Docker container with environment variables for features, CORS, frontend URL, and JWT keystore.

```bash
-eDISABLE_ADDITIONAL_FEATURES=false \
-e SECURITY_ENABLELOGIN=true \
-e SYSTEM_CORSALLOWEDORIGINS=https://pdf.example.com \
-e SYSTEM_FRONTENDURL=https://pdf.example.com \
-e SECURITY_JWT_ENABLEKEYSTORE=true \

```

--------------------------------

### Enable Login via Environment Variable

Source: https://docs.stirlingpdf.com/Configuration

Use this environment variable to enable login functionality for admin users. This is suitable for Docker deployments and infrastructure-as-code setups.

```docker
docker run -d \
  -e SECURITY_ENABLELOGIN=true \
  -e SYSTEM_DEFAULTLOCALE=en-US \
  stirlingtools/stirling-pdf:latest  
```

--------------------------------

### V2 Settings After Removal (YAML)

Source: https://docs.stirlingpdf.com/Migration/Breaking-Changes

Illustrates the V2 settings.yml after removing the deprecated UI configuration keys. These settings are now managed through the in-app UI.

```yaml
ui:
  appNameNavbar: 'CompanyName PDF'
  # appName - REMOVE THIS LINE
  # homeDescription - REMOVE THIS LINE
```

--------------------------------

### Stirling PDF systemd Service Configuration

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

This is the content to be pasted into the Stirling PDF systemd service file. It defines the service's unit, service, and install configurations.

```ini
[Unit]

Description=Stirling-PDF service  

After=syslog.target network.target  

[Service]

SuccessExitStatus=143  

User=root  
Group=root  

Type=simple  

EnvironmentFile=/opt/Stirling-PDF/.env  
WorkingDirectory=/opt/Stirling-PDF  
ExecStart=/usr/bin/java -jar Stirling-PDF-*.jar  
ExecStop=/bin/kill -15 $MAINPID  

[Install]

WantedBy=multi-user.target  
```

--------------------------------

### Create Stirling PDF .env File

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Create a .env file to store environment variables for Stirling PDF. Variables should be added one per line.

```bash
touch /opt/Stirling-PDF/.env
```

--------------------------------

### Configure via Java Properties

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Run Stirling PDF with specific Java properties to enable login and disable additional features.

```bash
java -jar Stirling-PDF.jar -DDISABLE_ADDITIONAL_FEATURES=false -DSECURITY_ENABLELOGIN=true  
```

--------------------------------

### Configure Custom Host and Port (Environment Variables)

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Sets custom server host and port for Stirling PDF using environment variables, typically used when running as a service with systemd.

```bash
SERVER_HOST="0.0.0.0"
SERVER_PORT="3000"
```

--------------------------------

### Run Stirling PDF with Ultra-Lite Tag

Source: https://docs.stirlingpdf.com/Installation/Docker%20Install

Use this command to run the Ultra-Lite version of Stirling PDF, suitable for limited resources. Change the tag to select other versions like `latest` or `latest-fat`.

```bash
docker run -d stirlingtools/stirling-pdf:latest-ultra-lite
```

--------------------------------

### Configure HTTPS with Docker Compose

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

Integrate HTTPS configuration into your Docker Compose setup by defining environment variables for the Stirling PDF service. This ensures secure communication when running in Docker.

```yaml
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    environment:
      SERVER_PORT: 8443
      SERVER_SSL_ENABLED: true
      SERVER_SSL_KEY-STORE: classpath:keystore.p12
      SERVER_SSL_KEY-STORE-PASSWORD: your-keystore-password
      SERVER_SSL_KEY-STORE-TYPE: PKCS12
      SERVER_SSL_KEY-ALIAS: tomcat

```

--------------------------------

### Set UI Logo Style via Environment Variable

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Set the UI logo style using an environment variable.

```bash
UI_LOGOSTYLE=modern
```

--------------------------------

### Configure Server Settings

Source: https://docs.stirlingpdf.com/Configuration/Extra-Settings

Customize server behavior including the port, address binding, context path, session timeout, and Jetty-specific thread pool and connection settings.

```yaml
server:
  port: 8080
  address: 0.0.0.0
  servlet:
    context-path: /
    session:
      timeout: 30m
  jetty:
    threads:
      max: 200
      min: 10
    connection-idle-timeout: 30000
    max-http-request-header-size: 65536
```

--------------------------------

### Download and Prepare Stirling PDF JAR

Source: https://docs.stirlingpdf.com/Installation/Unix%20Installation

Downloads the Stirling-PDF.jar file and makes it executable. This JAR contains the core Stirling PDF application.

```bash
sudo wget https://files.stirlingpdf.com/Stirling-PDF.jar  
sudo chmod +x Stirling-PDF.jar  
```

--------------------------------

### Run Full Docker Test Suite

Source: https://docs.stirlingpdf.com/Installation/Development%20Setup

Execute the comprehensive Docker test suite, which covers all Stirling PDF variants.

```bash
# Full Docker test suite (tests all variants)  

./testing/test.sh  
```

--------------------------------

### Server Certificate Management Settings (V2)

Source: https://docs.stirlingpdf.com/Migration/Settings-Changes

Enables auto-generation of signing certificates for the 'Sign with Stirling PDF' feature. Works automatically with defaults.

```yaml
system:
  serverCertificate: # NEW in V2
    enabled: true
    organizationName: Stirling-PDF
    validity: 365 # days
    regenerateOnStartup: false

```

--------------------------------

### Configure Java Memory Options

Source: https://docs.stirlingpdf.com/Configuration

Set minimum and maximum Java heap sizes using the JAVA_TOOL_OPTIONS environment variable.

```env
JAVA_TOOL_OPTIONS="-Xms512m -Xmx4g"  # Min 512MB, Max 4GB RAM
```

--------------------------------

### Server Certificate Environment Variables

Source: https://docs.stirlingpdf.com/Configuration/System%20and%20Security

Configure server certificate generation using environment variables.

```bash
SYSTEM_SERVERCERTIFICATE_ENABLED=true
SYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"
SYSTEM_SERVERCERTIFICATE_VALIDITY=365
SYSTEM_SERVERCERTIFICATE_REGENERATEONSTARTUP=false
```

--------------------------------

### Linux Provisioning File Path

Source: https://docs.stirlingpdf.com/Installation/Managed%20Deployment

Specifies the system directory path for the Stirling PDF provisioning file on Linux.

```text
/etc/stirling-pdf/stirling-provisioning.json
```

--------------------------------

### Navigate to Download Directory

Source: https://docs.stirlingpdf.com/Installation/Mac%20Installation

Changes the current directory in the terminal to the Downloads folder. Adjust the path if you saved the JAR file elsewhere.

```bash
cd ~/Downloads  # Or wherever you saved the JAR  
```

--------------------------------

### V1 UI Settings (Removed)

Source: https://docs.stirlingpdf.com/Migration/Settings-Changes

These UI settings have been removed in V2 and are now configured in-app.

```yaml
ui:
  appName: '' # REMOVED
  homeDescription: '' # REMOVED
```

--------------------------------

### Minimal Security Configuration

Source: https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing

This configuration enables the server certificate and sets basic trust validation settings.

```yaml
system:
  serverCertificate:
    enabled: true

security:
  validation:
    trust:
      serverAsAnchor: true
      useSystemTrust: true
```
Tokens:
Raw