# Table of Contents - [Getting Started | Stirling PDF](#getting-started-stirling-pdf) - [Getting Started | Stirling PDF](#getting-started-stirling-pdf) - [PDF Tools | Stirling PDF](#pdf-tools-stirling-pdf) - [Migrating from V1 to V2 | Stirling PDF](#migrating-from-v1-to-v2-stirling-pdf) - [Paid Offerings | Stirling PDF](#paid-offerings-stirling-pdf) - [API | Stirling PDF](#api-stirling-pdf) - [Configuration Guide | Stirling PDF](#configuration-guide-stirling-pdf) - [Production Deployment Guide | Stirling PDF](#production-deployment-guide-stirling-pdf) - [Contribution guidelines | Stirling PDF](#contribution-guidelines-stirling-pdf) - [FAQ | Stirling PDF](#faq-stirling-pdf) - [Analytics and Telemetry | Stirling PDF](#analytics-and-telemetry-stirling-pdf) - [Custom Settings Configuration | Stirling PDF](#custom-settings-configuration-stirling-pdf) - [Login, System and Security | Stirling PDF](#login-system-and-security-stirling-pdf) - [Mac Installation Guide | Stirling PDF](#mac-installation-guide-stirling-pdf) - [Unix Installation Guide | Stirling PDF](#unix-installation-guide-stirling-pdf) - [Windows Guide | Stirling PDF](#windows-guide-stirling-pdf) - [Docker Guide | Stirling PDF](#docker-guide-stirling-pdf) - [Contribution guidelines | Stirling PDF](#contribution-guidelines-stirling-pdf) - [Functionality | Stirling PDF](#functionality-stirling-pdf) - [FAQ | Stirling PDF](#faq-stirling-pdf) - [Analytics and Telemetry | Stirling PDF](#analytics-and-telemetry-stirling-pdf) - [API | Stirling PDF](#api-stirling-pdf) - [Versions | Stirling PDF](#versions-stirling-pdf) - [Pro / Enterprise | Stirling PDF](#pro-enterprise-stirling-pdf) - [Convert | Stirling PDF](#convert-stirling-pdf) - [Page Operations | Stirling PDF](#page-operations-stirling-pdf) - [Recommended Tools | Stirling PDF](#recommended-tools-stirling-pdf) - [Features - Security | Stirling PDF](#features-security-stirling-pdf) - [Content & Editing | Stirling PDF](#content-editing-stirling-pdf) - [Compare PDFs | Stirling PDF](#compare-pdfs-stirling-pdf) - [Compress PDF | Stirling PDF](#compress-pdf-stirling-pdf) - [Features - Pipeline / Automate | Stirling PDF](#features-pipeline-automate-stirling-pdf) - [Advanced Tools | Stirling PDF](#advanced-tools-stirling-pdf) - [Multi-Tool Workbench | Stirling PDF](#multi-tool-workbench-stirling-pdf) - [OCR (Optical Character Recognition) | Stirling PDF](#ocr-optical-character-recognition-stirling-pdf) - [Read & Annotate PDFs | Stirling PDF](#read-annotate-pdfs-stirling-pdf) - [Mobile Scanner | Stirling PDF](#mobile-scanner-stirling-pdf) - [Third-Party Credits | Stirling PDF](#third-party-credits-stirling-pdf) - [Sign PDF (Handwritten Signatures) | Stirling PDF](#sign-pdf-handwritten-signatures-stirling-pdf) - [One doc tagged with "Paid" | Stirling PDF](#one-doc-tagged-with-paid-stirling-pdf) - [One doc tagged with "Pricing" | Stirling PDF](#one-doc-tagged-with-pricing-stirling-pdf) - [One doc tagged with "API" | Stirling PDF](#one-doc-tagged-with-api-stirling-pdf) - [6 docs tagged with "enterprise" | Stirling PDF](#6-docs-tagged-with-enterprise-stirling-pdf) - [4 docs tagged with "server" | Stirling PDF](#4-docs-tagged-with-server-stirling-pdf) - [Settings Changes from V1 to V2 | Stirling PDF](#settings-changes-from-v1-to-v2-stirling-pdf) - [Breaking Changes in V2 | Stirling PDF](#breaking-changes-in-v2-stirling-pdf) - [Path Structure | Stirling PDF](#path-structure-stirling-pdf) - [New Features in V2 | Stirling PDF](#new-features-in-v2-stirling-pdf) - [Certificate Signing | Stirling PDF](#certificate-signing-stirling-pdf) - [Manual Redaction | Stirling PDF](#manual-redaction-stirling-pdf) - [Kubernetes Guide | Stirling PDF](#kubernetes-guide-stirling-pdf) - [Pipeline Automation (Automate) | Stirling PDF](#pipeline-automation-automate-stirling-pdf) - [Mobile Scanner Configuration | Stirling PDF](#mobile-scanner-configuration-stirling-pdf) - [External Database | Stirling PDF](#external-database-stirling-pdf) - [OCR (Optical Character Recognition) | Stirling PDF](#ocr-optical-character-recognition-stirling-pdf) - [Endpoints Customisation | Stirling PDF](#endpoints-customisation-stirling-pdf) - [Folder Scanning | Stirling PDF](#folder-scanning-stirling-pdf) - [SSRF Protection | Stirling PDF](#ssrf-protection-stirling-pdf) - [Visual Sign with Custom File Storage | Stirling PDF](#visual-sign-with-custom-file-storage-stirling-pdf) - [Keyboard Shortcuts | Stirling PDF](#keyboard-shortcuts-stirling-pdf) - [Fail2Ban Integration | Stirling PDF](#fail2ban-integration-stirling-pdf) - [OAuth 2.0 Single Sign-On Configuration | Stirling PDF](#oauth-2-0-single-sign-on-configuration-stirling-pdf) - [Single Sign-On (SSO) Overview | Stirling PDF](#single-sign-on-sso-overview-stirling-pdf) - [Process Limits | Stirling PDF](#process-limits-stirling-pdf) - [Google Drive File Picker | Stirling PDF](#google-drive-file-picker-stirling-pdf) - [Other Customisations | Stirling PDF](#other-customisations-stirling-pdf) - [Usage Monitoring | Stirling PDF](#usage-monitoring-stirling-pdf) - [Database Backups | Stirling PDF](#database-backups-stirling-pdf) - [Audit Logging | Stirling PDF](#audit-logging-stirling-pdf) - [File Sharing and Storage | Stirling PDF](#file-sharing-and-storage-stirling-pdf) - [UI Customisation | Stirling PDF](#ui-customisation-stirling-pdf) - [SAML 2.0 Single Sign-On Configuration | Stirling PDF](#saml-2-0-single-sign-on-configuration-stirling-pdf) - [Other Customisations | Stirling PDF](#other-customisations-stirling-pdf) - [Windows Guide | Stirling PDF](#windows-guide-stirling-pdf) - [Mac Installation Guide | Stirling PDF](#mac-installation-guide-stirling-pdf) - [Docker Guide | Stirling PDF](#docker-guide-stirling-pdf) - [Unix Installation Guide | Stirling PDF](#unix-installation-guide-stirling-pdf) - [Development Setup Guide | Stirling PDF](#development-setup-guide-stirling-pdf) - [The Technologies Behind Stirling PDF | Stirling PDF](#the-technologies-behind-stirling-pdf-stirling-pdf) - [Features - Miscellaneous | Stirling PDF](#features-miscellaneous-stirling-pdf) - [Features - Convert | Stirling PDF](#features-convert-stirling-pdf) - [Page Operations | Stirling PDF](#page-operations-stirling-pdf) - [Features - Security | Stirling PDF](#features-security-stirling-pdf) - [Versions | Stirling PDF](#versions-stirling-pdf) - [One doc tagged with "API" | Stirling PDF](#one-doc-tagged-with-api-stirling-pdf) - [One doc tagged with "Premium" | Stirling PDF](#one-doc-tagged-with-premium-stirling-pdf) - [5 docs tagged with "pro" | Stirling PDF](#5-docs-tagged-with-pro-stirling-pdf) - [6 docs tagged with "enterprise" | Stirling PDF](#6-docs-tagged-with-enterprise-stirling-pdf) - [Features - Pipeline | Stirling PDF](#features-pipeline-stirling-pdf) - [Other Customisations | Stirling PDF](#other-customisations-stirling-pdf) - [How to add Configurations | Stirling PDF](#how-to-add-configurations-stirling-pdf) - [External Database | Stirling PDF](#external-database-stirling-pdf) - [Single Sign-On (SSO) Configuration | Stirling PDF](#single-sign-on-sso-configuration-stirling-pdf) - [UI Customisation | Stirling PDF](#ui-customisation-stirling-pdf) - [Shared Signing | Stirling PDF](#shared-signing-stirling-pdf) - [Manual Redaction | Stirling PDF](#manual-redaction-stirling-pdf) - [Path Structure | Stirling PDF](#path-structure-stirling-pdf) - [Tags | Stirling PDF](#tags-stirling-pdf) - [Kubernetes Guide | Stirling PDF](#kubernetes-guide-stirling-pdf) - [2 docs tagged with "database" | Stirling PDF](#2-docs-tagged-with-database-stirling-pdf) - [One doc tagged with "saml" | Stirling PDF](#one-doc-tagged-with-saml-stirling-pdf) - [7 docs tagged with "management" | Stirling PDF](#7-docs-tagged-with-management-stirling-pdf) - [One doc tagged with "customisation" | Stirling PDF](#one-doc-tagged-with-customisation-stirling-pdf) - [7 docs tagged with "feature" | Stirling PDF](#7-docs-tagged-with-feature-stirling-pdf) - [One doc tagged with "UI" | Stirling PDF](#one-doc-tagged-with-ui-stirling-pdf) - [7 docs tagged with "advanced feature" | Stirling PDF](#7-docs-tagged-with-advanced-feature-stirling-pdf) - [Enabling PDF to CBR Conversion in Stirling PDF | Stirling PDF](#enabling-pdf-to-cbr-conversion-in-stirling-pdf-stirling-pdf) - [Visual Sign with Custom File Storage | Stirling PDF](#visual-sign-with-custom-file-storage-stirling-pdf) - [Tags | Stirling PDF](#tags-stirling-pdf) - [Database Backups | Stirling PDF](#database-backups-stirling-pdf) - [Login, System and Security | Stirling PDF](#login-system-and-security-stirling-pdf) - [Google Drive File Picker | Stirling PDF](#google-drive-file-picker-stirling-pdf) - [Endpoints Customisation | Stirling PDF](#endpoints-customisation-stirling-pdf) - [4 docs tagged with "management" | Stirling PDF](#4-docs-tagged-with-management-stirling-pdf) - [Usage Monitoring | Stirling PDF](#usage-monitoring-stirling-pdf) - [4 docs tagged with "advanced feature" | Stirling PDF](#4-docs-tagged-with-advanced-feature-stirling-pdf) - [2 docs tagged with "database" | Stirling PDF](#2-docs-tagged-with-database-stirling-pdf) - [4 docs tagged with "feature" | Stirling PDF](#4-docs-tagged-with-feature-stirling-pdf) - [Pipeline Automation | Stirling PDF](#pipeline-automation-stirling-pdf) - [OCR (Optical Character Recognition) | Stirling PDF](#ocr-optical-character-recognition-stirling-pdf) - [Folder Scanning | Stirling PDF](#folder-scanning-stirling-pdf) - [One doc tagged with "UI" | Stirling PDF](#one-doc-tagged-with-ui-stirling-pdf) - [Custom Settings Configuration | Stirling PDF](#custom-settings-configuration-stirling-pdf) - [One doc tagged with "customisation" | Stirling PDF](#one-doc-tagged-with-customisation-stirling-pdf) - [Fail2Ban Integration | Stirling PDF](#fail2ban-integration-stirling-pdf) --- # Getting Started | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/#__docusaurus_skipToContent_fallback) On this page Benefits of Stirling PDF[​](https://docs.stirlingpdf.com/#benefits-of-stirling-pdf "Direct link to Benefits of Stirling PDF") ------------------------------------------------------------------------------------------------------------------------------ * **Extensive PDF Functionality:** Access 60+ tools, including signing, converting, merging, and more. * **Advanced Customization:** Deep customization, themes, and environment variables. * **Enterprise Features:** SSO, user management, and permission controls. * **Data Security:** Local file processing with automatic deletion post-task. * **Scalability & Automation:** Batch processing with Docker and Kubernetes support. * **API Integration:** Use APIs for automation and external integrations. * **Open-Source:** Community-driven with frequent updates and GitHub support. * **Multi-Language Support:** Available in 38+ languages with active translations. Welcome to Stirling PDF[​](https://docs.stirlingpdf.com/#welcome-to-stirling-pdf "Direct link to Welcome to Stirling PDF") --------------------------------------------------------------------------------------------------------------------------- Upgrading from V1? See the **[Migration Guide](https://docs.stirlingpdf.com/Migration/Overview) ** for what's new and how to upgrade smoothly. Stirling PDF is a locally hosted web application that allows you to perform various operations on PDF files. With 60+ tools, flexible deployment options, and enterprise features, it's the comprehensive PDF solution for individuals and organizations. * * * What's New in V2[​](https://docs.stirlingpdf.com/#whats-new-in-v2 "Direct link to What's New in V2") ----------------------------------------------------------------------------------------------------- V2 brings major improvements to performance, workflow, and deployment flexibility: * **Stateful Processing** - Upload once, use across multiple tools without re-uploading * **Undo & Redo** - Full version history for page editing * **Native Desktop Apps** - Fast startup, "Open with" integration, offline capable * **In-App Settings** - Configure everything through the UI, no file editing needed * * * Documentation Guide[​](https://docs.stirlingpdf.com/#documentation-guide "Direct link to Documentation Guide") --------------------------------------------------------------------------------------------------------------- ### For Individual Users[​](https://docs.stirlingpdf.com/#for-individual-users "Direct link to For Individual Users") **[Tool Reference](https://docs.stirlingpdf.com/functionality) ** Browse all 60+ PDF tools with descriptions * * * ### For Organizations & IT Teams[​](https://docs.stirlingpdf.com/#for-organizations--it-teams "Direct link to For Organizations & IT Teams") **[Production Deployment Guide](https://docs.stirlingpdf.com/Production-Deployment-Guide) ** Complete walkthrough: installation - configuration - security - monitoring **[Paid Offerings (Server & Enterprise)](https://docs.stirlingpdf.com/Paid-Offerings) ** External databases, Google Drive integration, SSO, advanced monitoring, and priority support **[Configuration Options](https://docs.stirlingpdf.com/Configuration/Extra-Settings) ** All configuration options for Docker and server deployments * * * ### For Developers & Integration[​](https://docs.stirlingpdf.com/#for-developers--integration "Direct link to For Developers & Integration") **[API Documentation](https://docs.stirlingpdf.com/API) ** Integrate Stirling PDF into your applications and workflows **[Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) ** SSO, certificates, security settings, and more **[Contribute Guide](https://docs.stirlingpdf.com/Contribute) ** Help improve Stirling PDF - development setup and guidelines * * * Installation[​](https://docs.stirlingpdf.com/#installation "Direct link to Installation") ------------------------------------------------------------------------------------------ Choose how you want to run Stirling PDF based on your needs: ### Desktop Applications[​](https://docs.stirlingpdf.com/#desktop-applications "Direct link to Desktop Applications") Native apps with system integration: | Platform | Download | Guide | | --- | --- | --- | | **Windows** | [Installer](https://files.stirlingpdf.com/win-installer.exe) | [Windows Guide](https://docs.stirlingpdf.com/Installation/Windows%20Installation) | | **Mac (Apple Silicon)** | [DMG](https://files.stirlingpdf.com/mac-installer.dmg) | [Mac Guide](https://docs.stirlingpdf.com/Installation/Mac%20Installation) | | **Mac (Intel)** | [DMG](https://files.stirlingpdf.com/mac-x86_64-installer.dmg) | [Mac Guide](https://docs.stirlingpdf.com/Installation/Mac%20Installation) | | **Linux** | [DEB](https://files.stirlingpdf.com/linux-installer.deb) | [Unix Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) | **Features:** Fast startup, "Open with" integration, no login required, optional server connection for advanced tools * * * ### Docker Deployment[​](https://docs.stirlingpdf.com/#docker-deployment "Direct link to Docker Deployment") Recommended for server deployments and organizations: **Quick Start:** docker run -d \ -p 8080:8080 \ -v ./stirling-data:/configs \ stirlingtools/stirling-pdf:latest **Available versions:** * `latest` - Standard version (recommended) * `latest-fat` - Extra fonts and tools for highest quality conversions and full format support * `latest-ultra-lite` - Minimal size for resource-constrained environments **Full guide:** [Docker Installation Guide](https://docs.stirlingpdf.com/Installation/Docker%20Install) * * * ### Manual Server Setup[​](https://docs.stirlingpdf.com/#manual-server-setup "Direct link to Manual Server Setup") For bare metal installations or environments without Docker: 1. Download `Stirling-PDF.jar` 2. Install Java 21+ 3. Install dependencies (LibreOffice, Tesseract for OCR) 4. Run the JAR file **Full guide:** [Unix Installation Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) * * * Quick Links[​](https://docs.stirlingpdf.com/#quick-links "Direct link to Quick Links") --------------------------------------------------------------------------------------- * **Questions?** Check our **[FAQ](https://docs.stirlingpdf.com/FAQ) ** * **Issues?** Report on **[GitHub](https://github.com/Stirling-Tools/Stirling-PDF/issues) ** * **Community?** Join our **[Discord](https://discord.gg/Cn8pWhQRxZ) ** * [Benefits of Stirling PDF](https://docs.stirlingpdf.com/#benefits-of-stirling-pdf) * [Welcome to Stirling PDF](https://docs.stirlingpdf.com/#welcome-to-stirling-pdf) * [What's New in V2](https://docs.stirlingpdf.com/#whats-new-in-v2) * [Documentation Guide](https://docs.stirlingpdf.com/#documentation-guide) * [For Individual Users](https://docs.stirlingpdf.com/#for-individual-users) * [For Organizations & IT Teams](https://docs.stirlingpdf.com/#for-organizations--it-teams) * [For Developers & Integration](https://docs.stirlingpdf.com/#for-developers--integration) * [Installation](https://docs.stirlingpdf.com/#installation) * [Desktop Applications](https://docs.stirlingpdf.com/#desktop-applications) * [Docker Deployment](https://docs.stirlingpdf.com/#docker-deployment) * [Manual Server Setup](https://docs.stirlingpdf.com/#manual-server-setup) * [Quick Links](https://docs.stirlingpdf.com/#quick-links) --- # Getting Started | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Benefits of Stirling-PDF[​](https://docs.stirlingpdf.com/1.5/#benefits-of-stirling-pdf "Direct link to Benefits of Stirling-PDF") ---------------------------------------------------------------------------------------------------------------------------------- * **Extensive PDF Functionality:** Access 50+ tools, including signing, converting, merging, and more. * **Advanced Customization:** Deep customization, themes, and environment variables. * **Enterprise Features:** SSO, user management, and permission controls. * **Data Security:** Local file processing with automatic deletion post-task. * **Scalability & Automation:** Batch processing with Docker and Kubernetes support. * **API Integration:** Use APIs for automation and external integrations. * **Open-Source:** Community-driven with frequent updates and GitHub support. * **Multi-Language Support:** Available in 38+ languages with active translations. Please feel free to request new features or report bugs through our [GitHub](https://github.com/Stirling-Tools/Stirling-PDF/issues) or [Discord](https://discord.gg/Cn8pWhQRxZ) . Introduction[​](https://docs.stirlingpdf.com/1.5/#introduction "Direct link to Introduction") ---------------------------------------------------------------------------------------------- This guide will help you choose the right installation method based on your needs. We prioritise and focus on our Server deployment options however we also offer a [Ultra-Lite model](https://docs.stirlingpdf.com/Installation/Versions) for desktop users Choose Your Installation Type[​](https://docs.stirlingpdf.com/1.5/#choose-your-installation-type "Direct link to Choose Your Installation Type") ------------------------------------------------------------------------------------------------------------------------------------------------- ### For Desktop Users[​](https://docs.stirlingpdf.com/1.5/#for-desktop-users "Direct link to For Desktop Users") If you want to run Stirling PDF on your personal computer: 1. **Windows Users** * Download our installer ([Stirling-PDF-windows-x86\_64.msi](https://files.stirlingpdf.com/win-installer.exe) ) for a simple, standalone experience * Refer to our [Windows Installation Guide](https://docs.stirlingpdf.com/Installation/Windows%20Installation) for detailed setup instructions 2. **Linux/Unix Users** * Dedicated Linux installer to be released soon, Currently you must run Stirling-PDF as a java jar * Follow our comprehensive [Unix Installation Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) for a native installation 3. **Mac Users** * Download our installer ([Apple Silicon](https://files.stirlingpdf.com/mac-installer.dmg) /[Intel](https://files.stirlingpdf.com/mac-x86_64-installer.dmg) ) for a simple, standalone experience * Follow our comprehensive [Mac Installation Guide](https://docs.stirlingpdf.com/Installation/Mac%20Installation) for a native installation ### For Server Deployments[​](https://docs.stirlingpdf.com/1.5/#for-server-deployments "Direct link to For Server Deployments") If you're looking to host Stirling PDF as a service: 1. **Docker Users** * We recommend using our Docker images for the easiest deployment * Check our [Docker Installation Guide](https://docs.stirlingpdf.com/Installation/Docker%20Install) for setup instructions * Choose from three versions: * Fat (latest-fat): Includes additional fonts and security features * Standard (latest): Balanced features and size * Ultra-Lite (latest-ultra-lite): Minimal size with core features 2. **Manual Server Setup** * For bare metal server installations * Use Stirling-PDF.jar package * Follow our [Unix Installation Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) for setup steps Quick Reference Table[​](https://docs.stirlingpdf.com/1.5/#quick-reference-table "Direct link to Quick Reference Table") ------------------------------------------------------------------------------------------------------------------------- | Installation Type | Best For | Documentation Link | | --- | --- | --- | | Stirling-PDF-windows-x86\_64.msi | Windows desktop users | [Windows Guide](https://docs.stirlingpdf.com/Installation/Windows%20Installation) | | Stirling-PDF.jar | Server deployments without Docker | [Unix Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) | | Docker Images | Server deployments with Docker | [Docker Guide](https://docs.stirlingpdf.com/Installation/Docker%20Install) | Choose the installation method that best suits your needs and environment. Each guide provides detailed instructions for getting Stirling PDF up and running on your system. * [Benefits of Stirling-PDF](https://docs.stirlingpdf.com/1.5/#benefits-of-stirling-pdf) * [Introduction](https://docs.stirlingpdf.com/1.5/#introduction) * [Choose Your Installation Type](https://docs.stirlingpdf.com/1.5/#choose-your-installation-type) * [For Desktop Users](https://docs.stirlingpdf.com/1.5/#for-desktop-users) * [For Server Deployments](https://docs.stirlingpdf.com/1.5/#for-server-deployments) * [Quick Reference Table](https://docs.stirlingpdf.com/1.5/#quick-reference-table) --- # PDF Tools | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/functionality#__docusaurus_skipToContent_fallback) On this page All tools organized by category. * * * Most Popular[​](https://docs.stirlingpdf.com/functionality#most-popular "Direct link to Most Popular") ------------------------------------------------------------------------------------------------------- * **[Multi-Tool](https://docs.stirlingpdf.com/Functionality/Multi-Tool) ** - Upload once, chain operations * **[Read & Annotate](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate) ** - PDF viewer with annotations * **Merge** - Combine multiple PDFs * **[Convert](https://docs.stirlingpdf.com/Functionality/Convert/) ** - 50+ format conversions * **[Compress](https://docs.stirlingpdf.com/Functionality/Compress) ** - Reduce file size * **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** - Make scanned PDFs searchable * **[Compare](https://docs.stirlingpdf.com/Functionality/Compare) ** - See differences between PDFs * **Redact** - Remove sensitive content * * * [Security](https://docs.stirlingpdf.com/Functionality/Security/) [​](https://docs.stirlingpdf.com/functionality#security "Direct link to security") ---------------------------------------------------------------------------------------------------------------------------------------------------- * Add/Remove Password * Change Permissions * **[Sign](https://docs.stirlingpdf.com/Functionality/Security/Sign) ** - Handwritten signatures * **[Certificate Sign](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ** - Digital signatures * Validate Signature * Add Watermark * Sanitize PDF * Auto-Redact * * * [Page Operations](https://docs.stirlingpdf.com/Functionality/Page-Operations/) [​](https://docs.stirlingpdf.com/functionality#page-operations "Direct link to page-operations") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Split PDF * Merge PDFs * Rotate Pages * Extract Pages * Reorganize Pages * Add Page Numbers * Remove Pages/Blank Pages **Detailed Guide:** [Redaction](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact) * * * [Convert](https://docs.stirlingpdf.com/Functionality/Convert/) [​](https://docs.stirlingpdf.com/functionality#convert "Direct link to convert") ------------------------------------------------------------------------------------------------------------------------------------------------ **To PDF:** Word, Excel, PowerPoint, Images, HTML, Markdown, Email, and more **From PDF:** Word, PowerPoint, Text, Images, CSV, HTML, XML, PDF/A, and more * * * [Content & Editing](https://docs.stirlingpdf.com/Functionality/Content-Editing/) [​](https://docs.stirlingpdf.com/functionality#content--editing "Direct link to content--editing") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * Add/Extract Images * Add Stamp * Edit Metadata * Remove Annotations * Replace Colors * Get PDF Info * * * [Advanced Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools) [​](https://docs.stirlingpdf.com/functionality#advanced-tools "Direct link to advanced-tools") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Overlay PDFs * Booklet Imposition * Multi-Page Layout * Scale Pages * Auto Rename * Show JavaScript * Scanner Effect * * * Quick Tool Finder[​](https://docs.stirlingpdf.com/functionality#quick-tool-finder "Direct link to Quick Tool Finder") ---------------------------------------------------------------------------------------------------------------------- **I want to...** * Reduce file size → **[Compress](https://docs.stirlingpdf.com/Functionality/Compress) ** * Make searchable → **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** * Combine files → **Merge** * Split into parts → **Split** * Convert format → **[Convert](https://docs.stirlingpdf.com/Functionality/Convert/) ** * Add signature → **[Sign](https://docs.stirlingpdf.com/Functionality/Security/Sign) ** or **[Certificate Sign](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ** * Remove content → **Redact** or **Sanitize** * Edit pages → **Reorganize Pages** or **[Multi-Tool](https://docs.stirlingpdf.com/Functionality/Multi-Tool) ** * Automate workflow → **[Automate](https://docs.stirlingpdf.com/Configuration/Pipeline) ** * [Most Popular](https://docs.stirlingpdf.com/functionality#most-popular) * [Security](https://docs.stirlingpdf.com/functionality#security) * [Page Operations](https://docs.stirlingpdf.com/functionality#page-operations) * [Convert](https://docs.stirlingpdf.com/functionality#convert) * [Content & Editing](https://docs.stirlingpdf.com/functionality#content--editing) * [Advanced Tools](https://docs.stirlingpdf.com/functionality#advanced-tools) * [Quick Tool Finder](https://docs.stirlingpdf.com/functionality#quick-tool-finder) --- # Migrating from V1 to V2 | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Migration/Overview#__docusaurus_skipToContent_fallback) On this page Upgrading to Stirling PDF V2 is straightforward for most users. This guide will walk you through the upgrade process. Backup Your Configuration Before upgrading, **back up your configuration folder** (usually mounted as `/configs`) to ensure you can restore your settings if needed: # Docker volume backupdocker cp stirling-pdf:/configs ./configs-backup# Or if using bind mountcp -r ./configs ./configs-backup * * * Quick Upgrade Guide[​](https://docs.stirlingpdf.com/Migration/Overview#quick-upgrade-guide "Direct link to Quick Upgrade Guide") --------------------------------------------------------------------------------------------------------------------------------- ### Docker Users (Most Common)[​](https://docs.stirlingpdf.com/Migration/Overview#docker-users-most-common "Direct link to Docker Users (Most Common)") Update your image tag to `latest` (or specific V2 version): services: stirling-pdf: image: stirlingtools/stirling-pdf:latest # Change from 1.x to latest # Keep all your existing environment variables and volumes Then pull and restart. See the [Docker Installation Guide - Updating Section](https://docs.stirlingpdf.com/Installation/Docker%20Install#updating-stirling-pdf) for complete update commands. **That's it!** Your data and settings migrate automatically. * * * ### Desktop Application Users[​](https://docs.stirlingpdf.com/Migration/Overview#desktop-application-users "Direct link to Desktop Application Users") 1. **Windows**: Download new installer from [GitHub Releases](https://github.com/Stirling-Tools/Stirling-PDF/releases) , run it (automatically updates) 2. **Mac**: Download new DMG, drag to Applications (replaces old version) 3. **Linux**: Install new `.deb`/`.rpm`/`.AppImage` Your settings carry over automatically. * * * ### Manual Installation (JAR)[​](https://docs.stirlingpdf.com/Migration/Overview#manual-installation-jar "Direct link to Manual Installation (JAR)") 1. Download the latest V2 release from [GitHub Releases](https://github.com/Stirling-Tools/Stirling-PDF/releases) 2. Stop the current V1 instance 3. Replace the JAR file 4. Start with the same command * * * Migration Guide Sections[​](https://docs.stirlingpdf.com/Migration/Overview#migration-guide-sections "Direct link to Migration Guide Sections") ------------------------------------------------------------------------------------------------------------------------------------------------ This migration guide is organized into detailed sections: ### 📋 [Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) [​](https://docs.stirlingpdf.com/Migration/Overview#-settings-changes "Direct link to -settings-changes") **Start here** if you have custom configuration. Covers: * New settings added in V2 * Deprecated settings to remove * Settings that were renamed * Configuration examples and migration checklist ### ⚠️ [Breaking Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes) [​](https://docs.stirlingpdf.com/Migration/Overview#%EF%B8%8F-breaking-changes "Direct link to ️-breaking-changes") **Important** - Review if you have customizations. Covers: * Template customization system changes (most impactful) * UI settings moved to in-app configuration * Session management improvements * Database notification changes * API compatibility notes ### ✨ [New Features](https://docs.stirlingpdf.com/Migration/New-Features) [​](https://docs.stirlingpdf.com/Migration/Overview#-new-features "Direct link to -new-features") **Explore what's new** - Comprehensive list of V2 features: * Browser file storage * Undo/redo functionality * Desktop applications * Multi-Tool workbench * PDF signature validation * In-app settings management * And much more... * * * Should You Upgrade?[​](https://docs.stirlingpdf.com/Migration/Overview#should-you-upgrade "Direct link to Should You Upgrade?") -------------------------------------------------------------------------------------------------------------------------------- **Yes, if you want:** * ✅ Faster workflows with file persistence * ✅ Undo/redo functionality * ✅ Better performance with large files * ✅ Desktop applications * ✅ Modern, responsive interface * ✅ Future features and updates **Consider staying on V1 if:** * ⚠️ You heavily customized UI using Thymeleaf templates in `customFiles/templates/` (requires rewriting for React in V2) * **Note:** Static file overrides via `customFiles/static/` still work in V2 - only Thymeleaf templates don't work * ⚠️ You have specific compatibility requirements with very old browsers * * * What Stays the Same[​](https://docs.stirlingpdf.com/Migration/Overview#what-stays-the-same "Direct link to What Stays the Same") --------------------------------------------------------------------------------------------------------------------------------- * ✅ All existing PDF tools * ✅ Backend API compatibility * ✅ Configuration files (settings.yml) * ✅ Docker deployment process * ✅ Security features (SSO, user management) * ✅ Pipeline automation (renamed "Automate" in UI) * ✅ Privacy commitment * * * Your Data is Safe[​](https://docs.stirlingpdf.com/Migration/Overview#your-data-is-safe "Direct link to Your Data is Safe") --------------------------------------------------------------------------------------------------------------------------- V2 is **fully compatible** with V1 data: * ✅ User accounts and permissions * ✅ API keys * ✅ Settings and configurations * ✅ Database (internal or external) * ✅ Custom OCR language files * ✅ Custom fonts and certificates **No manual migration needed** - database schema updates automatically on first startup. * * * Post-Upgrade Checklist[​](https://docs.stirlingpdf.com/Migration/Overview#post-upgrade-checklist "Direct link to Post-Upgrade Checklist") ------------------------------------------------------------------------------------------------------------------------------------------ After upgrading, verify everything works: * [ ] Can log in with existing credentials * [ ] All PDF tools work as expected * [ ] Settings and preferences retained * [ ] API integrations still function (if applicable) * [ ] Custom branding appears correctly * [ ] OCR languages available * [ ] Pipelines continue working (now called "Automate" in UI) * * * Troubleshooting[​](https://docs.stirlingpdf.com/Migration/Overview#troubleshooting "Direct link to Troubleshooting") --------------------------------------------------------------------------------------------------------------------- ### Common Issues[​](https://docs.stirlingpdf.com/Migration/Overview#common-issues "Direct link to Common Issues") **"Unknown configuration key" warnings** * **Cause:** Old V1 settings in your `settings.yml` * **Solution:** See [Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) to remove deprecated settings **Users logged out after upgrade** * **Cause:** JWT token format changed (normal) * **Solution:** Users just need to log in once **Custom templates not loading** * **Cause:** Thymeleaf template system no longer used (V2 uses React) * **Solution:** Use static file overrides instead via `customFiles/static/` - See [Breaking Changes - UI Customization](https://docs.stirlingpdf.com/Migration/Breaking-Changes#-ui-customization-architecture-changed) **App name not showing** * **Cause:** Setting moved to in-app configuration * **Solution:** Log in as admin → Settings → UI * * * Rolling Back (If Needed)[​](https://docs.stirlingpdf.com/Migration/Overview#rolling-back-if-needed "Direct link to Rolling Back (If Needed)") ---------------------------------------------------------------------------------------------------------------------------------------------- If you need to return to V1: # Restore config backupcp -r ./configs-backup ./configs# Pull V1 imagedocker pull stirlingtools/stirling-pdf:1.5.0# Update docker-compose.yml to use 1.5.0 tagdocker-compose up -d **Note:** Your data will work if you roll back (database is backward compatible). * * * Getting Help[​](https://docs.stirlingpdf.com/Migration/Overview#getting-help "Direct link to Getting Help") ------------------------------------------------------------------------------------------------------------ If you encounter issues: 1. **[Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) ** - Update your configuration 2. **[Breaking Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes) ** - Review important changes 3. **[New Features](https://docs.stirlingpdf.com/Migration/New-Features) ** - Learn what's new 4. **[FAQ](https://docs.stirlingpdf.com/FAQ) ** - Common questions answered 5. **[GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) ** - Report problems 6. **[Discord](https://discord.gg/Cn8pWhQRxZ) ** - Community support * * * Summary[​](https://docs.stirlingpdf.com/Migration/Overview#summary "Direct link to Summary") --------------------------------------------------------------------------------------------- **Upgrading is easy:** 1. Back up your `/configs` folder 2. Pull latest Docker image (or download desktop app) 3. Start with existing configuration 4. Review [Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) for any needed updates 5. Check [Breaking Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes) if you have customizations **Welcome to V2!** Enjoy the faster, more modern Stirling PDF experience. * [Quick Upgrade Guide](https://docs.stirlingpdf.com/Migration/Overview#quick-upgrade-guide) * [Docker Users (Most Common)](https://docs.stirlingpdf.com/Migration/Overview#docker-users-most-common) * [Desktop Application Users](https://docs.stirlingpdf.com/Migration/Overview#desktop-application-users) * [Manual Installation (JAR)](https://docs.stirlingpdf.com/Migration/Overview#manual-installation-jar) * [Migration Guide Sections](https://docs.stirlingpdf.com/Migration/Overview#migration-guide-sections) * [📋 Settings Changes](https://docs.stirlingpdf.com/Migration/Overview#-settings-changes) * [⚠️ Breaking Changes](https://docs.stirlingpdf.com/Migration/Overview#%EF%B8%8F-breaking-changes) * [✨ New Features](https://docs.stirlingpdf.com/Migration/Overview#-new-features) * [Should You Upgrade?](https://docs.stirlingpdf.com/Migration/Overview#should-you-upgrade) * [What Stays the Same](https://docs.stirlingpdf.com/Migration/Overview#what-stays-the-same) * [Your Data is Safe](https://docs.stirlingpdf.com/Migration/Overview#your-data-is-safe) * [Post-Upgrade Checklist](https://docs.stirlingpdf.com/Migration/Overview#post-upgrade-checklist) * [Troubleshooting](https://docs.stirlingpdf.com/Migration/Overview#troubleshooting) * [Common Issues](https://docs.stirlingpdf.com/Migration/Overview#common-issues) * [Rolling Back (If Needed)](https://docs.stirlingpdf.com/Migration/Overview#rolling-back-if-needed) * [Getting Help](https://docs.stirlingpdf.com/Migration/Overview#getting-help) * [Summary](https://docs.stirlingpdf.com/Migration/Overview#summary) --- # Paid Offerings | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Paid-Offerings#__docusaurus_skipToContent_fallback) On this page Stirling PDF offers Server and Enterprise paid plans. These provide the same great software with added features, streamlined license management, and support options. Available Plans[​](https://docs.stirlingpdf.com/Paid-Offerings#available-plans "Direct link to Available Plans") ----------------------------------------------------------------------------------------------------------------- ### Free Plan[​](https://docs.stirlingpdf.com/Paid-Offerings#free-plan "Direct link to Free Plan") * **Cost**: Free forever * **Users**: Up to 5 users * **Features**: * Self-hosted deployment * All PDF operations * Community support * Regular updates * **Perfect for**: Personal use, small teams, or evaluation ### Server Plan[​](https://docs.stirlingpdf.com/Paid-Offerings#server-plan "Direct link to Server Plan") * **Cost**: $99/month or $999/year (save $189 with annual billing) * **Available billing**: Monthly or Yearly * **Users**: Unlimited users (flat rate regardless of user count) * **Value**: The more users you have, the better the value (e.g., 100 users = $1/user/month) * **Features**: * Self-hosted deployment * All PDF operations * Unlimited users - no per-seat charges * Community support * Regular updates * Support tickets via [support@stirlingpdf.com](mailto:support@stirlingpdf.com) * [External Database](https://docs.stirlingpdf.com/Configuration/External%20Database) support for optimized deployments and load-balancing * Google Drive integration * [OAuth2 SSO](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) (Google, GitHub, Keycloak, any OIDC provider) * **Perfect for**: Organizations with many users who want predictable, flat-rate pricing ### Enterprise Plan[​](https://docs.stirlingpdf.com/Paid-Offerings#enterprise-plan "Direct link to Enterprise Plan") * **Cost**: Base server price + per-seat licensing (check [stirling.com/pricing](https://stirling.com/pricing) ) * **Available billing**: Monthly or Yearly (save with annual billing) * **Users**: Per-seat licensing (flexible scaling) * **Features**: * All Server Plan features, plus: * [SAML2 SSO](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) (Okta, Azure AD, etc.) with automated login handling * Custom automated metadata handling * Priority support tickets via [support@stirlingpdf.com](mailto:support@stirlingpdf.com) * 1:1 meetings with the Stirling PDF team (from registered email domain) * Priority feature enhancements * Prometheus endpoint for advanced usage monitoring * Usage Monitoring UI * Audit logs * SLA guarantee * Custom integrations support * Dedicated account manager * **Perfect for**: Large enterprises requiring priority support, SLA guarantees, and per-seat licensing Purchasing a License[​](https://docs.stirlingpdf.com/Paid-Offerings#purchasing-a-license "Direct link to Purchasing a License") -------------------------------------------------------------------------------------------------------------------------------- ### In-App Purchase (Recommended)[​](https://docs.stirlingpdf.com/Paid-Offerings#in-app-purchase-recommended "Direct link to In-App Purchase (Recommended)") Stirling PDF offers streamlined in-app purchasing and license activation: 1. **Navigate to Settings**: Log in as an admin and go to Settings → Admin Plan 2. **Select Your Plan**: Choose between Server (unlimited users) or Enterprise (per-seat) plans 3. **Choose Billing Period**: Select monthly or yearly billing (yearly saves money) 4. **Complete Checkout**: You'll be redirected to Stripe's secure checkout 5. **Automatic Activation**: After payment, your license key is automatically retrieved and activated 6. **Confirmation**: You'll see your active plan status immediately in the Settings **Benefits of In-App Purchase:** * No manual license key entry required * Instant activation after payment * Manage billing directly from the app * Automatic license key synchronization * Easy plan upgrades ### Alternative - Contact Us[​](https://docs.stirlingpdf.com/Paid-Offerings#alternative---contact-us "Direct link to Alternative - Contact Us") If you prefer to purchase outside the app or have questions: 1. Visit [stirling.com/contact](https://stirling.com/contact) or email [support@stirlingpdf.com](mailto:support@stirlingpdf.com) 2. Our team will assist you with your purchase 3. You'll receive your license key via email 4. Follow manual activation steps below Activating Your License[​](https://docs.stirlingpdf.com/Paid-Offerings#activating-your-license "Direct link to Activating Your License") ----------------------------------------------------------------------------------------------------------------------------------------- ### Automatic Activation[​](https://docs.stirlingpdf.com/Paid-Offerings#automatic-activation "Direct link to Automatic Activation") If you purchased in-app, your license is automatically activated. No further action needed! ### Manual Activation[​](https://docs.stirlingpdf.com/Paid-Offerings#manual-activation "Direct link to Manual Activation") If you purchased via the website and received a license key by email: 1. **Admin Settings**: Log in as an admin and navigate to Settings → Admin Plan 2. **Enter License Key**: Paste your license key in the provided field 3. **Activate**: Click "Activate License" 4. **Confirmation**: Your plan features will be enabled immediately **No restart required** - license activation is dynamic! ### Legacy - settings.yml Activation[​](https://docs.stirlingpdf.com/Paid-Offerings#legacy---settingsyml-activation "Direct link to Legacy - settings.yml Activation") For advanced users or air-gapped environments, you can still activate via `settings.yml`: 1. Navigate to the Stirling PDF config folder 2. Open `settings.yml` 3. Find the premium section: premium: key: 00000000-0000-0000-0000-000000000000 enabled: false # Enable license key checks for pro/enterprise features 4. Replace the key with your license key 5. Change `enabled` from `false` to `true` 6. Restart Stirling PDF For 100% offline air-gapped environments (Enterprise only), you can request a certificate file: 1. Contact support to receive your `.crt` or `.lic` certificate file 2. Place the certificate in your config folder (e.g., `configs/cert.crt`) 3. Use the `file:` prefix to specify the certificate path: premium: key: file:configs/cert.crt enabled: true Managing Your Subscription[​](https://docs.stirlingpdf.com/Paid-Offerings#managing-your-subscription "Direct link to Managing Your Subscription") -------------------------------------------------------------------------------------------------------------------------------------------------- ### Billing Portal[​](https://docs.stirlingpdf.com/Paid-Offerings#billing-portal "Direct link to Billing Portal") Stirling PDF includes a convenient billing management interface: 1. Navigate to Settings → Admin Plan 2. Click "Manage Billing" 3. You'll be redirected to Stripe's customer portal where you can: * Update payment methods * View invoices * Cancel or modify subscriptions * Update billing information Feature Configuration[​](https://docs.stirlingpdf.com/Paid-Offerings#feature-configuration "Direct link to Feature Configuration") ----------------------------------------------------------------------------------------------------------------------------------- Once activated, you can customize premium features in your `settings.yml`: premium: proFeatures: SSOAutoLogin: false CustomMetadata: autoUpdateMetadata: false author: username creator: Stirling-PDF producer: Stirling-PDF googleDrive: enabled: false clientId: '' apiKey: '' appId: '' License Model[​](https://docs.stirlingpdf.com/Paid-Offerings#license-model "Direct link to License Model") ----------------------------------------------------------------------------------------------------------- Stirling PDF uses an **installation-based licensing model**: * Each license is tied to a specific installation (identified by machine fingerprint) * **Server Plan**: Flat-rate pricing with unlimited users for one installation * $99/month = unlimited users (great value for larger teams) * Example: 100 users = only $1 per user per month * Example: 500 users = only $0.20 per user per month * **Enterprise Plan**: Base installation license + per-seat user licensing * **Named User Model**: For Enterprise, seats represent unique users who can log in * Example: A company with 10 employees who use Stirling PDF needs 10 seats Upgrading Your Plan[​](https://docs.stirlingpdf.com/Paid-Offerings#upgrading-your-plan "Direct link to Upgrading Your Plan") ----------------------------------------------------------------------------------------------------------------------------- You can upgrade from Free → Server or Server → Enterprise at any time: 1. Navigate to Settings → Admin Plan 2. Click "Upgrade Plan" 3. Select your new plan tier 4. Complete checkout 5. Your existing license will be automatically upgraded **Note**: When upgrading, your new plan starts immediately and you'll be credited for any unused time on your previous plan. Support[​](https://docs.stirlingpdf.com/Paid-Offerings#support "Direct link to Support") ----------------------------------------------------------------------------------------- ### Community Support (All Plans)[​](https://docs.stirlingpdf.com/Paid-Offerings#community-support-all-plans "Direct link to Community Support (All Plans)") * GitHub Issues: [github.com/Stirling-Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF) * Discord: Join our community server ### Email Support (Server & Enterprise)[​](https://docs.stirlingpdf.com/Paid-Offerings#email-support-server--enterprise "Direct link to Email Support (Server & Enterprise)") * Email: [support@stirlingpdf.com](mailto:support@stirlingpdf.com) * Response time: 1-2 business days (Server), Priority response (Enterprise) ### Enterprise Support[​](https://docs.stirlingpdf.com/Paid-Offerings#enterprise-support "Direct link to Enterprise Support") * Priority email support * 1:1 meetings with Stirling PDF team * Dedicated account manager * SLA guarantees Frequently Asked Questions[​](https://docs.stirlingpdf.com/Paid-Offerings#frequently-asked-questions "Direct link to Frequently Asked Questions") -------------------------------------------------------------------------------------------------------------------------------------------------- **Q: Can I try before I buy?** A: Yes! The Free plan includes all features for up to 5 users. Test thoroughly before upgrading. **Q: What happens if I cancel?** A: Your license remains active until the end of your billing period, then reverts to Free plan limits. **Q: Can I move my license to a different server?** A: Contact [support@stirlingpdf.com](mailto:support@stirlingpdf.com) for license transfers. Enterprise customers have more flexibility. **Q: Do I need an internet connection?** A: License activation requires internet for initial verification. Enterprise customers can request offline certificate files. **Q: What's the difference between monthly and yearly billing?** A: Yearly billing offers significant savings. For Server plan: $999/year vs $1,188/year monthly (save $189 = almost 2 months free). **Q: How do I get an invoice?** A: Invoices are automatically sent via email and accessible through the Billing Portal. Migration from V1[​](https://docs.stirlingpdf.com/Paid-Offerings#migration-from-v1 "Direct link to Migration from V1") ----------------------------------------------------------------------------------------------------------------------- If you're upgrading from Stirling PDF V1 with an existing license: 1. Your existing license key will continue to work 2. You can enter it manually via Settings → Admin Plan 3. Or, re-activate through the in-app purchase flow 4. Contact [support@stirlingpdf.com](mailto:support@stirlingpdf.com) if you encounter any issues * * * For pricing details, visit [stirling.com/pricing](https://stirling.com/pricing) For technical support, email [support@stirlingpdf.com](mailto:support@stirlingpdf.com) * [Available Plans](https://docs.stirlingpdf.com/Paid-Offerings#available-plans) * [Free Plan](https://docs.stirlingpdf.com/Paid-Offerings#free-plan) * [Server Plan](https://docs.stirlingpdf.com/Paid-Offerings#server-plan) * [Enterprise Plan](https://docs.stirlingpdf.com/Paid-Offerings#enterprise-plan) * [Purchasing a License](https://docs.stirlingpdf.com/Paid-Offerings#purchasing-a-license) * [In-App Purchase (Recommended)](https://docs.stirlingpdf.com/Paid-Offerings#in-app-purchase-recommended) * [Alternative - Contact Us](https://docs.stirlingpdf.com/Paid-Offerings#alternative---contact-us) * [Activating Your License](https://docs.stirlingpdf.com/Paid-Offerings#activating-your-license) * [Automatic Activation](https://docs.stirlingpdf.com/Paid-Offerings#automatic-activation) * [Manual Activation](https://docs.stirlingpdf.com/Paid-Offerings#manual-activation) * [Legacy - settings.yml Activation](https://docs.stirlingpdf.com/Paid-Offerings#legacy---settingsyml-activation) * [Managing Your Subscription](https://docs.stirlingpdf.com/Paid-Offerings#managing-your-subscription) * [Billing Portal](https://docs.stirlingpdf.com/Paid-Offerings#billing-portal) * [Feature Configuration](https://docs.stirlingpdf.com/Paid-Offerings#feature-configuration) * [License Model](https://docs.stirlingpdf.com/Paid-Offerings#license-model) * [Upgrading Your Plan](https://docs.stirlingpdf.com/Paid-Offerings#upgrading-your-plan) * [Support](https://docs.stirlingpdf.com/Paid-Offerings#support) * [Community Support (All Plans)](https://docs.stirlingpdf.com/Paid-Offerings#community-support-all-plans) * [Email Support (Server & Enterprise)](https://docs.stirlingpdf.com/Paid-Offerings#email-support-server--enterprise) * [Enterprise Support](https://docs.stirlingpdf.com/Paid-Offerings#enterprise-support) * [Frequently Asked Questions](https://docs.stirlingpdf.com/Paid-Offerings#frequently-asked-questions) * [Migration from V1](https://docs.stirlingpdf.com/Paid-Offerings#migration-from-v1) --- # API | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/API#__docusaurus_skipToContent_fallback) On this page Stirling PDF exposes a simple API for easy integration with external scripts. You can access the API documentation in two ways: 1. Local Swagger UI at `/swagger-ui/index.html` on your Stirling PDF instance 2. Online [Swagger Documentation](https://app.swaggerhub.com/apis-docs/Frooodle/Stirling-PDF/) You can also access the documentation through the settings menu (gear icon in the top-right corner). Accessing API Documentation[​](https://docs.stirlingpdf.com/API#accessing-api-documentation "Direct link to Accessing API Documentation") ------------------------------------------------------------------------------------------------------------------------------------------ ### Local Swagger UI[​](https://docs.stirlingpdf.com/API#local-swagger-ui "Direct link to Local Swagger UI") Your Stirling PDF instance includes built-in API documentation: 1. Navigate to `http://your-instance:port/swagger-ui/index.html` 2. Or append `/swagger-ui/index.html` to your Stirling PDF URL 3. This provides an interactive documentation interface where you can: * View all available endpoints * Test API calls directly * See request/response schemas * View authentication requirements ### Settings Menu Access[​](https://docs.stirlingpdf.com/API#settings-menu-access "Direct link to Settings Menu Access") 1. Click the gear icon (⚙️) in the top-right corner 2. Look for the "API Documentation" or "API" link 3. This will take you to the local Swagger UI API Authentication[​](https://docs.stirlingpdf.com/API#api-authentication "Direct link to API Authentication") --------------------------------------------------------------------------------------------------------------- When security is enabled, all API requests require authentication. There are two ways to handle API authentication: ### User-Specific API Keys[​](https://docs.stirlingpdf.com/API#user-specific-api-keys "Direct link to User-Specific API Keys") 1. Obtain your API key: * Log into Stirling PDF * Go to Account Settings (via the gear icon) * Find your API key in the account details ### Global API Key[​](https://docs.stirlingpdf.com/API#global-api-key "Direct link to Global API Key") You can set a custom global API key using the environment variable: SECURITY_CUSTOMGLOBALAPIKEY=your-custom-api-key This allows you to set a single API key that works regardless of user authentication. 2. Include the API key in all requests: X-API-KEY: your-api-key-here 3. Example authenticated request: curl -X POST "http://localhost:8080/add-watermark" \ -H "X-API-KEY: your-api-key-here" \ -H "Content-Type: multipart/form-data" \ ... API Limitations[​](https://docs.stirlingpdf.com/API#api-limitations "Direct link to API Limitations") ------------------------------------------------------------------------------------------------------ Stirling PDF's feature set is not entirely confined to the backend, hence not all functionalities are accessible via the API. Certain operations, such as the "view-pdf" or "visually sign", are executed exclusively on the front-end, and as such, they are only available through the Web-UI. If you encounter a situation where some API endpoints appear to be absent, it is likely attributable to these front-end exclusive features. Stirling PDF also has statistic and health endpoints to integrate with monitoring/dashboard applications. Example CURL Commands[​](https://docs.stirlingpdf.com/API#example-curl-commands "Direct link to Example CURL Commands") ------------------------------------------------------------------------------------------------------------------------ * Unix/Linux/MacOS * Windows CMD curl -X POST "http://localhost:8080/add-watermark" \ -H "Content-Type: multipart/form-data" \ -F "fileInput=@/Users/username/Downloads/sample-1_cropped.pdf" \ -F "watermarkType=text" \ -F "watermarkText=YOUR_WATERMARK_TEXT" \ -F "alphabet=roman" \ -F "fontSize=30" \ -F "rotation=0" \ -F "opacity=0.5" \ -F "widthSpacer=50" \ -F "heightSpacer=50" \ > "/Users/username/Downloads/output.pdf" curl -X POST "http://localhost:8080/add-watermark" ^ -H "Content-Type: multipart/form-data" ^ -F "fileInput=@C:\Users\systo\Downloads\sample-1_cropped.pdf" ^ -F "watermarkType=text" ^ -F "watermarkText=YOUR_WATERMARK_TEXT" ^ -F "alphabet=roman" ^ -F "fontSize=30" ^ -F "rotation=0" ^ -F "opacity=0.5" ^ -F "widthSpacer=50" ^ -F "heightSpacer=50" ^ > "C:\Users\systo\Downloads\output.pdf" * [Accessing API Documentation](https://docs.stirlingpdf.com/API#accessing-api-documentation) * [Local Swagger UI](https://docs.stirlingpdf.com/API#local-swagger-ui) * [Settings Menu Access](https://docs.stirlingpdf.com/API#settings-menu-access) * [API Authentication](https://docs.stirlingpdf.com/API#api-authentication) * [User-Specific API Keys](https://docs.stirlingpdf.com/API#user-specific-api-keys) * [Global API Key](https://docs.stirlingpdf.com/API#global-api-key) * [API Limitations](https://docs.stirlingpdf.com/API#api-limitations) * [Example CURL Commands](https://docs.stirlingpdf.com/API#example-curl-commands) --- # Configuration Guide | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration#__docusaurus_skipToContent_fallback) On this page Stirling PDF can be configured in three ways, depending on your deployment and preferences. Configuration Methods[​](https://docs.stirlingpdf.com/Configuration#configuration-methods "Direct link to Configuration Methods") ---------------------------------------------------------------------------------------------------------------------------------- ### 1\. In-App Settings (Recommended)[​](https://docs.stirlingpdf.com/Configuration#1-in-app-settings-recommended "Direct link to 1. In-App Settings (Recommended)") If you have login enabled, admins can configure everything through the Settings menu in the application. **To use:** 1. Set `SECURITY_ENABLELOGIN=true` 2. Log in as admin 3. Go to Settings → configure through UI 4. Changes apply immediately, no restart needed **Best for:** Production deployments with admin users * * * ### 2\. Environment Variables[​](https://docs.stirlingpdf.com/Configuration#2-environment-variables "Direct link to 2. Environment Variables") Configure via Docker environment variables or system environment variables. **To use:** docker run -d \ -e SECURITY_ENABLELOGIN=true \ -e LANGS=en_GB \ stirlingtools/stirling-pdf:latest **Best for:** Docker deployments, infrastructure-as-code, initial setup * * * ### 3\. Settings File (settings.yml)[​](https://docs.stirlingpdf.com/Configuration#3-settings-file-settingsyml "Direct link to 3. Settings File (settings.yml)") Edit `/configs/settings.yml` directly for advanced configuration. **To use:** security: enableLogin: truesystem: defaultLocale: en-GB **Best for:** Complex configurations, when you prefer file-based config * * * Common Settings[​](https://docs.stirlingpdf.com/Configuration#common-settings "Direct link to Common Settings") ---------------------------------------------------------------------------------------------------------------- ### Authentication[​](https://docs.stirlingpdf.com/Configuration#authentication "Direct link to Authentication") **Note:** Authentication and additional features are included by default in: * **Docker**: All images except ultra-lite (authentication is enabled by default) * **JAR**: [Stirling-PDF-with-login.jar](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) **(Recommended)** The plain [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) does not include authentication or additional features. Configure user login: * Settings File * Environment Variable security: enableLogin: true initialLogin: username: admin password: changeme123 SECURITY_ENABLELOGIN=trueSECURITY_INITIALLOGIN_USERNAME=adminSECURITY_INITIALLOGIN_PASSWORD=changeme123 Default credentials: `admin` / `stirling` (change immediately after first login) For more details, see [System and Security Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) . ### Language & Localization[​](https://docs.stirlingpdf.com/Configuration#language--localization "Direct link to Language & Localization") * Settings File * Environment Variable langs: en_GBsystem: defaultLocale: en-GB LANGS=en_GB # Available languagesSYSTEM_DEFAULTLOCALE=en-GB # Default language **How language selection works:** Stirling PDF determines the interface language using this priority order: 1. **User's manual selection** (highest priority) * When a user clicks the language globe icon and selects a language * Choice is stored in browser's localStorage (persists across sessions) * Storage key: `i18nextLng` 2. **Browser's language preference** * Automatically detected from browser's `Accept-Language` header via the `navigator` API * Example: Firefox set to Swedish (sv-SE) will show Swedish UI 3. **System default locale** (lowest priority) * Set via `SYSTEM_DEFAULTLOCALE` or `system.defaultLocale` * Only applied if user has no localStorage preference (first-time visitors) **Example:** * Config: `SYSTEM_DEFAULTLOCALE=en_GB` * Browser: Swedish (sv-SE) * Result: UI shows Swedish (browser preference overrides config) To force a specific default language regardless of browser settings, users must manually select it via the language globe icon. > **Tip**: Set `SYSTEM_DEFAULTLOCALE` to your organization's primary language. Users can always override it using the language selector in the top-right corner. ### File Upload Limits[​](https://docs.stirlingpdf.com/Configuration#file-upload-limits "Direct link to File Upload Limits") * Settings File * Environment Variable system: maxFileSize: 2000 # MBspring: servlet: multipart: max-file-size: 2000MB max-request-size: 2000MB SYSTEM_MAXFILESIZE=2000 # MBSPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=2000MBSPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=2000MB ### Memory Management[​](https://docs.stirlingpdf.com/Configuration#memory-management "Direct link to Memory Management") JAVA_TOOL_OPTIONS="-Xms512m -Xmx4g" # Min 512MB, Max 4GB RAM * * * Specialized Configuration Guides[​](https://docs.stirlingpdf.com/Configuration#specialized-configuration-guides "Direct link to Specialized Configuration Guides") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- For advanced features and specific use cases, see these detailed guides: ### Authentication & Security[​](https://docs.stirlingpdf.com/Configuration#authentication--security "Direct link to Authentication & Security") **[Single Sign-On (SSO)](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) ** * OAuth2 (Google, GitHub, Keycloak, OIDC) - Server tier * SAML2 (Okta, Azure AD) - Enterprise tier * Complete configuration examples **[System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) ** * Server certificates * JWT configuration **[Fail2Ban Integration](https://docs.stirlingpdf.com/Configuration/fail2ban) ** * Protect against brute-force attacks * Auto-ban after failed login attempts * * * ### Features & Customization[​](https://docs.stirlingpdf.com/Configuration#features--customization "Direct link to Features & Customization") **[UI Customization](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) ** * Branding and logos * Theme customization * Custom styling **[Endpoint/Feature Control](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation) ** * Enable/disable specific tools * Control feature availability by user/role **[Pipeline (Automation)](https://docs.stirlingpdf.com/Configuration/Pipeline) ** * Automated workflows * Folder scanning * Batch processing * Multi-step operations * * * ### Integration & Storage[​](https://docs.stirlingpdf.com/Configuration#integration--storage "Direct link to Integration & Storage") **[External Database](https://docs.stirlingpdf.com/Configuration/External%20Database) ** * PostgreSQL configuration (Pro/Enterprise) * Database migration * Backup strategies **[Google Drive File Picker](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker) ** * Direct Google Drive integration * OAuth setup **[OCR Configuration](https://docs.stirlingpdf.com/Configuration/OCR) ** * Tesseract language packs * OCR optimization **[Usage Monitoring](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) ** * Prometheus metrics (Pro/Enterprise) * Application monitoring * Performance tracking * * * ### Other Configuration[​](https://docs.stirlingpdf.com/Configuration#other-configuration "Direct link to Other Configuration") **[Folder Scanning](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) ** * Watch folders for automatic processing **[Custom Signature Files](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files) ** * Pre-loaded signatures for quick signing **[Extra Settings](https://docs.stirlingpdf.com/Configuration/Extra-Settings) ** * Logging configuration * Server settings (port, SSL/TLS) * Advanced Spring Boot settings * * * Configuration Priority[​](https://docs.stirlingpdf.com/Configuration#configuration-priority "Direct link to Configuration Priority") ------------------------------------------------------------------------------------------------------------------------------------- When the same setting is defined in multiple places, this is the order of precedence (highest to lowest): 1. **Environment Variables** 2. **settings.yml / In-App Settings** 3. **Default values** * * * Environment Variable Format[​](https://docs.stirlingpdf.com/Configuration#environment-variable-format "Direct link to Environment Variable Format") ---------------------------------------------------------------------------------------------------------------------------------------------------- Convert YAML paths to environment variables: # settings.ymlsecurity: enableLogin: true Becomes: SECURITY_ENABLELOGIN=true **Rules:** * Uppercase everything * Replace `.` with `_` * Nested properties become `PARENT_CHILD` * * * Troubleshooting[​](https://docs.stirlingpdf.com/Configuration#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------------------------------------------------- ### Settings Not Applied[​](https://docs.stirlingpdf.com/Configuration#settings-not-applied "Direct link to Settings Not Applied") 1. Check configuration priority (env vars override settings.yml) 2. Restart container after changing environment variables 3. Check logs: `docker logs stirling-pdf | grep ERROR` 4. Verify file permissions on `/configs` volume ### Database Issues[​](https://docs.stirlingpdf.com/Configuration#database-issues "Direct link to Database Issues") Default database location: `/configs/stirling-pdf-DB.mv.db` If missing: * Ensure `/configs` volume is mounted * Check write permissions * Review startup logs * * * Next Steps[​](https://docs.stirlingpdf.com/Configuration#next-steps "Direct link to Next Steps") ------------------------------------------------------------------------------------------------- * **Production Deployment:** See [Production Deployment Guide](https://docs.stirlingpdf.com/Production-Deployment-Guide) * **API Usage:** See [API Documentation](https://docs.stirlingpdf.com/API) * **Tool Reference:** See [Functionality](https://docs.stirlingpdf.com/functionality) * [Configuration Methods](https://docs.stirlingpdf.com/Configuration#configuration-methods) * [1\. In-App Settings (Recommended)](https://docs.stirlingpdf.com/Configuration#1-in-app-settings-recommended) * [2\. Environment Variables](https://docs.stirlingpdf.com/Configuration#2-environment-variables) * [3\. Settings File (settings.yml)](https://docs.stirlingpdf.com/Configuration#3-settings-file-settingsyml) * [Common Settings](https://docs.stirlingpdf.com/Configuration#common-settings) * [Authentication](https://docs.stirlingpdf.com/Configuration#authentication) * [Language & Localization](https://docs.stirlingpdf.com/Configuration#language--localization) * [File Upload Limits](https://docs.stirlingpdf.com/Configuration#file-upload-limits) * [Memory Management](https://docs.stirlingpdf.com/Configuration#memory-management) * [Specialized Configuration Guides](https://docs.stirlingpdf.com/Configuration#specialized-configuration-guides) * [Authentication & Security](https://docs.stirlingpdf.com/Configuration#authentication--security) * [Features & Customization](https://docs.stirlingpdf.com/Configuration#features--customization) * [Integration & Storage](https://docs.stirlingpdf.com/Configuration#integration--storage) * [Other Configuration](https://docs.stirlingpdf.com/Configuration#other-configuration) * [Configuration Priority](https://docs.stirlingpdf.com/Configuration#configuration-priority) * [Environment Variable Format](https://docs.stirlingpdf.com/Configuration#environment-variable-format) * [Troubleshooting](https://docs.stirlingpdf.com/Configuration#troubleshooting) * [Settings Not Applied](https://docs.stirlingpdf.com/Configuration#settings-not-applied) * [Database Issues](https://docs.stirlingpdf.com/Configuration#database-issues) * [Next Steps](https://docs.stirlingpdf.com/Configuration#next-steps) --- # Production Deployment Guide | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Production-Deployment-Guide#__docusaurus_skipToContent_fallback) On this page Welcome! This guide will walk you through deploying Stirling-PDF for your organization, from initial installation to advanced configuration and scaling. For Organizations & Teams This guide is designed for server administrators deploying Stirling-PDF for teams, departments, or entire organizations. If you're interested in **paid plan features** (external database, Google Drive, SSO, advanced user management, priority support), we'll highlight upgrade paths throughout this guide. * * * Overview: What You'll Accomplish[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#overview-what-youll-accomplish "Direct link to Overview: What You'll Accomplish") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- By the end of this guide, you'll have: 1. ✅ **Stirling-PDF running** on your infrastructure 2. ✅ **User authentication configured** with admin access 3. ✅ **Settings customized** for your organization 4. ✅ **Security hardened** with HTTPS and proper access controls 5. ✅ **Monitoring setup** to track usage and performance 6. ✅ **Understanding of paid plan** upgrade paths (Server/Enterprise) **Time estimate:** 30-60 minutes for basic setup, 2-3 hours for full enterprise configuration * * * Step 1: Choose Your Deployment Path[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-1-choose-your-deployment-path "Direct link to Step 1: Choose Your Deployment Path") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Docker Compose (Recommended) * Docker Run * Kubernetes * Bare Metal / JAR **Best for:** Most organizations, production deployments, easy management **Why Docker Compose?** * ✅ Simple one-command deployment * ✅ Easy updates and rollbacks * ✅ Persistent data management * ✅ Production-ready configuration * ✅ Easy to scale and customize **Requirements:** * Docker Engine 20.10+ * Docker Compose 1.29+ * 2GB RAM minimum (4GB+ recommended) * 10GB disk space **Jump to:** [Docker Compose Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-compose-setup) **Best for:** Quick testing, single-container deployments, learning **Why Docker Run?** * ✅ Fastest way to get started * ✅ Single command deployment * ✅ Good for testing before production * ⚠️ More manual management needed **Requirements:** * Docker Engine 20.10+ * 2GB RAM minimum * 5GB disk space **Jump to:** [Docker Run Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-run-setup) **Best for:** Enterprise scale, high availability, cloud-native deployments **Why Kubernetes?** * ✅ Auto-scaling capabilities * ✅ High availability and fault tolerance * ✅ Load balancing built-in * ✅ Cloud provider integration * ⚠️ More complex to set up **Requirements:** * Kubernetes cluster 1.19+ * kubectl configured * Persistent volume support * Load balancer support **Jump to:** [Kubernetes Guide](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install) **Best for:** Environments without Docker, specific OS requirements **Why Bare Metal?** * ✅ Maximum control * ✅ No container overhead * ✅ Custom Java configurations * ⚠️ More maintenance required **Requirements:** * Java 21+ * Linux/Unix system * 2GB RAM minimum * LibreOffice, Tesseract (for features) **Jump to:** [Unix Installation Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) * * * Step 2: Installation[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-2-installation "Direct link to Step 2: Installation") -------------------------------------------------------------------------------------------------------------------------------------------- Follow the installation instructions for your chosen deployment method from Step 1. * Docker Compose (Recommended) * Docker Run * Kubernetes * Bare Metal / JAR ### Docker Compose Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-compose-setup "Direct link to Docker Compose Setup") This is the recommended approach for production deployments. #### 2.1: Create docker-compose.yml[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#21-create-docker-composeyml "Direct link to 2.1: Create docker-compose.yml") Create a directory for your Stirling-PDF deployment: mkdir -p ~/stirling-pdfcd ~/stirling-pdf Create `docker-compose.yml` with this production-ready configuration: services: stirling-pdf: image: stirlingtools/stirling-pdf:latest container_name: stirling-pdf ports: - '8080:8080' volumes: # Persistent data storage - ./stirling-data/tessdata:/usr/share/tessdata # OCR language files - ./stirling-data/configs:/configs # Settings & database - ./stirling-data/logs:/logs # Application logs - ./stirling-data/customFiles:/customFiles:rw # Custom branding files - ./stirling-data/pipeline:/pipeline # Automation configs environment: # Core Settings - SECURITY_ENABLELOGIN=true # Enable user authentication # Language & Localization - LANGS=en_GB # Change to your locale # System Configuration - SYSTEM_DEFAULTLOCALE=en-GB # Default locale - SYSTEM_GOOGLEVISIBILITY=false # Hide from search engines - SYSTEM_ROOTURIPATH=/ # Base URL path - SYSTEM_CONNECTIONTIMEOUTMINUTES=5 # Connection timeout - SYSTEM_MAXFILESIZE=2000 # Max file size in MB # Optional: Logging - SYSTEM_CUSTOMSTATICFILEPATH=/customFiles/static/ # Custom files path restart: unless-stopped # Optional: Resource limits deploy: resources: limits: memory: 4G cpus: '2.0' reservations: memory: 2G cpus: '1.0' #### 2.2: Start Stirling-PDF[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#22-start-stirling-pdf "Direct link to 2.2: Start Stirling-PDF") # Start the containerdocker-compose up -d# Check if it's runningdocker-compose ps# View logsdocker-compose logs -f #### 2.3: Verify Installation[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#23-verify-installation "Direct link to 2.3: Verify Installation") Open your browser and navigate to: http://your-server-ip:8080 You should see the Stirling-PDF homepage! Success! If you see the Stirling-PDF interface, your installation is successful. Continue to Step 3 to set up authentication. **Troubleshooting:** * **Can't connect?** Check firewall rules: `sudo ufw allow 8080` * **Container won't start?** Check logs: `docker-compose logs` * **Permission errors?** Fix permissions: `sudo chmod -R 755 ./stirling-data` ### Docker Run Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-run-setup "Direct link to Docker Run Setup") For quick testing or simpler deployments. #### 2.1: Create Data Directory and Run Container[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#21-create-data-directory-and-run-container "Direct link to 2.1: Create Data Directory and Run Container") # Create data directorymkdir -p ~/stirling-data# Run Stirling-PDFdocker 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/customFiles:/customFiles:rw \ -e SECURITY_ENABLELOGIN=true \ -e LANGS=en_GB \ -e SYSTEM_DEFAULTLOCALE=en-GB \ -e SYSTEM_GOOGLEVISIBILITY=false \ -e SYSTEM_MAXFILESIZE=2000 \ --restart unless-stopped \ stirlingtools/stirling-pdf:latest #### 2.2: Verify Installation[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#22-verify-installation "Direct link to 2.2: Verify Installation") # Check if runningdocker ps | grep stirling-pdf# View logsdocker logs -f stirling-pdf Open your browser and navigate to: http://your-server-ip:8080 You should see the Stirling-PDF homepage! Success! If you see the Stirling-PDF interface, your installation is successful. Continue to Step 3 to set up authentication. **Troubleshooting:** * **Can't connect?** Check firewall rules: `sudo ufw allow 8080` * **Container won't start?** Check logs: `docker logs stirling-pdf` * **Permission errors?** Fix permissions: `sudo chmod -R 755 ~/stirling-data` ### Kubernetes Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#kubernetes-setup "Direct link to Kubernetes Setup") For enterprise-scale deployments with high availability. Kubernetes deployment requires: * Persistent Volume Claims (PVCs) * Deployments and Services * Ingress/LoadBalancer configuration * Resource limits and autoscaling **See full guide:** [Kubernetes Installation Guide](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install) This includes complete YAML configurations, namespace setup, SSL/TLS, and horizontal pod autoscaling. ### Bare Metal Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#bare-metal-setup "Direct link to Bare Metal Setup") For environments without Docker or specific OS requirements. Bare metal installation requires: * Java 21+ * LibreOffice (for conversions) * Tesseract OCR (for OCR features) * Systemd service setup **See full guide:** [Unix Installation Guide](https://docs.stirlingpdf.com/Installation/Unix%20Installation) This includes complete dependency installation, JAR setup, systemd configuration, and troubleshooting. * * * Step 3: Initial Login & Admin Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-3-initial-login--admin-setup "Direct link to Step 3: Initial Login & Admin Setup") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now that Stirling-PDF is running with authentication enabled, you need to create your admin account. ### 3.1: First-Time Login[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#31-first-time-login "Direct link to 3.1: First-Time Login") 1. **Navigate to your Stirling-PDF instance:** http://your-server-ip:8080 2. **Log in with default credentials:** Username: adminPassword: stirling 3. **Change the default password immediately:** * After first login, go to Settings → Account * Change to a strong password (12+ characters, mixed case, numbers, symbols) Customizing Default Credentials You can set custom default credentials **before first startup** using environment variables: environment: - SECURITY_INITIALLOGIN_USERNAME=youradmin - SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123! **Important:** These only work on first startup. If you change them after the database is created, the old credentials remain active. Always change the password through the UI after first login. User Registration After first login, you can control how additional users are created through Settings → Security (covered in Step 4). ### 3.2: Verify Admin Access[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#32-verify-admin-access "Direct link to 3.2: Verify Admin Access") 1. **Log in with your admin account** 2. **Click the Settings gear icon** ⚙️ in the top navigation bar 3. **Verify you have admin access** by checking for admin-only sections: * **General Settings** - System configuration * **Security Settings** - User management, login settings * **UI Customization** - Branding and appearance * **User Management** - Create/manage users * **Endpoint Configuration** - Enable/disable tools **Note:** Regular users can also access Settings but only see their personal preferences (language, theme). Only admins see the sections listed above. 4. **If you don't see admin sections:** * Check logs: `docker logs stirling-pdf` * Verify you're the first user created * Confirm `SECURITY_ENABLELOGIN=true` is set Secure Your Admin Account * **Change the default password immediately** after first login * Use a strong password (12+ characters, mixed case, numbers, symbols) * Consider using SSO (OAuth2/SAML2) to avoid password management entirely * * * Step 4: Configure Essential Settings[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-4-configure-essential-settings "Direct link to Step 4: Configure Essential Settings") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now that you're logged in as admin, let's configure Stirling-PDF for your organization. ### 4.1: General Settings[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#41-general-settings "Direct link to 4.1: General Settings") Navigate to **Settings → General** * Must Configure * Should Configure **These settings should be configured immediately:** #### System Locale & Language[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#system-locale--language "Direct link to System Locale & Language") system: defaultLocale: en-US # or en-GB, de-DE, fr-FR, etc.ui: languages: [] # Empty = all languages enabled. Or specify: ["en_GB", "de_DE", "fr_FR"] **Why:** Ensures UI appears in the correct language for your users #### Search Engine Visibility[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#search-engine-visibility "Direct link to Search Engine Visibility") system: googlevisibility: false # Prevents search engines from indexing your site **Why:** Keeps your internal PDF tool private #### File Upload Limits[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#file-upload-limits "Direct link to File Upload Limits") system: fileUploadLimit: 2000MB # or "2GB" - adjust based on your needs **Why:** Prevents users from uploading files that crash the system **Configure these for better user experience:** #### Legal & Compliance[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#legal--compliance "Direct link to Legal & Compliance") legal: termsAndConditions: https://yourcompany.com/tos # or empty string to disable privacyPolicy: https://yourcompany.com/privacy # or empty string to disable accessibilityStatement: '' # optional cookiePolicy: '' # optional impressum: '' # optional (required in some countries like Germany) **Why:** Legal compliance, especially in GDPR/regulated industries #### Update Notifications (Optional)[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#update-notifications-optional "Direct link to Update Notifications (Optional)") system: showUpdate: false # Set true to show update notifications showUpdateOnlyAdmin: false # Only admins see updates (requires showUpdate: true) **Why:** Control update notifications in production environments #### Process Limits[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#process-limits "Direct link to Process Limits") processExecutor: sessionLimit: libreOfficeSessionLimit: 1 tesseractSessionLimit: 1 pythonOpenCvSessionLimit: 8 timeoutMinutes: libreOfficetimeoutMinutes: 30 tesseractTimeoutMinutes: 30 **Why:** Prevents resource exhaustion based on your server capacity ### 4.2: Security Settings[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#42-security-settings "Direct link to 4.2: Security Settings") Navigate to **Settings → Security** Critical for Production These settings directly impact your organization's security. Review carefully! #### User Registration Control[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#user-registration-control "Direct link to User Registration Control") * Invite-Only (Recommended) * SSO (OAuth2/SAML2) **Best for:** Controlled environments, enterprises, security-conscious orgs **How it works:** 1. Admin creates user accounts manually in Settings → User Management 2. Admin shares credentials with users securely 3. Users log in with provided credentials **Email Invitations (Optional):** If you configure email, admins can send invitation links instead. * settings.yml * Environment Variables mail: enabled: true from: noreply@yourcompany.com enableInvites: true smtp: host: smtp.gmail.com port: 587 username: noreply@yourcompany.com password: ${MAIL_PASSWORD} # Use environment variable tls: enabled: true MAIL_ENABLED=trueMAIL_FROM=noreply@yourcompany.comMAIL_ENABLEINVITES=trueMAIL_HOST=smtp.gmail.comMAIL_PORT=587MAIL_USERNAME=noreply@yourcompany.comMAIL_PASSWORD=your-app-passwordMAIL_TLS_ENABLED=true **Best for:** Large enterprises, existing SSO infrastructure **Single Sign-On (SSO) options:** * **OAuth2:** Server tier - Supports Google, GitHub, Keycloak, any OpenID Connect provider * **SAML2:** Enterprise tier - Supports Okta, Azure AD, etc. **Key settings:** security: enableLogin: true loginMethod: oauth2 # or 'saml2' or 'all' oauth2: enabled: true autoCreateUser: true # Auto-create users on first login blockRegistration: false # Set true to require admin pre-registration **Benefits:** * ✅ No password management * ✅ Centralized access control * ✅ Automatic user provisioning * ✅ Corporate policy compliance **See full guide:** [SSO Configuration Guide](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) Complete configuration examples for Google, GitHub, Keycloak, Okta, Azure AD, and generic OIDC/SAML2 providers. #### Login Security Settings[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#login-security-settings "Direct link to Login Security Settings") security: csrfDisabled: false # NEVER disable CSRF protection in production loginAttemptCount: 5 # Lock account after 5 failed attempts loginResetTimeMinutes: 120 # Unlock after 2 hours **Notes:** * Session timeout is not configurable via settings * Password policies (length, complexity) are not currently configurable * Use SSO/OAuth2 for enterprise password policies ### 4.3: Feature Control[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#43-feature-control "Direct link to 4.3: Feature Control") Navigate to **Settings → Endpoints** Control which PDF tools are available to users. * Recommended Features * Disabling Specific Tools **All tools are enabled by default.** You can disable specific tools if needed: endpoints: toRemove: [] # Add tool IDs to disable, e.g. ['sign', 'add-password'] groupsToRemove: [] # Disable entire groups, e.g. ['LibreOffice'] **Most organizations don't need to disable anything** - all tools are useful and safe **Example: Disable security-sensitive tools:** endpoints: toRemove: - 'add-password' # Disable password protection tool - 'remove-password' # Disable password removal tool - 'change-permissions' # Disable permissions modification **Example: Disable entire groups:** endpoints: groupsToRemove: - 'LibreOffice' # Disables all LibreOffice-based conversions **How to disable in UI:** 1. Log in as admin 2. Go to Settings → Endpoints 3. Find tool you want to disable 4. Toggle off 5. Save changes **See all tool IDs:** [Endpoint Customisation](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation) ### 4.4: Save and Apply Settings[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#44-save-and-apply-settings "Direct link to 4.4: Save and Apply Settings") After configuring all settings: 1. **Click "Save" button** at the bottom of each settings page 2. **Verify settings saved** - You should see a success message 3. **Some settings require restart** - Check if restart notification appears 4. **Test changes** - Log out and log in as a regular user to verify **If restart is needed:** # Docker Composedocker-compose restart# Docker Rundocker restart stirling-pdf * * * Step 5: HTTPS & Domain Setup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-5-https--domain-setup "Direct link to Step 5: HTTPS & Domain Setup") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Production Requirement **Never run in production without HTTPS.** User credentials and PDF files will be transmitted in plain text over the network. ### 5.1: Choose Your HTTPS Method[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#51-choose-your-https-method "Direct link to 5.1: Choose Your HTTPS Method") * Built-in SSL (Simple) * Reverse Proxy (Production) * Traefik (Docker-Native) * Cloudflare Tunnel **Best for:** Simple deployments, no reverse proxy needed Stirling-PDF can handle HTTPS directly using built-in SSL configuration. #### Configure SSL in Stirling-PDF[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#configure-ssl-in-stirling-pdf "Direct link to Configure SSL in Stirling-PDF") 1. **Generate or obtain SSL certificate:** **Option A: Self-signed (for testing/internal use):** # Generate self-signed certificatekeytool -genkeypair \ -alias stirling \ -keyalg RSA \ -keysize 2048 \ -storetype PKCS12 \ -keystore keystore.p12 \ -validity 365# Move to configs directorymv keystore.p12 ./stirling-data/configs/ **Option B: Let's Encrypt (for production):** # Get certificate with certbotsudo certbot certonly --standalone -d pdf.yourcompany.com# Convert to PKCS12 formatsudo openssl pkcs12 -export \ -in /etc/letsencrypt/live/pdf.yourcompany.com/fullchain.pem \ -inkey /etc/letsencrypt/live/pdf.yourcompany.com/privkey.pem \ -out keystore.p12 \ -name stirling# Move to configssudo mv keystore.p12 ./stirling-data/configs/sudo chown $USER:$USER ./stirling-data/configs/keystore.p12 2. **Create custom\_settings.yml:** Create `./stirling-data/configs/custom_settings.yml`: server: port: 8443 # HTTPS port ssl: enabled: true key-store: file:/configs/keystore.p12 key-store-password: your-keystore-password key-store-type: PKCS12 key-alias: stirling 3. **Update docker-compose.yml to expose port 8443:** services: stirling-pdf: ports: - '8443:8443' # Change from 8080:8080 4. **Restart Stirling-PDF:** docker-compose downdocker-compose up -d 5. **Access via HTTPS:** https://pdf.yourcompany.com:8443 **Benefits:** * ✅ Simple setup, no reverse proxy needed * ✅ Direct SSL termination in application * ✅ Good for small deployments **Limitations:** * ⚠️ Manual certificate renewal * ⚠️ No load balancing * ⚠️ Port 8443 instead of standard 443 **Learn more:** [Custom Settings - SSL Configuration](https://docs.stirlingpdf.com/Production-Deployment-Guide/Configuration/Extra-Settings#ssltls-configuration) **Best for:** Production deployments, standard ports (443), load balancing Use a reverse proxy like **Nginx, Apache, or Traefik** to handle HTTPS. #### Option A: Nginx with Let's Encrypt[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#option-a-nginx-with-lets-encrypt "Direct link to Option A: Nginx with Let's Encrypt") **Install Nginx and Certbot:** sudo apt updatesudo apt install nginx certbot python3-certbot-nginx **Configure Nginx:** Create `/etc/nginx/sites-available/stirling-pdf`: server { listen 80; server_name pdf.yourcompany.com; # Redirect HTTP to HTTPS return 301 https://$server_name$request_uri;}server { listen 443 ssl http2; server_name pdf.yourcompany.com; # SSL certificates (will be added by certbot) ssl_certificate /etc/letsencrypt/live/pdf.yourcompany.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/pdf.yourcompany.com/privkey.pem; # Strong SSL settings ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_prefer_server_ciphers on; # Security headers add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; # Large file uploads client_max_body_size 2000M; client_body_timeout 300s; # Proxy to Stirling-PDF location / { proxy_pass http://localhost: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; # WebSocket support (if needed) proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # Timeouts for large files proxy_connect_timeout 300s; proxy_send_timeout 300s; proxy_read_timeout 300s; }} **Enable site and get certificate:** # Enable sitesudo ln -s /etc/nginx/sites-available/stirling-pdf /etc/nginx/sites-enabled/sudo nginx -tsudo systemctl reload nginx# Get Let's Encrypt certificatesudo certbot --nginx -d pdf.yourcompany.com# Auto-renewal (certbot sets this up automatically)sudo certbot renew --dry-run **Update DNS:** A record: pdf.yourcompany.com → your-server-ip **Access your site:** https://pdf.yourcompany.com **Best for:** Docker environments, automatic certificate management Traefik is a Docker-native reverse proxy that automatically: * Obtains SSL certificates from Let's Encrypt * Renews certificates automatically * Routes traffic based on Docker labels **Key benefits:** * ✅ Zero-config certificate management * ✅ Docker label-based routing * ✅ Automatic service discovery Add Traefik container to your `docker-compose.yml` and configure Stirling-PDF with Docker labels for routing. **See Traefik documentation:** [https://doc.traefik.io/traefik/user-guides/docker-compose/basic-example/](https://doc.traefik.io/traefik/user-guides/docker-compose/basic-example/) **Best for:** No public IP, behind firewall, home servers Cloudflare Tunnel provides: * ✅ No port forwarding needed * ✅ DDoS protection included * ✅ Automatic HTTPS * ✅ Free for most use cases **Quick setup:** 1. Install `cloudflared` 2. Authenticate with Cloudflare 3. Create tunnel pointing to `http://localhost:8080` 4. Add DNS record 5. Run as system service **See Cloudflare documentation:** [https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/) ### 5.2: Update Stirling-PDF Configuration[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#52-update-stirling-pdf-configuration "Direct link to 5.2: Update Stirling-PDF Configuration") After setting up HTTPS, update Stirling-PDF to use the correct URL: **In Settings → General:** System Settings: Root URI Path: / (or /pdf if using subdirectory) Frontend URL: https://pdf.yourcompany.com CORS Allowed Origins: https://pdf.yourcompany.com * * * Step 6: User Management[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-6-user-management "Direct link to Step 6: User Management") ----------------------------------------------------------------------------------------------------------------------------------------------------- Now that your system is secure and accessible, let's set up users. ### 6.1: Understanding User Roles[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#61-understanding-user-roles "Direct link to 6.1: Understanding User Roles") * Standard Roles **Out-of-the-box roles:** | Role | Permissions | Use Case | | --- | --- | --- | | **Admin** | Full access to all features, settings, user management | System administrators, IT staff | | **User** | Access to enabled PDF tools, no settings access | Regular employees, end users | **Admin capabilities:** * ✅ Access all PDF tools * ✅ Manage users (create, delete, reset passwords) * ✅ Configure all settings * ✅ View usage statistics * ✅ Enable/disable features * ✅ View logs (if configured) **User capabilities:** * ✅ Access enabled PDF tools only * ✅ Upload and process files * ✅ Download results * ❌ No settings access * ❌ No user management * ❌ No system configuration ### 6.2: Adding Users[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#62-adding-users "Direct link to 6.2: Adding Users") * Manual Creation * Email Invitation (Recommended) **As admin, manually create user accounts:** 1. **Navigate to Settings → User Management** 2. **Click "Add User" button** 3. **Fill in user details:** Username: john.doeEmail: john.doe@yourcompany.com (optional but recommended)Password: Auto-generate or set manuallyRole: User (or Admin for additional admins)Enabled: Yes 4. **Click "Create User"** 5. **Share credentials with user** (via secure channel) **Bulk user creation:** You can paste a list of email addresses (one per line) to create multiple users at once. **Best practices:** * Use email as username for easier identification * Auto-generate strong passwords * Keep records of who has access **Send email invitations** (requires email configuration): 1. **Navigate to Settings → User Management** 2. **Click "Invite User" button** 3. **Fill in details:** Email: jane.smith@yourcompany.comRole: UserMessage: Optional welcome message 4. **Click "Send Invitation"** 5. **User receives email** with magic link to register 6. **User clicks link, creates password, and is automatically logged in** **Bulk invitations:** You can paste a list of email addresses (one per line) to send multiple invitations at once. **Benefits:** * ✅ More secure (user sets own password) * ✅ Professional onboarding experience * ✅ Magic link authentication * ✅ No need to share passwords **Email configuration required:** Email Settings: SMTP Host: smtp.gmail.com SMTP Port: 587 SMTP Username: noreply@yourcompany.com SMTP Password: your-app-password From Address: noreply@yourcompany.com ### 6.3: User Management Tasks[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#63-user-management-tasks "Direct link to 6.3: User Management Tasks") **Common admin tasks:** #### View All Users[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#view-all-users "Direct link to View All Users") * Navigate to **Settings → User Management** * See list of all users with status, role, last login #### Reset User Password[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#reset-user-password "Direct link to Reset User Password") 1. Find user in user list 2. Click "Reset Password" button 3. New password generated or set manually 4. Share new password securely #### Disable/Enable User[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#disableenable-user "Direct link to Disable/Enable User") 1. Find user in user list 2. Toggle "Enabled" switch 3. Disabled users cannot log in #### Delete User[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#delete-user "Direct link to Delete User") 1. Find user in user list 2. Click "Delete" button 3. Confirm deletion 4. ⚠️ **Warning:** This is permanent #### Change User Role[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#change-user-role "Direct link to Change User Role") 1. Find user in user list 2. Change role dropdown (User/Admin) 3. Save changes * * * Step 7: Monitoring & Usage Tracking[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-7-monitoring--usage-tracking "Direct link to Step 7: Monitoring & Usage Tracking") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Understanding how your users are using Stirling-PDF helps with capacity planning and identifying issues. ### 7.1: Basic Monitoring[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#71-basic-monitoring "Direct link to 7.1: Basic Monitoring") * Docker Logs * External Monitoring **View application logs:** # Docker Composedocker-compose logs -f stirling-pdf# Docker Rundocker logs -f stirling-pdf# Last 100 linesdocker logs --tail 100 stirling-pdf# Filter for errorsdocker logs stirling-pdf 2>&1 | grep ERROR **What to look for:** * ✅ Successful operations * ⚠️ Warnings (disk space, memory) * ❌ Errors (failed operations, crashes) * 🔒 Security events (failed logins, unauthorized access) **Common log entries:** INFO: User john.doe uploaded file document.pdfINFO: Operation MERGE completed successfullyWARN: Disk space low: 85% usedERROR: OCR operation failed: Tesseract not found #### Basic API Monitoring[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#basic-api-monitoring "Direct link to Basic API Monitoring") **Usage Statistics API** (available to all users): # Application statuscurl http://localhost:8080/api/v1/info/status# Request countscurl http://localhost:8080/api/v1/info/requests/all# Unique userscurl http://localhost:8080/api/v1/info/requests/all/unique **Health Check Endpoint:** curl http://localhost:8080/api/v1/health# Response:{"status":"UP","components":{"diskSpace":{"status":"UP"}}} **Use for:** * Load balancer health checks * Uptime monitoring (Uptime Robot, Pingdom) * Custom monitoring scripts #### Prometheus Integration (Enterprise)[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#prometheus-integration-enterprise "Direct link to Prometheus Integration (Enterprise)") Stirling-PDF Enterprise plan supports Prometheus metrics for advanced monitoring. **Learn more:** [Usage Monitoring - Prometheus Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide/Configuration/Usage%20Monitoring#prometheus-monitoring-configuration) **Features:** * JVM metrics (memory, GC, threads) * System metrics (CPU, disk) * Application metrics (request rates, processing times) * PDF processing metrics #### Log Aggregation[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#log-aggregation "Direct link to Log Aggregation") Forward logs to centralized logging: **Option 1: Docker log driver** services: stirling-pdf: logging: driver: "json-file" options: max-size: "10m" max-file: "3" **Option 2: Syslog** services: stirling-pdf: logging: driver: syslog options: syslog-address: "tcp://your-syslog-server:514" **Popular log aggregation tools:** * ELK Stack (Elasticsearch, Logstash, Kibana) * Splunk * Graylog * Datadog ### 7.2: Set Up Monitoring[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#72-set-up-monitoring "Direct link to 7.2: Set Up Monitoring") **Basic monitoring approach:** 1. **Monitor Docker logs regularly:** docker logs stirling-pdf --tail 100 -f 2. **Check Docker container health:** docker psdocker stats stirling-pdf 3. **Monitor disk space:** df -hdu -sh ./stirling-data/* 4. **Use external uptime monitoring:** * Uptime Robot (free) * Pingdom * StatusCake * Monitor the health endpoint: `http://localhost:8080/api/v1/health` * * * Step 8: Backup & Disaster Recovery[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-8-backup--disaster-recovery "Direct link to Step 8: Backup & Disaster Recovery") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Protect your users' data and configuration with proper backups. ### 8.1: What to Backup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#81-what-to-backup "Direct link to 8.1: What to Backup") **Critical data to backup:** | Data | Location | Frequency | Importance | | --- | --- | --- | --- | | **User Database (if local)** | `./stirling-data/configs/stirling-pdf.db` | Daily | Critical\* | | **Settings File** | `./stirling-data/configs/settings.yml` | After changes | Critical | | **Custom Files** | `./stirling-data/customFiles/` | After changes | High | | **OCR Languages** | `./stirling-data/tessdata/` | Weekly | Medium | | **Logs** | `./stirling-data/logs/` | Optional | Low | **\*Note on User Database:** * **Free edition:** Uses local H2 database (`stirling-pdf.db`) - must be backed up * **Server/Enterprise:** Should use external PostgreSQL database (backed up separately) Server/Enterprise Recommendation Server and Enterprise plan users should configure an external PostgreSQL database instead of using the local H2 database. This provides better reliability, scalability, and backup capabilities. **Learn more:** [External Database Configuration](https://docs.stirlingpdf.com/Configuration/External%20Database) ### 8.2: Backup Strategies[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#82-backup-strategies "Direct link to 8.2: Backup Strategies") * Simple Backup Script * Docker Volume Backup **Create automated backup script:** Create `backup-stirling.sh`: #!/bin/bash# ConfigurationBACKUP_DIR="/backups/stirling-pdf"STIRLING_DATA="/path/to/stirling-data"RETENTION_DAYS=30# Create backup directorymkdir -p "$BACKUP_DIR"# Generate timestampTIMESTAMP=$(date +%Y%m%d-%H%M%S)BACKUP_FILE="$BACKUP_DIR/stirling-backup-$TIMESTAMP.tar.gz"# Stop container (optional, for consistency)# docker-compose -f /path/to/docker-compose.yml stop stirling-pdf# Create backuptar -czf "$BACKUP_FILE" \ -C "$STIRLING_DATA" \ configs/ \ customFiles/ \ tessdata/# Start container (if stopped)# docker-compose -f /path/to/docker-compose.yml start stirling-pdf# Delete old backupsfind "$BACKUP_DIR" -name "stirling-backup-*.tar.gz" -mtime +$RETENTION_DAYS -delete# Log resultecho "[$TIMESTAMP] Backup completed: $BACKUP_FILE" **Make executable and schedule:** chmod +x backup-stirling.sh# Add to crontab (daily at 2 AM)crontab -e# Add: 0 2 * * * /path/to/backup-stirling.sh >> /var/log/stirling-backup.log 2>&1 **Backup Docker volumes:** # Stop containerdocker-compose stop stirling-pdf# Backup volumesdocker run --rm \ -v $(pwd)/stirling-data:/data \ -v $(pwd)/backups:/backup \ alpine tar -czf /backup/stirling-data-$(date +%Y%m%d).tar.gz /data# Start containerdocker-compose start stirling-pdf **Automated with Cron:** Create `docker-volume-backup.sh`: #!/bin/bashcd /path/to/stirling-pdfdocker-compose stop stirling-pdfdocker run --rm \ -v "$(pwd)/stirling-data:/data" \ -v "$(pwd)/backups:/backup" \ alpine tar -czf /backup/stirling-data-$(date +%Y%m%d).tar.gz /datadocker-compose start stirling-pdf# Cleanup old backups (keep 30 days)find backups/ -name "stirling-data-*.tar.gz" -mtime +30 -delete ### 8.3: Restore from Backup[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#83-restore-from-backup "Direct link to 8.3: Restore from Backup") **Restore procedure:** 1. **Stop Stirling-PDF:** docker-compose stop stirling-pdf 2. **Extract backup:** tar -xzf stirling-backup-YYYYMMDD-HHMMSS.tar.gz -C ./stirling-data/ 3. **Verify files restored:** ls -la ./stirling-data/configs/# Should see: stirling-pdf.db, settings.yml 4. **Start Stirling-PDF:** docker-compose start stirling-pdf 5. **Verify functionality:** * Access web interface * Log in as admin * Check users exist * Verify settings * * * Step 9: Performance Optimization[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-9-performance-optimization "Direct link to Step 9: Performance Optimization") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Optimize Stirling-PDF for your workload and server capacity. ### 9.1: Resource Allocation[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#91-resource-allocation "Direct link to 9.1: Resource Allocation") * Small Team (5-20 users) * Medium Team (20-100 users) * Large Organization (100+ users) **Recommended specifications:** * **CPU:** 2 cores * **RAM:** 4GB * **Disk:** 20GB * **Concurrent operations:** 2-4 **Docker resource limits:** deploy: resources: limits: memory: 4G cpus: '2.0' reservations: memory: 2G cpus: '1.0' **Settings:** system: maxFileSize: 500 # 500MB max file connectionTimeoutMinutes: 5 maxConcurrentOperations: 2 **Recommended specifications:** * **CPU:** 4 cores * **RAM:** 8GB * **Disk:** 50GB * **Concurrent operations:** 4-8 **Docker resource limits:** deploy: resources: limits: memory: 8G cpus: '4.0' reservations: memory: 4G cpus: '2.0' **Settings:** system: maxFileSize: 1000 # 1GB max file connectionTimeoutMinutes: 10 maxConcurrentOperations: 4 **Consider:** * Load balancer for multiple instances * Database on separate server **Recommended specifications:** * **CPU:** 8+ cores * **RAM:** 16GB+ * **Disk:** 100GB+ (SSD recommended) * **Concurrent operations:** 8+ **Docker resource limits:** deploy: resources: limits: memory: 16G cpus: '8.0' reservations: memory: 8G cpus: '4.0' **Settings:** system: maxFileSize: 2000 # 2GB max file connectionTimeoutMinutes: 15 maxConcurrentOperations: 8 **Architecture:** * Multiple instances for processing * Load balancer with session affinity * Dedicated database server * Redis for session storage Server/Enterprise Recommended For large organizations, **Server or Enterprise plans** provide: * Advanced load balancing * High availability configuration * Database clustering * Performance monitoring * Dedicated support [Learn more](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-10-paid-plans-serverenterprise) ### 9.2: Storage Management[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#92-storage-management "Direct link to 9.2: Storage Management") **Monitor disk usage:** # Check Docker disk usagedocker system df# Check Stirling-PDF data usagedu -sh ./stirling-data/* **Cleanup strategies:** system: # Automatic cleanup settings tempFileCleanup: true tempFileMaxAge: 24 # hours # Log rotation logRetentionDays: 30 maxLogSize: 100 # MB **Manual cleanup:** # Clean Docker systemdocker system prune -a --volumes# Clean old logsfind ./stirling-data/logs -name "*.log" -mtime +30 -delete# Clean temporary files (if not auto-cleaned)find ./stirling-data/temp -type f -mtime +1 -delete * * * Step 10: Paid Plans (Server/Enterprise)[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-10-paid-plans-serverenterprise "Direct link to Step 10: Paid Plans (Server/Enterprise)") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Stirling-PDF offers **Server and Enterprise paid plans** with additional features for organizations. ### Key Paid Plan Features[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#key-paid-plan-features "Direct link to Key Paid Plan Features") **Authentication & Security:** * **OAuth2 SSO:** Server tier (Google, GitHub, Keycloak, OIDC) * **SAML2 SSO:** Enterprise tier (Okta, Azure AD, etc.) * Enhanced security features **Database & Infrastructure:** * **External PostgreSQL Database:** Available for Server/Enterprise deployments * Better reliability and scalability than local H2 database * Professional backup and replication strategies **Monitoring & Analytics:** * **Prometheus Integration:** Advanced metrics and monitoring * **Usage Dashboard:** Graphical usage statistics at `/usage` * Enhanced monitoring APIs **For pricing and enterprise inquiries:** * **Email:** [support@stirlingtools.com](mailto:support@stirlingtools.com) * **Website:** [https://stirlingtools.com/pricing](https://stirlingtools.com/pricing) * **Documentation:** [Paid Offerings](https://docs.stirlingpdf.com/Paid-Offerings) * **External Database Setup:** [External Database Guide](https://docs.stirlingpdf.com/Configuration/External%20Database) * **Monitoring Setup:** [Usage Monitoring](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) * * * Next Steps & Resources[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#next-steps--resources "Direct link to Next Steps & Resources") -------------------------------------------------------------------------------------------------------------------------------------------------- Congratulations! You've successfully deployed and configured Stirling-PDF for your organization. ### Recommended Next Steps[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#recommended-next-steps "Direct link to Recommended Next Steps") 1. **📚 Train your users** * Share the [Getting Started Guide](https://docs.stirlingpdf.com/) * Point them to [Tool Reference](https://docs.stirlingpdf.com/functionality) * Create internal documentation for your specific workflows 2. **🔧 Advanced configuration** * [OCR Configuration](https://docs.stirlingpdf.com/Configuration/OCR) - Add more languages * [Pipeline Automation](https://docs.stirlingpdf.com/Configuration/Pipeline) - Automate workflows * [API Integration](https://docs.stirlingpdf.com/API) - Integrate with other systems 3. **🔒 Harden security** * [Fail2Ban Setup](https://docs.stirlingpdf.com/Configuration/fail2ban) - Prevent brute force * [External Database](https://docs.stirlingpdf.com/Configuration/External%20Database) - Use PostgreSQL * Review [System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) settings 4. **📊 Monitor and optimize** * Set up regular backup verification * Review logs weekly * Monitor disk space and performance * Plan for growth ### Support & Community[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#support--community "Direct link to Support & Community") * **Documentation:** [https://docs.stirlingpdf.com](https://docs.stirlingpdf.com/) * **GitHub:** [https://github.com/Stirling-Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF) * **Discord:** [https://discord.gg/Cn8pWhQRxZ](https://discord.gg/Cn8pWhQRxZ) * **Issue Tracker:** [https://github.com/Stirling-Tools/Stirling-PDF/issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) ### Stay Updated[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#stay-updated "Direct link to Stay Updated") * **Release Notes:** [https://github.com/Stirling-Tools/Stirling-PDF/releases](https://github.com/Stirling-Tools/Stirling-PDF/releases) * **Blog:** [https://stirlingtools.com/blog](https://stirlingtools.com/blog) * **Newsletter:** Subscribe at [https://stirlingtools.com](https://stirlingtools.com/) * * * Troubleshooting Common Issues[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#troubleshooting-common-issues "Direct link to Troubleshooting Common Issues") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### Authentication Issues[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#authentication-issues "Direct link to Authentication Issues") **Problem:** Can't log in as admin **Solutions:** 1. Check logs: `docker logs stirling-pdf | grep ERROR` 2. Verify `SECURITY_ENABLELOGIN=true` is set 3. Reset admin password via command line: docker exec -it stirling-pdf sh# Use built-in password reset tool ### Performance Issues[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#performance-issues "Direct link to Performance Issues") **Problem:** Slow processing, timeouts **Solutions:** 1. Check resource limits: `docker stats stirling-pdf` 2. Increase memory: Update `deploy.resources.limits.memory` 3. Reduce concurrent operations: Lower `maxConcurrentOperations` 4. Check disk I/O: Use SSD for better performance ### HTTPS/Certificate Issues[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#httpscertificate-issues "Direct link to HTTPS/Certificate Issues") **Problem:** Certificate errors, HTTPS not working **Solutions:** 1. Check Nginx/Traefik logs 2. Verify DNS points to correct IP 3. Ensure ports 80 and 443 are open 4. Test Let's Encrypt manually: `sudo certbot certificates` ### File Upload Issues[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#file-upload-issues "Direct link to File Upload Issues") **Problem:** Can't upload large files **Solutions:** 1. Increase Nginx limit: `client_max_body_size 2000M;` 2. Increase Stirling-PDF limit: `system.maxFileSize: 2000` 3. Check disk space: `df -h` 4. Increase timeouts: `client_body_timeout 300s;` ### Need More Help?[​](https://docs.stirlingpdf.com/Production-Deployment-Guide#need-more-help "Direct link to Need More Help?") **For Community Support:** * Join Discord: [https://discord.gg/Cn8pWhQRxZ](https://discord.gg/Cn8pWhQRxZ) * Search GitHub Issues: [https://github.com/Stirling-Tools/Stirling-PDF/issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) **For Priority Support:** * Upgrade to Server or Enterprise plan * Email: [support@stirlingtools.com](mailto:support@stirlingtools.com) * Get dedicated support team * * * **You're all set!** 🎉 Your Stirling-PDF deployment is ready for production use. If you have any questions or need assistance, don't hesitate to reach out to our community or consider upgrading to a paid plan (Server or Enterprise) for dedicated support. Happy PDF processing! 📄✨ * [Overview: What You'll Accomplish](https://docs.stirlingpdf.com/Production-Deployment-Guide#overview-what-youll-accomplish) * [Step 1: Choose Your Deployment Path](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-1-choose-your-deployment-path) * [Step 2: Installation](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-2-installation) * [Docker Compose Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-compose-setup) * [Docker Run Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#docker-run-setup) * [Kubernetes Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#kubernetes-setup) * [Bare Metal Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#bare-metal-setup) * [Step 3: Initial Login & Admin Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-3-initial-login--admin-setup) * [3.1: First-Time Login](https://docs.stirlingpdf.com/Production-Deployment-Guide#31-first-time-login) * [3.2: Verify Admin Access](https://docs.stirlingpdf.com/Production-Deployment-Guide#32-verify-admin-access) * [Step 4: Configure Essential Settings](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-4-configure-essential-settings) * [4.1: General Settings](https://docs.stirlingpdf.com/Production-Deployment-Guide#41-general-settings) * [4.2: Security Settings](https://docs.stirlingpdf.com/Production-Deployment-Guide#42-security-settings) * [4.3: Feature Control](https://docs.stirlingpdf.com/Production-Deployment-Guide#43-feature-control) * [4.4: Save and Apply Settings](https://docs.stirlingpdf.com/Production-Deployment-Guide#44-save-and-apply-settings) * [Step 5: HTTPS & Domain Setup](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-5-https--domain-setup) * [5.1: Choose Your HTTPS Method](https://docs.stirlingpdf.com/Production-Deployment-Guide#51-choose-your-https-method) * [5.2: Update Stirling-PDF Configuration](https://docs.stirlingpdf.com/Production-Deployment-Guide#52-update-stirling-pdf-configuration) * [Step 6: User Management](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-6-user-management) * [6.1: Understanding User Roles](https://docs.stirlingpdf.com/Production-Deployment-Guide#61-understanding-user-roles) * [6.2: Adding Users](https://docs.stirlingpdf.com/Production-Deployment-Guide#62-adding-users) * [6.3: User Management Tasks](https://docs.stirlingpdf.com/Production-Deployment-Guide#63-user-management-tasks) * [Step 7: Monitoring & Usage Tracking](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-7-monitoring--usage-tracking) * [7.1: Basic Monitoring](https://docs.stirlingpdf.com/Production-Deployment-Guide#71-basic-monitoring) * [7.2: Set Up Monitoring](https://docs.stirlingpdf.com/Production-Deployment-Guide#72-set-up-monitoring) * [Step 8: Backup & Disaster Recovery](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-8-backup--disaster-recovery) * [8.1: What to Backup](https://docs.stirlingpdf.com/Production-Deployment-Guide#81-what-to-backup) * [8.2: Backup Strategies](https://docs.stirlingpdf.com/Production-Deployment-Guide#82-backup-strategies) * [8.3: Restore from Backup](https://docs.stirlingpdf.com/Production-Deployment-Guide#83-restore-from-backup) * [Step 9: Performance Optimization](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-9-performance-optimization) * [9.1: Resource Allocation](https://docs.stirlingpdf.com/Production-Deployment-Guide#91-resource-allocation) * [9.2: Storage Management](https://docs.stirlingpdf.com/Production-Deployment-Guide#92-storage-management) * [Step 10: Paid Plans (Server/Enterprise)](https://docs.stirlingpdf.com/Production-Deployment-Guide#step-10-paid-plans-serverenterprise) * [Key Paid Plan Features](https://docs.stirlingpdf.com/Production-Deployment-Guide#key-paid-plan-features) * [Next Steps & Resources](https://docs.stirlingpdf.com/Production-Deployment-Guide#next-steps--resources) * [Recommended Next Steps](https://docs.stirlingpdf.com/Production-Deployment-Guide#recommended-next-steps) * [Support & Community](https://docs.stirlingpdf.com/Production-Deployment-Guide#support--community) * [Stay Updated](https://docs.stirlingpdf.com/Production-Deployment-Guide#stay-updated) * [Troubleshooting Common Issues](https://docs.stirlingpdf.com/Production-Deployment-Guide#troubleshooting-common-issues) * [Authentication Issues](https://docs.stirlingpdf.com/Production-Deployment-Guide#authentication-issues) * [Performance Issues](https://docs.stirlingpdf.com/Production-Deployment-Guide#performance-issues) * [HTTPS/Certificate Issues](https://docs.stirlingpdf.com/Production-Deployment-Guide#httpscertificate-issues) * [File Upload Issues](https://docs.stirlingpdf.com/Production-Deployment-Guide#file-upload-issues) * [Need More Help?](https://docs.stirlingpdf.com/Production-Deployment-Guide#need-more-help) --- # Contribution guidelines | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Contribute#__docusaurus_skipToContent_fallback) On this page Thanks for taking a look at how to contribute to Stirling PDFs open-source codebase! Development Setup[​](https://docs.stirlingpdf.com/Contribute#development-setup "Direct link to Development Setup") ------------------------------------------------------------------------------------------------------------------- ### Prerequisites[​](https://docs.stirlingpdf.com/Contribute#prerequisites "Direct link to Prerequisites") * Java 21 or later * Node.js 18+ * Docker (for testing) * Gradle (included in repository) ### Getting Started[​](https://docs.stirlingpdf.com/Contribute#getting-started "Direct link to Getting Started") 1. **Clone the repository** git clone https://github.com/Stirling-Tools/Stirling-PDF.gitcd Stirling-PDF 2. **Backend Development** # Build and run the Spring Boot backend./gradlew bootRun# Backend runs on localhost:8080 3. **Frontend Development (V2.0+)** # Navigate to frontend directorycd frontend# Install dependenciesnpm install# Run development servernpm run dev# Frontend runs on localhost:5173, proxies API calls to backend (localhost:8080) Contributing to Code[​](https://docs.stirlingpdf.com/Contribute#contributing-to-code "Direct link to Contributing to Code") ---------------------------------------------------------------------------------------------------------------------------- ### Backend Contributions[​](https://docs.stirlingpdf.com/Contribute#backend-contributions "Direct link to Backend Contributions") * See our [CONTRIBUTING guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) * Backend uses Spring Boot + Java * Code formatting: Run `./gradlew spotlessApply` before committing ### Frontend Contributions (V2.0+)[​](https://docs.stirlingpdf.com/Contribute#frontend-contributions-v20 "Direct link to Frontend Contributions (V2.0+)") * Frontend is a React + TypeScript application * Uses Vite for build tooling * UI components: Mantine UI + TailwindCSS * Adding new tools: See [ADDING\_TOOLS.md](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/ADDING_TOOLS.md) * Tool architecture: Uses `useToolOperation` hook pattern Translation Contributions[​](https://docs.stirlingpdf.com/Contribute#translation-contributions "Direct link to Translation Contributions") ------------------------------------------------------------------------------------------------------------------------------------------- ### V2.0 Translations (JSON)[​](https://docs.stirlingpdf.com/Contribute#v20-translations-json "Direct link to V2.0 Translations (JSON)") Translation files are located in `frontend/public/locales/` * **CRITICAL**: Always update translations in `en-GB` only, never `en-US` * Files are organized by feature (e.g., `common.json`, `tools.json`) * Use standard JSON format Development Resources[​](https://docs.stirlingpdf.com/Contribute#development-resources "Direct link to Development Resources") ------------------------------------------------------------------------------------------------------------------------------- * **API Documentation**: Access at `/swagger-ui/index.html` on your local instance * **Developer Guide**: See `DeveloperGuide.md` in the repository * **Claude Code Guide**: See `CLAUDE.md` for detailed architecture and patterns * [Development Setup](https://docs.stirlingpdf.com/Contribute#development-setup) * [Prerequisites](https://docs.stirlingpdf.com/Contribute#prerequisites) * [Getting Started](https://docs.stirlingpdf.com/Contribute#getting-started) * [Contributing to Code](https://docs.stirlingpdf.com/Contribute#contributing-to-code) * [Backend Contributions](https://docs.stirlingpdf.com/Contribute#backend-contributions) * [Frontend Contributions (V2.0+)](https://docs.stirlingpdf.com/Contribute#frontend-contributions-v20) * [Translation Contributions](https://docs.stirlingpdf.com/Contribute#translation-contributions) * [V2.0 Translations (JSON)](https://docs.stirlingpdf.com/Contribute#v20-translations-json) * [Development Resources](https://docs.stirlingpdf.com/Contribute#development-resources) --- # FAQ | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/FAQ#__docusaurus_skipToContent_fallback) On this page ### Q1: Why are .htm files being downloaded when I use the application?[​](https://docs.stirlingpdf.com/FAQ#q1-why-are-htm-files-being-downloaded-when-i-use-the-application "Direct link to Q1: Why are .htm files being downloaded when I use the application?") This is often caused by your NGINX configuration. NGINX's default file upload size is 1MB, and any file larger than this will cause an .htm file to be downloaded instead. To fix this issue, you should modify your NGINX configuration to increase the maximum file upload size. ### Q2: Can I customize the appearance and language of the Stirling PDF application?[​](https://docs.stirlingpdf.com/FAQ#q2-can-i-customize-the-appearance-and-language-of-the-stirling-pdf-application "Direct link to Q2: Can I customize the appearance and language of the Stirling PDF application?") Yes, Stirling PDF provides several environment variables to allow customization of the application, custom HTML, CSS and other settings such as the visibility to search engines. Please refer to the [UI Customisation](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) section for more details. ### Q3: I want to add a new feature to Stirling PDF. How can I contribute?[​](https://docs.stirlingpdf.com/FAQ#q3-i-want-to-add-a-new-feature-to-stirling-pdf-how-can-i-contribute "Direct link to Q3: I want to add a new feature to Stirling PDF. How can I contribute?") We welcome contributions from the community! Please open an issue on our GitHub page to discuss any large features before making any changes. Any small changes are fully welcome without discussion! After the feature has been discussed and approved, you can make the changes and submit a pull request. ### Q4: I have a cool idea can you add it?[​](https://docs.stirlingpdf.com/FAQ#q4-i-have-a-cool-idea-can-you-add-it "Direct link to Q4: I have a cool idea can you add it?") All feedback and suggestions are appreciated. It is best to submit these via a Github issue ticket with \[Feature Request\] in the title. You can also reach out in discord but without a ticket to track it the request can often get lost! ### Q5: I found a bug in Stirling PDF. Where can I report it?[​](https://docs.stirlingpdf.com/FAQ#q5-i-found-a-bug-in-stirling-pdf-where-can-i-report-it "Direct link to Q5: I found a bug in Stirling PDF. Where can I report it?") Please report any bugs or issues you encounter through our GitHub Issues page. Be sure to include as much detail as possible so we can diagnose and resolve the issue quickly. ### Q6: My Stirling PDF Using high RAM at idle, How can I optimize memory usage?[​](https://docs.stirlingpdf.com/FAQ#q6-my-stirling-pdf-using-high-ram-at-idle-how-can-i-optimize-memory-usage "Direct link to Q6: My Stirling PDF Using high RAM at idle, How can I optimize memory usage?") Stirling PDF's memory usage can be optimized in several ways: Disable additional features: Set DISABLE\_ADDITIONAL\_FEATURES=true to reduce RAM consumption. This can significantly lower memory usage, especially during idle periods. Use the Ultra Lite version: Pull the latest-ultra-lite tag from Docker Hub or GitHub, which is specifically designed for lower-end hardware. ### Q7: I'm experiencing connection errors when pulling from docker.stirling.com[​](https://docs.stirlingpdf.com/FAQ#q7-im-experiencing-connection-errors-when-pulling-from-dockerstirlingcom "Direct link to Q7: I'm experiencing connection errors when pulling from docker.stirling.com") If you experience connection issues, use these alternative endpoints: * Docker Hub: `docker pull stirlingtools/stirling-pdf:latest` * GitHub: `docker pull ghcr.io/stirling-tools/stirling-pdf:latest` All endpoints provide the same functionality. ### Q8: Does Stirling PDF track my data?[​](https://docs.stirlingpdf.com/FAQ#q8-does-stirling-pdf-track-my-data "Direct link to Q8: Does Stirling PDF track my data?") No, we track no data without your explicit consent. You can see how, when, and why at our [Analytics and Telemetry](https://docs.stirlingpdf.com/analytics-telemetry) page. ### Q9: When I upload a file, where is it processed?[​](https://docs.stirlingpdf.com/FAQ#q9-when-i-upload-a-file-where-is-it-processed "Direct link to Q9: When I upload a file, where is it processed?") Uploads go to the server or desktop instance you're using, not to Stirling servers. The macOS/Windows desktop apps process files locally - even when you pick the Stirling Cloud sign-in today - so your PDFs stay on your device unless you point the app to a remote self-hosted server. Planned SaaS-assisted features (for desktop app) will be opt-in when they arrive. ### Q10: What are the different JAR files and which should I use?[​](https://docs.stirlingpdf.com/FAQ#q10-what-are-the-different-jar-files-and-which-should-i-use "Direct link to Q10: What are the different JAR files and which should I use?") Stirling PDF comes in three different JAR files: **Stirling-PDF-with-login.jar** (Recommended - Full Features): * Bundles frontend UI + backend server * **Includes authentication and additional features** - requires user login * **Recommended for all users** - personal, shared, or enterprise deployments **Stirling-PDF.jar** (Plain JAR - Basic Features): * Bundles frontend UI + backend server * **Basic version** - no authentication, core features only * Only use if you require no login at all and don't mind missing certain features **Stirling-PDF-server.jar** (Backend Only - **Advanced**): * Backend server only (no bundled frontend UI) * **No authentication** - API access only * Use for API access, desktop app backend, or custom frontend ### Q11: How do I enable or disable authentication?[​](https://docs.stirlingpdf.com/FAQ#q11-how-do-i-enable-or-disable-authentication "Direct link to Q11: How do I enable or disable authentication?") **Default JAR (Stirling-PDF.jar)**: Authentication is **not available** (security module not included at build time). **With-Login JAR (Stirling-PDF-with-login.jar)**: Authentication is **enabled by default**. To disable authentication in the with-login version: * Settings File * Docker Run * Docker Compose * JAR (Java Property) * JAR (Environment Variable) security: enableLogin: false docker run -d \ -p 8080:8080 \ -e SECURITY_ENABLELOGIN=false \ stirlingtools/stirling-pdf:latest environment: SECURITY_ENABLELOGIN: false java -jar Stirling-PDF.jar -DSECURITY_ENABLELOGIN=false export SECURITY_ENABLELOGIN=falsejava -jar Stirling-PDF.jar For more details, see the [System and Security Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#running-without-authentication) documentation. * [Q1: Why are .htm files being downloaded when I use the application?](https://docs.stirlingpdf.com/FAQ#q1-why-are-htm-files-being-downloaded-when-i-use-the-application) * [Q2: Can I customize the appearance and language of the Stirling PDF application?](https://docs.stirlingpdf.com/FAQ#q2-can-i-customize-the-appearance-and-language-of-the-stirling-pdf-application) * [Q3: I want to add a new feature to Stirling PDF. How can I contribute?](https://docs.stirlingpdf.com/FAQ#q3-i-want-to-add-a-new-feature-to-stirling-pdf-how-can-i-contribute) * [Q4: I have a cool idea can you add it?](https://docs.stirlingpdf.com/FAQ#q4-i-have-a-cool-idea-can-you-add-it) * [Q5: I found a bug in Stirling PDF. Where can I report it?](https://docs.stirlingpdf.com/FAQ#q5-i-found-a-bug-in-stirling-pdf-where-can-i-report-it) * [Q6: My Stirling PDF Using high RAM at idle, How can I optimize memory usage?](https://docs.stirlingpdf.com/FAQ#q6-my-stirling-pdf-using-high-ram-at-idle-how-can-i-optimize-memory-usage) * [Q7: I'm experiencing connection errors when pulling from docker.stirling.com](https://docs.stirlingpdf.com/FAQ#q7-im-experiencing-connection-errors-when-pulling-from-dockerstirlingcom) * [Q8: Does Stirling PDF track my data?](https://docs.stirlingpdf.com/FAQ#q8-does-stirling-pdf-track-my-data) * [Q9: When I upload a file, where is it processed?](https://docs.stirlingpdf.com/FAQ#q9-when-i-upload-a-file-where-is-it-processed) * [Q10: What are the different JAR files and which should I use?](https://docs.stirlingpdf.com/FAQ#q10-what-are-the-different-jar-files-and-which-should-i-use) * [Q11: How do I enable or disable authentication?](https://docs.stirlingpdf.com/FAQ#q11-how-do-i-enable-or-disable-authentication) --- # Analytics and Telemetry | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/analytics-telemetry#__docusaurus_skipToContent_fallback) On this page > Please note all the following applies to version 1.5.0 onward due to be released 16th October Stirling‑PDF uses analytics to understand usage patterns and improve the application. This page explains what data is collected, why we collect it, and how to disable analytics if desired. > **User control**: All analytics are **opt‑in via a consent banner** (Disabled untill a user expressly allows it) a self‑hosted administrator can also disables all analytics system‑wide. If analytics are disabled system‑wide, no banner is shown. Overview[​](https://docs.stirlingpdf.com/analytics-telemetry#overview "Direct link to Overview") ------------------------------------------------------------------------------------------------- Stirling‑PDF uses two analytics services: 1. **[Scarf](https://scarf.sh/) ** - a privacy‑friendly tool designed for open‑source projects. 2. **[PostHog](https://posthog.com/) ** - an open‑source product analytics platform for detailed usage insights. Both services are designed with privacy in mind and can be completely disabled. * * * PostHog Analytics[​](https://docs.stirlingpdf.com/analytics-telemetry#posthog-analytics "Direct link to PostHog Analytics") ---------------------------------------------------------------------------------------------------------------------------- ### What is PostHog?[​](https://docs.stirlingpdf.com/analytics-telemetry#what-is-posthog "Direct link to What is PostHog?") PostHog is an open‑source product analytics platform that provides detailed insights into how users interact with Stirling‑PDF. It's hosted on PostHog's European servers (`eu.i.posthog.com`) for GDPR alignment. ### Data collected by PostHog[​](https://docs.stirlingpdf.com/analytics-telemetry#data-collected-by-posthog "Direct link to Data collected by PostHog") PostHog collects comprehensive system and usage information **only when analytics are enabled and consented**: #### System information[​](https://docs.stirlingpdf.com/analytics-telemetry#system-information "Direct link to System information") * Operating system name and version * Java version and vendor * CPU cores and memory allocation * Deployment type (Docker, JAR, EXE) * Docker/Kubernetes environment details (if applicable) * Timezone and locale settings #### Application configuration[​](https://docs.stirlingpdf.com/analytics-telemetry#application-configuration "Direct link to Application configuration") * Security settings (login enabled, OAuth/SAML configuration status) * UI customization settings * Feature flags and enabled functionality * Legal document URLs (terms, privacy policy, etc.) * System limits and quotas #### Usage data[​](https://docs.stirlingpdf.com/analytics-telemetry#usage-data "Direct link to Usage data") * Aggregate counts (e.g., total number of user accounts created) * Feature/tool usage (which tools/operations are used) * Error tracking * Browser and device information (for the web interface) **Important privacy notes**: * **No document content, PDF data, or file metadata is ever collected or transmitted.** * PostHog is configured with: * `opt_out_capturing_by_default: true` * `mask_all_text: true` * `mask_all_element_attributes: true` * Users must accept cookies before any data is captured. * Data is stored on EU servers. * Each instance has a unique UUID (not tied to individuals). ### Why we use PostHog[​](https://docs.stirlingpdf.com/analytics-telemetry#why-we-use-posthog "Direct link to Why we use PostHog") PostHog analytics help us: * Understand which features are most valuable * Identify and fix bugs proactively * Improve user experience based on actual usage patterns * Prioritize feature development * Ensure compatibility across different environments * Monitor application health and performance * * * Scarf[​](https://docs.stirlingpdf.com/analytics-telemetry#scarf "Direct link to Scarf") ---------------------------------------------------------------------------------------- ### What is Scarf?[​](https://docs.stirlingpdf.com/analytics-telemetry#what-is-scarf "Direct link to What is Scarf?") [Scarf](https://scarf.sh/) provides a simple tracking pixel (`pixel.stirling.com`) that collects basic, non‑personally identifiable information about Stirling‑PDF usage. ### Data collected by Scarf[​](https://docs.stirlingpdf.com/analytics-telemetry#data-collected-by-scarf "Direct link to Data collected by Scarf") The Scarf pixel collects the following information: * **Machine Type**: Deployment type (Docker, JAR, or EXE) * **App Version**: The version of Stirling‑PDF you're running * **License Type**: Whether you're using Community or Enterprise edition * **Login Enabled**: Whether authentication is enabled * **Page Endpoint Loaded**: Which Stirling‑PDF page was loaded (e.g., `/split-pdf`) **Important**: The Scarf pixel does **not** collect or store: * Personal information (PII) * IP addresses (IP addresses are not stored) * User‑specific identifiers * Document content or file metadata * Fine‑grained user behavior beyond which page/endpoint was loaded ### Why we use Scarf[​](https://docs.stirlingpdf.com/analytics-telemetry#why-we-use-scarf "Direct link to Why we use Scarf") Scarf helps us understand: * Which deployment types are most common * Version adoption rates * Which pages/tools are reached across different configurations This data helps prioritize development efforts and ensure compatibility across deployment scenarios. ### How to disable Scarf[​](https://docs.stirlingpdf.com/analytics-telemetry#how-to-disable-scarf "Direct link to How to disable Scarf") Scarf is opt‑in by default (via the cookie consent banner). To disable the Scarf tracking pixel **system‑wide** and suppress the banner for it: **Environment variable** SYSTEM_ENABLESCARF=false **settings.yml** system: enableScarf: false * * * Configuration and Control[​](https://docs.stirlingpdf.com/analytics-telemetry#configuration-and-control "Direct link to Configuration and Control") ---------------------------------------------------------------------------------------------------------------------------------------------------- Analytics are governed by a **global master toggle**, **component toggles**, and the **cookie consent banner**. ### 1) Global analytics toggle (master switch)[​](https://docs.stirlingpdf.com/analytics-telemetry#1-global-analytics-toggle-master-switch "Direct link to 1) Global analytics toggle (master switch)") Controls **all** analytics and whether a consent banner appears. * Settings File * Environment Variable * Docker Compose system: enableAnalytics: false # true | false | null (unset) SYSTEM_ENABLEANALYTICS=false # true | false | (unset = null) services: stirling-pdf: environment: SYSTEM_ENABLEANALYTICS: false **Behavior** * `false`: Disables **all** analytics (no consent banner; PostHog & Scarf are off). * `true`: Allows analytics (banner still required for user consent before any capture). * `null`/unset: **First‑run admin choice** - on the first ever connection to a self‑hosted instance, the first visitor (assumed admin) is prompted to choose, and that choice sets the global behavior for all users (either disabling analytics or enabling the consent banner for others). ### 2) Component toggles[​](https://docs.stirlingpdf.com/analytics-telemetry#2-component-toggles "Direct link to 2) Component toggles") Use these to selectively enable/disable providers **in addition** to the global toggle. **PostHog:** * Settings File * Environment Variable system: enablePosthog: false # true | false | null SYSTEM_ENABLEPOSTHOG=false **Scarf tracking pixel:** * Settings File * Environment Variable system: enableScarf: false # true | false | null SYSTEM_ENABLESCARF=false **Interaction** * If `enableAnalytics` is `false`, everything is off regardless of component toggles. * If `enableAnalytics` is `true`/`null`, the consent banner is shown (see below). After consent: * PostHog runs only if `enablePosthog` is `true`/`null` **and** the user consented. * Scarf runs only if `enableScarf` is `true`/`null` **and** the user consented. ### 3) Cookie consent banner[​](https://docs.stirlingpdf.com/analytics-telemetry#3-cookie-consent-banner "Direct link to 3) Cookie consent banner") When analytics are allowed globally (`system.enableAnalytics: true` or resolved via the first‑run admin choice), users see a cookie consent banner on their first visit. Users can: * **Accept all** → enables PostHog (if `enablePosthog` is `true`/`null`) and Scarf (if `enableScarf` is `true`/`null`) * **Accept only necessary** → disables PostHog and Scarf * **Customize** → granular selection where applicable **User control details** * Users can change preferences at any time. * Consent choices are stored locally in the user's browser. * PostHog and Scarf respect the consent decision immediately. * No tracking occurs until explicit consent is given. * * * Complete analytics disable (shortcut)[​](https://docs.stirlingpdf.com/analytics-telemetry#complete-analytics-disable-shortcut "Direct link to Complete analytics disable (shortcut)") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you want to disable **all** analytics and telemetry (and suppress any consent prompts) at once: * Settings File * Environment Variable * Docker Compose system: enableAnalytics: false SYSTEM_ENABLEANALYTICS=false services: stirling-pdf: environment: SYSTEM_ENABLEANALYTICS: false * * * Privacy and Data Security[​](https://docs.stirlingpdf.com/analytics-telemetry#privacy-and-data-security "Direct link to Privacy and Data Security") ---------------------------------------------------------------------------------------------------------------------------------------------------- ### Data retention[​](https://docs.stirlingpdf.com/analytics-telemetry#data-retention "Direct link to Data retention") * PostHog data is retained according to PostHog’s configured retention policies. * Scarf pixel data is aggregated and anonymized. * No personal documents or content are ever transmitted. ### GDPR alignment[​](https://docs.stirlingpdf.com/analytics-telemetry#gdpr-alignment "Direct link to GDPR alignment") * PostHog servers are located in the EU. * Cookie consent is required before tracking. * Users can opt out at any time. * No cross‑site tracking or fingerprinting. * Text and element masking helps prevent accidental PII collection. ### Transparency[​](https://docs.stirlingpdf.com/analytics-telemetry#transparency "Direct link to Transparency") * All analytics‑related code is open source and visible in the repository. * Analytics can be completely disabled with simple configuration changes. * Users have full control over their data via cookie preferences (when analytics are allowed globally). * * * For Self‑Hosted Instances[​](https://docs.stirlingpdf.com/analytics-telemetry#for-selfhosted-instances "Direct link to For Self‑Hosted Instances") --------------------------------------------------------------------------------------------------------------------------------------------------- If you're running Stirling‑PDF on your own infrastructure: 1. **Private networks**: Analytics from self‑hosted instances help us understand deployment patterns but don't expose your internal network. 2. **Air‑gapped environments**: Disable analytics; the application works perfectly without external connections. 3. **Corporate environments**: Disable analytics if your security policy requires it, or allow it to help improve the product. * * * Support[​](https://docs.stirlingpdf.com/analytics-telemetry#support "Direct link to Support") ---------------------------------------------------------------------------------------------- If you have questions or concerns about analytics: * Check our [Privacy Policy](https://www.stirling.com/privacy-policy) * Review the [source code](https://github.com/Stirling-Tools/Stirling-PDF) * Ask questions on [Discord](https://discord.gg/HYmhKj45pU) * Open an issue on [GitHub](https://github.com/Stirling-Tools/Stirling-PDF/issues) * [Overview](https://docs.stirlingpdf.com/analytics-telemetry#overview) * [PostHog Analytics](https://docs.stirlingpdf.com/analytics-telemetry#posthog-analytics) * [What is PostHog?](https://docs.stirlingpdf.com/analytics-telemetry#what-is-posthog) * [Data collected by PostHog](https://docs.stirlingpdf.com/analytics-telemetry#data-collected-by-posthog) * [Why we use PostHog](https://docs.stirlingpdf.com/analytics-telemetry#why-we-use-posthog) * [Scarf](https://docs.stirlingpdf.com/analytics-telemetry#scarf) * [What is Scarf?](https://docs.stirlingpdf.com/analytics-telemetry#what-is-scarf) * [Data collected by Scarf](https://docs.stirlingpdf.com/analytics-telemetry#data-collected-by-scarf) * [Why we use Scarf](https://docs.stirlingpdf.com/analytics-telemetry#why-we-use-scarf) * [How to disable Scarf](https://docs.stirlingpdf.com/analytics-telemetry#how-to-disable-scarf) * [Configuration and Control](https://docs.stirlingpdf.com/analytics-telemetry#configuration-and-control) * [1) Global analytics toggle (master switch)](https://docs.stirlingpdf.com/analytics-telemetry#1-global-analytics-toggle-master-switch) * [2) Component toggles](https://docs.stirlingpdf.com/analytics-telemetry#2-component-toggles) * [3) Cookie consent banner](https://docs.stirlingpdf.com/analytics-telemetry#3-cookie-consent-banner) * [Complete analytics disable (shortcut)](https://docs.stirlingpdf.com/analytics-telemetry#complete-analytics-disable-shortcut) * [Privacy and Data Security](https://docs.stirlingpdf.com/analytics-telemetry#privacy-and-data-security) * [Data retention](https://docs.stirlingpdf.com/analytics-telemetry#data-retention) * [GDPR alignment](https://docs.stirlingpdf.com/analytics-telemetry#gdpr-alignment) * [Transparency](https://docs.stirlingpdf.com/analytics-telemetry#transparency) * [For Self‑Hosted Instances](https://docs.stirlingpdf.com/analytics-telemetry#for-selfhosted-instances) * [Support](https://docs.stirlingpdf.com/analytics-telemetry#support) --- # Custom Settings Configuration | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Extra-Settings#__docusaurus_skipToContent_fallback) On this page Stirling PDF provides a `/configs/custom_settings.yml` file where users can configure additional settings beyond the standard configuration. This file follows standard YAML format and supports Spring Boot application properties, allowing you to customize the application without modifying core files. Logging Configuration[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#logging-configuration "Direct link to Logging Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------- Control the verbosity of logs by adjusting log levels for different components: logging: level: root: INFO org.springframework: WARN org.hibernate: WARN org.eclipse.jetty: WARN stirling.software.SPDF: INFO # Enable debug logging for specific components when troubleshooting # org.springframework.security.saml2: TRACE # org.springframework.security: DEBUG # org.opensaml: DEBUG Server Configuration[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#server-configuration "Direct link to Server Configuration") ---------------------------------------------------------------------------------------------------------------------------------------------- Configure server behavior including port, address binding, and session timeout: server: port: 8080 # Default port address: 0.0.0.0 # Bind to all interfaces servlet: context-path: / # Application context path session: timeout: 30m # Session timeout jetty: threads: max: 200 # Maximum number of request processing threads min: 10 # Minimum number of threads always kept running connection-idle-timeout: 30000 # Connection idle timeout in milliseconds SSL/TLS Configuration[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#ssltls-configuration "Direct link to SSL/TLS Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------ Configure HTTPS for secure connections: * Settings File * Environment Variable * Docker Compose server: port: 8443 # Standard HTTPS port ssl: enabled: true key-store: classpath:keystore.p12 # Path to keystore file key-store-password: your-keystore-password key-store-type: PKCS12 # Type of keystore key-alias: tomcat # Alias of the certificate SERVER_PORT=8443SERVER_SSL_ENABLED=trueSERVER_SSL_KEY-STORE=classpath:keystore.p12SERVER_SSL_KEY-STORE-PASSWORD=your-keystore-passwordSERVER_SSL_KEY-STORE-TYPE=PKCS12SERVER_SSL_KEY-ALIAS=tomcat 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 ### Creating a Self-Signed Certificate[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#creating-a-self-signed-certificate "Direct link to Creating a Self-Signed Certificate") To generate a self-signed certificate for development or testing: keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 365 > #### ⚠️ Note[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _For production use, it's recommended to use a certificate from a trusted Certificate Authority._ Configuration Examples[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#configuration-examples "Direct link to Configuration Examples") ---------------------------------------------------------------------------------------------------------------------------------------------------- ### Basic Configuration[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#basic-configuration "Direct link to Basic Configuration") A simple configuration that changes the port and adjusts logging levels: # custom_settings.ymlserver: port: 9000logging: level: root: INFO org.springframework: WARN org.hibernate: WARN stirling.software.SPDF: INFO ### HTTPS Configuration[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#https-configuration "Direct link to HTTPS Configuration") Enable HTTPS with a custom certificate: # custom_settings.ymlserver: port: 8443 ssl: enabled: true key-store: classpath:keystore.p12 key-store-password: your-keystore-password key-store-type: PKCS12 key-alias: tomcatlogging: level: root: INFO org.springframework: WARN Troubleshooting Common Issues[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#troubleshooting-common-issues "Direct link to Troubleshooting Common Issues") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Authentication Issues[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#authentication-issues "Direct link to Authentication Issues") Increase security logging to diagnose authentication problems: logging: level: org.springframework.security: DEBUG stirling.software.SPDF.config.security: DEBUG ### SAML/OAuth Issues[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#samloauth-issues "Direct link to SAML/OAuth Issues") Increase SAML-related logging for SSO troubleshooting: logging: level: org.springframework.security.saml2: TRACE org.springframework.security.oauth2: DEBUG org.opensaml: DEBUG ### General Application Issues[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#general-application-issues "Direct link to General Application Issues") For general application issues: logging: level: stirling.software.SPDF: DEBUG > #### ⚠️ Note[​](https://docs.stirlingpdf.com/Configuration/Extra-Settings#%EF%B8%8F-note-1 "Direct link to ⚠️ Note") > > _Debug-level logging can significantly increase log volume and may impact performance in production environments. Return logging to normal levels after troubleshooting._ * [Logging Configuration](https://docs.stirlingpdf.com/Configuration/Extra-Settings#logging-configuration) * [Server Configuration](https://docs.stirlingpdf.com/Configuration/Extra-Settings#server-configuration) * [SSL/TLS Configuration](https://docs.stirlingpdf.com/Configuration/Extra-Settings#ssltls-configuration) * [Creating a Self-Signed Certificate](https://docs.stirlingpdf.com/Configuration/Extra-Settings#creating-a-self-signed-certificate) * [Configuration Examples](https://docs.stirlingpdf.com/Configuration/Extra-Settings#configuration-examples) * [Basic Configuration](https://docs.stirlingpdf.com/Configuration/Extra-Settings#basic-configuration) * [HTTPS Configuration](https://docs.stirlingpdf.com/Configuration/Extra-Settings#https-configuration) * [Troubleshooting Common Issues](https://docs.stirlingpdf.com/Configuration/Extra-Settings#troubleshooting-common-issues) * [Authentication Issues](https://docs.stirlingpdf.com/Configuration/Extra-Settings#authentication-issues) * [SAML/OAuth Issues](https://docs.stirlingpdf.com/Configuration/Extra-Settings#samloauth-issues) * [General Application Issues](https://docs.stirlingpdf.com/Configuration/Extra-Settings#general-application-issues) --- # Login, System and Security | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#__docusaurus_skipToContent_fallback) On this page Stirling PDF allows customization of system and security settings. For security features to be enabled, you must use the security jar. For Docker users, this means setting `DISABLE_ADDITIONAL_FEATURES` to `false` via an environment variable. Basic Security Settings[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#basic-security-settings "Direct link to Basic Security Settings") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- * `enableLogin`: Enables or disables the login functionality (only available in Stirling-PDF-with-login.jar or when `DISABLE_ADDITIONAL_FEATURES=false`) * `csrfDisabled`: Set to 'true' to disable CSRF protection (not recommended for production) * `defaultLocale`: Set the default language (e.g. 'de-DE', 'fr-FR', etc) * `googlevisibility`: 'true' to allow Google visibility (via robots.txt), 'false' to disallow * `xFrameOptions`: Controls whether your instance can be embedded in an iframe. Set to `DENY` to prevent clickjacking. Use `SAMEORIGIN` only if you embed the UI in your own application. * `loginAttemptCount`: Number of failed login attempts before an account is locked (e.g. `5`) * `loginResetTimeMinutes`: Minutes before a locked account is automatically unlocked (e.g. `10`) Authentication Setup[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#authentication-setup "Direct link to Authentication Setup") ------------------------------------------------------------------------------------------------------------------------------------------------------- **Important:** Authentication and additional features are included by default in: * **Docker**: All images except ultra-lite (authentication is **enabled by default**) * **JAR files**: Use [Stirling-PDF-with-login.jar](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) **(Recommended)** **Not included in:** * **Docker ultra-lite**: Minimal build without authentication (set `DISABLE_ADDITIONAL_FEATURES=false` to enable) * **Plain JAR**: [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) - Basic build without authentication or additional features ### Prerequisites[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#prerequisites "Direct link to Prerequisites") 1. Ensure the `/configs` directory is mounted as a volume in Docker for persistence across updates 2. Use the appropriate build: * **JAR**: Download Stirling-PDF-with-login.jar * **Docker**: Set `DISABLE_ADDITIONAL_FEATURES=false` in environment variables ### Initial Login Credentials[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#initial-login-credentials "Direct link to Initial Login Credentials") * Default Username: `admin` * Default Password: `stirling` * Note: Users will be forced to change their password on first login * Custom initial credentials can be set using: * `SECURITY_INITIALLOGIN_USERNAME` * `SECURITY_INITIALLOGIN_PASSWORD` ### Database Location[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#database-location "Direct link to Database Location") Upon successful setup, a new `stirling-pdf-DB-2.3.232.mv.db` file will be created in your configured storage location. This file contains user data and should be backed up regularly. ### Account Management[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#account-management "Direct link to Account Management") 1. Access Account Settings: * Click the settings cog menu in the top right navbar * Select "Account Settings" * Here you can manage your profile and find your API key 2. Adding New Users: * Navigate to Account Settings * Scroll to bottom and click 'Admin Settings' * Use the user management interface to add new users ### Role-Based Access Control[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#role-based-access-control "Direct link to Role-Based Access Control") Currently, roles are primarily used for rate limiting purposes. The role system is under active development and will be expanded with additional features in future updates. ### API Authentication[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#api-authentication "Direct link to API Authentication") When using the API: * Each user has a unique API key found in their Account Settings * Include the API key in requests using the `X-API-KEY` header * Example: X-API-KEY: your-api-key-here Running Without Authentication[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#running-without-authentication "Direct link to Running Without Authentication") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you need to run without authentication (note: this also disables additional features), you have two options: ### Option 1: Disable Login in With-Login Version (Recommended)[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#option-1-disable-login-in-with-login-version-recommended "Direct link to Option 1: Disable Login in With-Login Version (Recommended)") Disable authentication while keeping additional features: * Settings File * Environment Variable * Docker Run * Docker Compose * JAR (Java Property) * JAR (Environment Variable) security: enableLogin: false SECURITY_ENABLELOGIN=false docker run -d \ -p 8080:8080 \ -e SECURITY_ENABLELOGIN=false \ -e DISABLE_ADDITIONAL_FEATURES=false \ stirlingtools/stirling-pdf:latest services: stirling-pdf: image: stirlingtools/stirling-pdf:latest environment: SECURITY_ENABLELOGIN: false DISABLE_ADDITIONAL_FEATURES: false java -jar Stirling-PDF-with-login.jar -DSECURITY_ENABLELOGIN=false export SECURITY_ENABLELOGIN=falsejava -jar Stirling-PDF-with-login.jar ### Option 2: Use Open Source JAR[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#option-2-use-open-source-jar "Direct link to Option 2: Use Open Source JAR") Use [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) which has no authentication (note: also excludes additional features): java -jar Stirling-PDF.jar ### Recommendation[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#recommendation "Direct link to Recommendation") **We recommend Stirling-PDF-with-login.jar for all deployments** because it includes additional features beyond just authentication. You can always disable authentication if needed while keeping the extra functionality. * * * Server Certificates[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#server-certificates "Direct link to Server Certificates") ---------------------------------------------------------------------------------------------------------------------------------------------------- Stirling PDF can auto-generate certificates for the "Sign with Stirling PDF" feature. ### Configuration[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#configuration "Direct link to Configuration") system: serverCertificate: enabled: true # Enable auto-generation organizationName: Stirling-PDF # Certificate organization name validity: 365 # Days until expiration regenerateOnStartup: false # Keep same cert across restarts **Environment Variables:** SYSTEM_SERVERCERTIFICATE_ENABLED=trueSYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"SYSTEM_SERVERCERTIFICATE_VALIDITY=365SYSTEM_SERVERCERTIFICATE_REGENERATEONSTARTUP=false ### How It Works[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#how-it-works "Direct link to How It Works") 1. **First Startup:** Server generates self-signed certificate, stored in `/configs` directory 2. **Subsequent Startups:** Reuses existing certificate (unless `regenerateOnStartup: true`) 3. **User Signs:** PDFs signed using this certificate via "Sign with Stirling PDF" option ### Custom Certificates[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#custom-certificates "Direct link to Custom Certificates") To use your own certificate instead: 1. Place certificate in `/configs/keystore.p12` 2. Set `serverCertificate.enabled: false` 3. Provide password via `KEYSTORE_PASSWORD` environment variable **Learn more:** [Certificate Signing Guide](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) * * * Signature Validation[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#signature-validation "Direct link to Signature Validation") ------------------------------------------------------------------------------------------------------------------------------------------------------- Configure how PDF certificate signatures are validated. ### Trust Sources[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#trust-sources "Direct link to Trust Sources") security: validation: trust: serverAsAnchor: true # Trust server-generated certificates useSystemTrust: true # Use OS certificate store useMozillaBundle: true # Mozilla CA bundle useAATL: false # Adobe Approved Trust List useEUTL: false # EU Trusted List (eIDAS) **Environment Variables:** SECURITY_VALIDATION_TRUST_SERVERASANCHOR=trueSECURITY_VALIDATION_TRUST_USESYSTEMTRUST=trueSECURITY_VALIDATION_TRUST_USEMOZILLABUNDLE=trueSECURITY_VALIDATION_TRUST_USEAATL=falseSECURITY_VALIDATION_TRUST_USEEUTL=false ### Trust List URLs[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#trust-list-urls "Direct link to Trust List URLs") Configure external trust list locations: security: validation: aatl: url: https://trustlist.adobe.com/tl.pdf eutl: lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml acceptTransitional: false ### Revocation Checking[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#revocation-checking "Direct link to Revocation Checking") Verify certificates haven't been revoked: security: validation: revocation: mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false # Fail validation if revocation check fails **Revocation Modes:** * `none`: No revocation checking (not recommended for production) * `ocsp`: Online Certificate Status Protocol (fast, requires network) * `crl`: Certificate Revocation Lists (slower, works offline) * `ocsp+crl`: Try OCSP first, fall back to CRL (recommended) **Environment Variables:** SECURITY_VALIDATION_REVOCATION_MODE=ocsp+crlSECURITY_VALIDATION_REVOCATION_HARDFAIL=false ### Authority Information Access (AIA)[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#authority-information-access-aia "Direct link to Authority Information Access (AIA)") Allow automatic fetching of intermediate certificates: security: validation: allowAIA: false # Set true to enable (requires network access) **⚠️ Security Note:** Disabled by default. Only enable in controlled environments where outbound HTTPS is secure. **Learn more:** [Certificate Signing - Validation](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing#validating-signatures) * * * JWT Authentication[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#jwt-authentication "Direct link to JWT Authentication") ------------------------------------------------------------------------------------------------------------------------------------------------- Configure JSON Web Token authentication for sessions. ### JWT Settings[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#jwt-settings "Direct link to JWT Settings") security: jwt: persistence: true # Store keys across restarts enableKeyRotation: true # Rotate signing keys periodically enableKeyCleanup: true # Auto-delete old keys keyRetentionDays: 7 # How long to keep old keys **Environment Variables:** SECURITY_JWT_PERSISTENCE=trueSECURITY_JWT_ENABLEKEYROTATION=trueSECURITY_JWT_ENABLEKEYCLEANUP=trueSECURITY_JWT_KEYRETENTIONDAYS=7 ### What These Settings Do[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#what-these-settings-do "Direct link to What These Settings Do") * **`persistence`**: Store JWT signing keys in database, survive container restarts * **`enableKeyRotation`**: Periodically generate new signing keys for security * **`enableKeyCleanup`**: Automatically delete old keys after retention period * **`keyRetentionDays`**: Grace period where old keys still work (prevents immediate logout) ### Migration from V1[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#migration-from-v1 "Direct link to Migration from V1") If migrating from V1, note these setting name changes: * `jwt.enabled` → `jwt.persistence` * `jwt.keyCleanup` → `jwt.enableKeyCleanup` * `jwt.secureCookie` → Removed (always secure in production) **Learn more:** [Migration - JWT Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes#enhanced-jwt-configuration) * * * Email Configuration[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#email-configuration "Direct link to Email Configuration") ---------------------------------------------------------------------------------------------------------------------------------------------------- Configure SMTP for sending email invitations and notifications. Enable `mail.enableInvites` to allow invitation links. > 💡 **When is email configuration required?** > > Email configuration is **OPTIONAL** and only needed for: > > * **Email invitations**: Admins can send invite links to users via email > * **Password reset emails**: Users can reset forgotten passwords (if implemented) > > Email is **NOT required** for: > > * Basic username/password login > * SSO authentication (OAuth 2.0 or SAML 2.0) > * Manual user creation by admins > * Normal application operation > > You can run Stirling PDF without any email configuration if you create users manually or use SSO. ### Email Invites[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#email-invites "Direct link to Email Invites") Enable email-based user invitations: mail: enabled: true from: noreply@example.com enableInvites: true smtp: host: smtp.example.com port: 587 username: noreply@example.com password: ${MAIL_PASSWORD} tls: enabled: true **Environment Variables:** MAIL_ENABLED=trueMAIL_FROM=noreply@example.comMAIL_ENABLEINVITES=trueMAIL_HOST=smtp.gmail.comMAIL_PORT=587MAIL_USERNAME=your-email@gmail.comMAIL_PASSWORD=your-app-passwordMAIL_TLS_ENABLED=true **Requirements:** * `mail.enabled: true` * `mail.enableInvites: true` for invitation flows * `security.enableLogin: true` * Valid SMTP configuration * `system.frontendUrl` configured (for invite links) * * * UI Customization[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#ui-customization "Direct link to UI Customization") ------------------------------------------------------------------------------------------------------------------------------------------- ### Logo Style[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#logo-style "Direct link to Logo Style") Choose between logo styles: ui: logoStyle: classic # Options: 'classic' or 'modern' **Environment Variable:** UI_LOGOSTYLE=modern **Styles:** * `classic`: Traditional "S" icon logo * `modern`: Minimalist design ### Custom Logo[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#custom-logo "Direct link to Custom Logo") You can also provide a custom logo file: customFiles/ └── static/ └── logo.svg # Your custom logo **Learn more:** [UI Customisation](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) * * * Configuration Examples ====================== * Settings File * Local Configuration * Docker Run * Docker Compose security: enableLogin: true # Only works with Stirling-PDF-with-login.jar or DISABLE_ADDITIONAL_FEATURES=false csrfDisabled: true jwt: persistence: true enableKeyRotation: true enableKeyCleanup: true keyRetentionDays: 7 validation: trust: serverAsAnchor: true useSystemTrust: true useMozillaBundle: true revocation: mode: ocsp hardFail: falsesystem: 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: 365mail: enabled: false enableInvites: falseui: logoStyle: classic You can configure these settings in two ways when running locally: **Option 1: Using Java Properties** java -jar Stirling-PDF.jar -DDISABLE_ADDITIONAL_FEATURES=false -DSECURITY_ENABLELOGIN=true **Option 2: Using Environment Variables** export DISABLE_ADDITIONAL_FEATURES=falseexport SECURITY_ENABLELOGIN=true -e DISABLE_ADDITIONAL_FEATURES=false \-e SECURITY_ENABLELOGIN=true \-e SYSTEM_CORSALLOWEDORIGINS=https://pdf.example.com \-e SYSTEM_FRONTENDURL=https://pdf.example.com \-e SECURITY_JWT_PERSISTENCE=true \ environment: DISABLE_ADDITIONAL_FEATURES: false SECURITY_ENABLELOGIN: true SECURITY_JWT_PERSISTENCE: true SYSTEM_SERVERCERTIFICATE_ENABLED: true * * * Related Documentation[​](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#related-documentation "Direct link to Related Documentation") ---------------------------------------------------------------------------------------------------------------------------------------------------------- * **[Security Features](https://docs.stirlingpdf.com/Functionality/Security/) ** - PDF security tools, CORS, signature validation * **[Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ** - Comprehensive signing and validation guide * **[Single Sign-On](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) ** - Enterprise authentication * **[UI Customisation](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) ** - Branding and appearance * **[Migration Guide](https://docs.stirlingpdf.com/Migration/Settings-Changes) ** - Upgrading from V1 * [Basic Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#basic-security-settings) * [Authentication Setup](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#authentication-setup) * [Prerequisites](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#prerequisites) * [Initial Login Credentials](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#initial-login-credentials) * [Database Location](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#database-location) * [Account Management](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#account-management) * [Role-Based Access Control](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#role-based-access-control) * [API Authentication](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#api-authentication) * [Running Without Authentication](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#running-without-authentication) * [Option 1: Disable Login in With-Login Version (Recommended)](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#option-1-disable-login-in-with-login-version-recommended) * [Option 2: Use Open Source JAR](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#option-2-use-open-source-jar) * [Recommendation](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#recommendation) * [Server Certificates](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#server-certificates) * [Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#configuration) * [How It Works](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#how-it-works) * [Custom Certificates](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#custom-certificates) * [Signature Validation](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#signature-validation) * [Trust Sources](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#trust-sources) * [Trust List URLs](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#trust-list-urls) * [Revocation Checking](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#revocation-checking) * [Authority Information Access (AIA)](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#authority-information-access-aia) * [JWT Authentication](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#jwt-authentication) * [JWT Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#jwt-settings) * [What These Settings Do](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#what-these-settings-do) * [Migration from V1](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#migration-from-v1) * [Email Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#email-configuration) * [Email Invites](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#email-invites) * [UI Customization](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#ui-customization) * [Logo Style](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#logo-style) * [Custom Logo](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#custom-logo) * [Related Documentation](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#related-documentation) --- # Mac Installation Guide | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Mac%20Installation#__docusaurus_skipToContent_fallback) On this page Stirling PDF for Mac is available as a **native desktop application** or can run as a **server** using the JAR file. Desktop Application (Recommended)[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#desktop-application-recommended "Direct link to Desktop Application (Recommended)") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Native Mac desktop app with all PDF tools available. ### What You Get[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#what-you-get "Direct link to What You Get") * ✅ **Native macOS application** - Optimized for both Apple Silicon and Intel Macs * ✅ **No login required** - Install and start using PDF tools right away * ✅ **Processes files locally** - All your PDF processing stays on your Mac * ✅ **Optional server connection** - Connect to Stirling Cloud or your own self-hosted server for advanced tools like OCR and document conversions * ✅ **All local tools included** - Merge, split, rotate, sign, and more work without any server * ✅ **Better performance** - Native speed on M1/M2/M3 chips * ✅ **No external browser needed** - Uses the built-in window * ✅ **Menu bar integration** - Feels like a native Mac app ### Installation Steps[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#installation-steps "Direct link to Installation Steps") **1\. Download the right version for your Mac:** | Chip Type | Download Link | | --- | --- | | **Apple Silicon** (M1/M2/M3) | [Download for Apple Silicon](https://files.stirlingpdf.com/mac-installer.dmg) | | **Intel** processors | [Download for Intel](https://files.stirlingpdf.com/mac-x86_64-installer.dmg) | **Not sure which chip you have?** * Click the Apple menu → "About This Mac" * Look at "Chip" or "Processor" * If it says "M1", "M2", or "M3" → Use Apple Silicon version * If it says "Intel" → Use Intel version **2\. Install the application:** 1. Open the downloaded `.dmg` file 2. Drag Stirling PDF to your Applications folder ![mac-installer.png](https://docs.stirlingpdf.com/assets/images/mac-installer-ccc8bc3bb1c7ee7bbddea1af99aec658.png) **3\. First-time launch (Security):** macOS will block the app on first launch because it's not from the App Store: ![mac-app-blocked.png](https://docs.stirlingpdf.com/assets/images/mac-app-blocked-55a8f08bac7011f4127128c619fcfc15.png) **To allow Stirling PDF:** 1. Open **System Settings** → **Privacy & Security** 2. Scroll down to the **Security** section 3. Click **"Open Anyway"** next to the Stirling PDF message 4. Enter your password if prompted 5. Go back to Applications and launch Stirling PDF again ![mac-security-allow.png](https://docs.stirlingpdf.com/assets/images/mac-security-allow-c77bdbbb4ab77f0df5ac46e9c784f659.png) The app will now open normally every time! ### Using the Desktop App[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#using-the-desktop-app "Direct link to Using the Desktop App") 1. Launch Stirling PDF 2. Start using local PDF tools right away - no login needed 3. Upload or drag-and-drop files into the window 4. Optionally connect to Stirling Cloud or a self-hosted server for advanced tools like OCR and document conversions **Making Stirling PDF your default PDF viewer:** 1. Right-click (or Control+click) any PDF file 2. Select **"Get Info"** 3. Under **"Open with"**, choose **Stirling PDF** 4. Click **"Change All"** to apply to all PDFs 5. Confirm when prompted **Benefits of desktop app:** * Files stay on your Mac (not in browser storage) * Work without internet connection * Native performance (especially on Apple Silicon) * Unlimited file storage * Menu bar integration * macOS gestures and features work Server Version (For Hosting and Sharing)[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#server-version-for-hosting-and-sharing "Direct link to Server Version (For Hosting and Sharing)") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Want to host Stirling PDF on a Mac server for multiple users? Use the JAR file version. ### Prerequisites[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#prerequisites "Direct link to Prerequisites") Install Java 21 (required for server version): # Install Homebrew if you don't have it/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# Install Java 21brew install openjdk@21# Add to your PATH (add to ~/.zshrc to make permanent)export PATH="/usr/local/opt/openjdk@21/bin:$PATH" ### JAR Downloads[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#jar-downloads "Direct link to JAR Downloads") Stirling PDF comes in three different JAR files: **Stirling-PDF-with-login.jar** (Recommended - Full Features): * Download: [Stirling-PDF-with-login.jar](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) * Bundles frontend UI + backend server in one file * **Includes authentication and additional features** - requires user login (default credentials: `admin` / `stirling`) * **Recommended for all users** - personal, shared, or enterprise deployments **Stirling-PDF.jar** (Plain JAR - Basic Features): * Download: [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) * Bundles frontend UI + backend server in one file * **Basic version** - no authentication, core features only * Only use if you require no login at all and don't mind missing certain features **Stirling-PDF-server.jar** (Backend Only - **Advanced**): * Download: [Stirling-PDF-server.jar](https://files.stirlingpdf.com/Stirling-PDF-server.jar) * Backend server only (no bundled UI) * **No authentication** - API access only * For desktop app backend, custom frontend, or API integrations ### Running the Server[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#running-the-server "Direct link to Running the Server") 1. **Download your preferred JAR file** (see above) 2. **Open Terminal** and navigate to the download folder: cd ~/Downloads # Or wherever you saved the JAR 3. **Run Stirling PDF**: java -jar Stirling-PDF.jar 4. **Access via browser** at `http://localhost:8080` 5. **Share with others** on your network at `http://your-mac-ip:8080` ### Creating a Convenience Script[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#creating-a-convenience-script "Direct link to Creating a Convenience Script") For easier launching, create a startup script: 1. **Create the script**: nano ~/run-stirling.sh 2. **Add these contents**: #!/bin/bashcd ~/Downloads # Change to where your JAR is locatedjava -jar Stirling-PDF.jar 3. **Save and exit** (Ctrl+X, then Y, then Enter) 4. **Make it executable**: chmod +x ~/run-stirling.sh 5. **Run anytime with**: ~/run-stirling.sh ### Optional Dependencies[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#optional-dependencies "Direct link to Optional Dependencies") Install these via [Homebrew](https://brew.sh/) to enable additional features like advanced document conversion or PDF compression: # Install Homebrew if needed/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# Install dependencies as neededbrew install openjdk@21 # Requiredbrew install qpdf # PDF compressionbrew install --cask libreoffice # Document conversionbrew install tesseract # OCR functionalitybrew install tesseract-lang # Additional OCR languagesbrew install poppler # PDF to HTML conversionpip3 install weasyprint # URL to PDF conversionpip3 install unoserver # File to PDF conversion For Tesseract OCR, add to `config/settings.yml` (generated once you first run the jar): system: tessdataDir: /usr/local/share/tessdata Quick Troubleshooting[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#quick-troubleshooting "Direct link to Quick Troubleshooting") ---------------------------------------------------------------------------------------------------------------------------------------------------- * Java not found? Add to `~/.zshrc`: export PATH="/usr/local/opt/openjdk@21/bin:$PATH" * Verify installations with: `[command] --version` (e.g., `java --version`) * LibreOffice issues? Ensure no LibreOffice processes are running * Need help? Visit [GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) ### Starting unoserver alongside Stirling PDF[​](https://docs.stirlingpdf.com/Installation/Mac%20Installation#starting-unoserver-alongside-stirling-pdf "Direct link to Starting unoserver alongside Stirling PDF") To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command: unoserver --port 2003 --interface 0.0.0.0 You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF. * [Desktop Application (Recommended)](https://docs.stirlingpdf.com/Installation/Mac%20Installation#desktop-application-recommended) * [What You Get](https://docs.stirlingpdf.com/Installation/Mac%20Installation#what-you-get) * [Installation Steps](https://docs.stirlingpdf.com/Installation/Mac%20Installation#installation-steps) * [Using the Desktop App](https://docs.stirlingpdf.com/Installation/Mac%20Installation#using-the-desktop-app) * [Server Version (For Hosting and Sharing)](https://docs.stirlingpdf.com/Installation/Mac%20Installation#server-version-for-hosting-and-sharing) * [Prerequisites](https://docs.stirlingpdf.com/Installation/Mac%20Installation#prerequisites) * [JAR Downloads](https://docs.stirlingpdf.com/Installation/Mac%20Installation#jar-downloads) * [Running the Server](https://docs.stirlingpdf.com/Installation/Mac%20Installation#running-the-server) * [Creating a Convenience Script](https://docs.stirlingpdf.com/Installation/Mac%20Installation#creating-a-convenience-script) * [Optional Dependencies](https://docs.stirlingpdf.com/Installation/Mac%20Installation#optional-dependencies) * [Quick Troubleshooting](https://docs.stirlingpdf.com/Installation/Mac%20Installation#quick-troubleshooting) * [Starting unoserver alongside Stirling PDF](https://docs.stirlingpdf.com/Installation/Mac%20Installation#starting-unoserver-alongside-stirling-pdf) --- # Unix Installation Guide | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Unix%20Installation#__docusaurus_skipToContent_fallback) On this page Stirling PDF on Linux is available as a **native desktop application** or as a **server** using the JAR file. Desktop Application (Recommended for Personal Use)[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#desktop-application-recommended-for-personal-use "Direct link to Desktop Application (Recommended for Personal Use)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Native Linux desktop app with all PDF tools available. ### What You Get[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#what-you-get "Direct link to What You Get") * ✅ **Native Linux application** - Integrated with your desktop environment * ✅ **Open PDFs directly** - Double-click any PDF to open in Stirling-PDF * ✅ **No login required** - Install and start using PDF tools right away * ✅ **Processes files locally** - All your PDF processing stays on your device * ✅ **Optional server connection** - Connect to Stirling Cloud or your own self-hosted server for advanced tools like OCR and document conversions * ✅ **All local tools included** - Merge, split, rotate, sign, and more work without any server * ✅ **Better performance** - Native Linux integration * ✅ **No browser needed** - Standalone application ### Installation[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#installation "Direct link to Installation") **1\. Download:** [Stirling-PDF Desktop Installer (DEB)](https://files.stirlingpdf.com/linux-installer.deb) **2\. Install the application:** sudo dpkg -i linux-installer.deb **3\. Launch Stirling-PDF:** * Search for "Stirling-PDF" in your application menu, or * Run `stirling-pdf` from the terminal ### Connecting to a server[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#connecting-to-a-server "Direct link to Connecting to a server") The desktop app works fully offline for local PDF tools like merging, splitting, rotating, and signing. If you need advanced server-side features like OCR or document format conversions, you can connect to a server at any time: **Stirling Cloud** * Sign in with your Stirling Cloud account * Gives access to advanced tools powered by server-side processing * Your files are processed securely and never stored **Self-hosted Server** * Enter the URL of your own Stirling-PDF server instance (e.g., `http://192.168.1.53:8080`) * Full control over your data and processing * Useful for team deployments or when you want all features on your own infrastructure * * * Server Version (For Hosting and Sharing)[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#server-version-for-hosting-and-sharing "Direct link to Server Version (For Hosting and Sharing)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ To run the application without Docker/Podman, you will need to manually install all dependencies and build the necessary components. Note that some dependencies might not be available in the standard repositories of all Linux distributions, and may require additional steps to install. The following guide assumes you have a basic understanding of using a command line interface in your operating system. It should work on most Linux distributions and MacOS. For Windows, you might need to use Windows Subsystem for Linux (WSL) for certain steps. The amount of dependencies is to actually reduce overall size, ie installing LibreOffice sub components rather than full LibreOffice package. You could theoretically use a Distrobox/Toolbox, if your Distribution has old or not all Packages. But you might just as well use the Docker Container then. ### Step 1: Prerequisites[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-1-prerequisites "Direct link to Step 1: Prerequisites") Install the following software, if not already installed: * Java 21 or later * Gradle 7.0 or later (included within repo so not needed on server) * Git * Python 3.8 (with pip) * Make * GCC/G++ * Automake * Autoconf * libtool * pkg-config * zlib1g-dev * libleptonica-dev * Debian-based Systems * Fedora-based Systems * Nix Package Manager sudo apt-get updatesudo apt-get install -y git automake autoconf libtool \ libleptonica-dev pkg-config zlib1g-dev make g++ \ openjdk-21-jdk python3 python3-pip sudo dnf install -y git automake autoconf libtool \ leptonica-devel pkg-config zlib-devel make gcc-c++ \ java-21-openjdk python3 python3-pip nix-channel --updatenix-env -iA nixpkgs.jdk21 nixpkgs.git nixpkgs.python38 \ nixpkgs.gnumake nixpkgs.libgcc nixpkgs.automake \ nixpkgs.autoconf nixpkgs.libtool nixpkgs.pkg-config \ nixpkgs.zlib nixpkgs.leptonica ### Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-2-clone-and-build-jbig2enc-only-required-for-certain-ocr-functionality "Direct link to Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)") * Debian * Fedora * Nix Package Manager mkdir ~/.gitcd ~/.git &&\git clone https://github.com/agl/jbig2enc.git &&\cd jbig2enc &&\./autogen.sh &&\./configure &&\make &&\sudo make install mkdir ~/.gitcd ~/.git &&\git clone https://github.com/agl/jbig2enc.git &&\cd jbig2enc &&\./autogen.sh &&\./configure &&\make &&\sudo make install nix-env -iA nixpkgs.jbig2enc ### Step 3: Install Additional Software[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-3-install-additional-software "Direct link to Step 3: Install Additional Software") Next we need to install LibreOffice for conversions, tesseract for OCR, and opencv for pattern recognition functionality. Install the following software: * libreoffice (libreoffice-core libreoffice-common libreoffice-writer libreoffice-calc libreoffice-impress) * python3-uno * unoserver * pngquant * tesseract * opencv-python-headless * Debian-based Systems * Fedora-based Systems * Nix Package Manager sudo apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseract-ocrpip3 install uno opencv-python-headless unoserver pngquant WeasyPrint --break-system-packages sudo dnf install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseractpip3 install uno opencv-python-headless unoserver pngquant WeasyPrint nix-env -iA nixpkgs.libreoffice nixpkgs.tesseract nixpkgs.poppler_utilspip3 install uno opencv-python-headless unoserver pngquant WeasyPrint ### Step 4: Grab latest Stirling PDF Jar[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-4-grab-latest-stirling-pdf-jar "Direct link to Step 4: Grab latest Stirling PDF Jar") Stirling PDF comes in three different JAR files: **Stirling-PDF-with-login.jar** (Recommended - Full Features): * Download: [Stirling-PDF-with-login.jar](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) * Bundles frontend UI + backend server in one file * **Includes authentication and additional features** - requires user login (default credentials: `admin` / `stirling`) * **Recommended for all users** - personal, shared, or enterprise deployments **Stirling-PDF.jar** (Plain JAR - Basic Features): * Download: [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) * Bundles frontend UI + backend server in one file * **Basic version** - no authentication, core features only * Only use if you require no login at all and don't mind missing certain features **Stirling-PDF-server.jar** (Backend Only - **Advanced**): * Download: [Stirling-PDF-server.jar](https://files.stirlingpdf.com/Stirling-PDF-server.jar) * Backend server only (no bundled UI) * **No authentication** - API access only * For desktop app backend, custom frontend, or API integrations Example download and setup: sudo wget https://files.stirlingpdf.com/Stirling-PDF.jarsudo chmod +x Stirling-PDF.jar ### Step 4b: Clone the Stirling-PDF Repository[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-4b-clone-the-stirling-pdf-repository "Direct link to Step 4b: Clone the Stirling-PDF Repository") You need the repository to get the `scripts` folder, which contains Python scripts used by OpenCV for certain PDF operations. git clone https://github.com/Stirling-Tools/Stirling-PDF.git ### Step 5: Move JAR and Scripts to Desired Location[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-5-move-jar-and-scripts-to-desired-location "Direct link to Step 5: Move JAR and Scripts to Desired Location") Move the downloaded JAR file and the `scripts` folder from the cloned repository to a desired location, for example, `/opt/Stirling-PDF/`. The `scripts` folder is required for the Python scripts using OpenCV. * Debian (Root) * Fedora (Root) * Nix (Non-root) 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." 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." mkdir -p ~/Stirling-PDF &&\mv Stirling-PDF.jar ~/Stirling-PDF/ &&\cp -r Stirling-PDF/scripts ~/Stirling-PDF/ ### Step 6: OCR Language Support[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-6-ocr-language-support "Direct link to Step 6: OCR Language Support") If you plan to use the OCR (Optical Character Recognition) functionality, you might need to install language packs for Tesseract if running non-english scanning. * Debian-based Systems * Fedora-based Systems * Nix Package Manager * Manual Installation 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' # 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' nix-env -iA nixpkgs.tesseract Note: Nix Package Manager pre-installs almost all the language packs when tesseract is installed. 1. Download the desired language pack(s) by selecting the `.traineddata` file(s) for the language(s) you need. 2. Place the `.traineddata` files in the Tesseract tessdata directory: `/usr/share/tessdata` 3. Please view [tesseract install guide](https://tesseract.readthedocs.io/en/latest/installation.html) for more info. **IMPORTANT:** DO NOT REMOVE EXISTING `eng.traineddata`, IT'S REQUIRED. ### Step 7: Run Stirling PDF[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-7-run-stirling-pdf "Direct link to Step 7: Run Stirling PDF") * Debian-based Systems * Fedora-based Systems * Nix Package Manager java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar Since libreoffice, soffice, and conversion tools have their dbus\_tmp\_dir set as `dbus_tmp_dir="/run/user/$(id -u)/libreoffice-dbus"`, you get the following error: `[Thread-7] INFO s.s.SPDF.utils.ProcessExecutor - mkdir: cannot create directory '/run/user/1501': Permission denied` To resolve this, use: `bash mkdir temp export DBUS_SESSION_BUS_ADDRESS="unix:path=./temp"` ### Step 8: Adding a Desktop Icon[​](https://docs.stirlingpdf.com/Installation/Unix%20Installation#step-8-adding-a-desktop-icon "Direct link to Step 8: Adding a Desktop Icon") This will add a modified Appstarter to your Appmenu. location=$(pwd)/gradlewimage=$(pwd)/docs/stirling-transparent.svgcat > ~/.local/share/applications/Stirling-PDF.desktop <Set to `1` to enforce self-hosted server only, preventing accidental connections to external servers. | `1` (locked) or `0` (unlocked) | **Example Installation Command:** msiexec /i "Stirling-PDF-windows-x86_64.msi" /qn STIRLING_SERVER_URL="http://192.168.1.53:2357" STIRLING_LOCK_CONNECTION=1 **Command Breakdown:** * `msiexec` - Windows Installer command-line tool (included with all Windows installations) for installing, modifying, and performing operations on MSI packages * `/i` - Install the MSI package * `/qn` - Run silently with no user interface (quiet mode, no UI) * `STIRLING_SERVER_URL` - Automatically sets the server URL on first launch * `STIRLING_LOCK_CONNECTION=1` - Locks the connection to the specified server (users cannot change it) **Additional Parameters:** | Parameter | Description | Example | | --- | --- | --- | | `INSTALLDIR` | Custom installation directory | `INSTALLDIR="C:\CustomPath\Stirling-PDF"` | | `ALLUSERS` | Install for all users (requires admin).
`1` = all users, `0` or omit = current user only | `ALLUSERS=1` | **Technical Details:** * **Default Install Location**: `C:\Program Files\Stirling-PDF` * **Settings Storage**: `%APPDATA%\stirling.pdf.dev\connection.json` (per-user settings) * **Provisioning File**: * Per-user install: `%APPDATA%\stirling.pdf.dev\stirling-provisioning.json` * All-users install: `%PROGRAMDATA%\Stirling-PDF\stirling-provisioning.json` * **URL Format**: Must include protocol (`http://` or `https://`), trailing slash is optional **Notes:** * The MSI installer is available in the [releases](https://github.com/Stirling-Tools/Stirling-PDF/releases/latest) * When `STIRLING_LOCK_CONNECTION=1` is set, users cannot modify the server URL in the application settings * For unattended installations without parameters, omit the custom properties * System-wide provisioning files (`%PROGRAMDATA%`) are not deleted after being applied, allowing reinstallation with same settings Server Version (For Hosting and Sharing)[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-version-for-hosting-and-sharing "Direct link to Server Version (For Hosting and Sharing)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Want to host Stirling PDF on a Windows server for multiple users? Use the server version. ### Server Downloads[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-downloads "Direct link to Server Downloads") Stirling PDF comes in three different JAR files: **Stirling-PDF-with-login.jar** (Recommended - Full Features): * Download: [Stirling-PDF-with-login.jar](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) * Bundles frontend UI + backend server in one file * **Includes authentication and additional features** - requires user login (default credentials: `admin` / `stirling`) * **Recommended for all users** - personal, shared, or enterprise deployments **Stirling-PDF.jar** (Plain JAR - Basic Features): * Download: [Stirling-PDF.jar](https://files.stirlingpdf.com/Stirling-PDF.jar) * Bundles frontend UI + backend server in one file * **Basic version** - no authentication, core features only * Only use if you require no login at all and don't mind missing certain features **Stirling-PDF-server.jar** (Backend Only - **Advanced**): * Download: [Stirling-PDF-server.jar](https://files.stirlingpdf.com/Stirling-PDF-server.jar) * Backend server only (no bundled UI) * **No authentication** - API access only * For desktop app backend, custom frontend, or API integrations **Required:** [Java JDK 21](https://download.oracle.com/java/21/latest/jdk-21_windows-x64_bin.exe) - Server versions need Java installed ### Server Installation Steps[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-installation-steps "Direct link to Server Installation Steps") 1. **Install Java JDK 21** from the link above 2. **Download** your preferred JAR file 3. **Run the JAR file:** java -jar Stirling-PDF.jar 4. **Access** via browser at `http://localhost:8080` 5. **Share the URL** with users on your network (e.g., `http://your-server-ip:8080`) ### Optional Dependencies[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#optional-dependencies "Direct link to Optional Dependencies") These dependencies enable additional features in Stirling PDF. Install only the ones you need: #### Python and Related Tools[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#python-and-related-tools "Direct link to Python and Related Tools") Python and its related tools enable various features in Stirling PDF: * OpenCV: Enables image scan extraction features * Unoserver: Enables file to PDF conversion features * Python: Required base for OpenCV and other Python-based features 1. Python Installation: * Download Python from [Python's official site](https://www.python.org/downloads/) * During installation, **IMPORTANT**: Check "Add Python to PATH" * Verify installation by opening Command Prompt and running: python --version 2. OpenCV Installation: * After Python is installed, open Command Prompt as administrator * Install OpenCV by running: pip install opencv-python * Verify installation: python -c "import cv2" * Enables Extract Image Scans operation 3. Unoserver Installation: * First install LibreOffice (see LibreOffice section below) * Open Command Prompt as administrator * Install unoserver: pip install unoserver * Verify installation: unoserver --version * Enables File To PDF operation Note: Unoserver requires both Python and LibreOffice to function properly #### QPDF[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#qpdf "Direct link to QPDF") * Download from [QPDF's official site](https://qpdf.sourceforge.io/) * Enables PDF compression and other operations #### LibreOffice[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#libreoffice "Direct link to LibreOffice") * Download and install from [LibreOffice's official site](https://www.libreoffice.org/download/download-libreoffice/) * Enables PDF to DOCX conversion and other document format conversions #### Tesseract OCR[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#tesseract-ocr "Direct link to Tesseract OCR") 1. Download the installer from [UB Mannheim's GitHub](https://github.com/UB-Mannheim/tesseract/wiki) 2. During installation, check additional languages you need 3. Add to settings.yml in your Stirling PDF installation directory: system: tessdataDir: C:\\Program Files\\Tesseract-OCR\\tessdata * Enables OCR functionality for PDFs #### Weasyprint[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#weasyprint "Direct link to Weasyprint") 1. Download from [Weasyprint's releases](https://github.com/Kozea/WeasyPrint/releases) 2. Create a directory (e.g., `c:\weasyprint\`) and place weasyprint.exe there * Enables URL to PDF conversion * Note: Some antivirus software may flag weasyprint.exe - you may need to whitelist it #### PDFtoHTML[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#pdftohtml "Direct link to PDFtoHTML") 1. Download from [SourceForge](https://sourceforge.net/projects/pdftohtml/) 2. Create a directory (e.g., `c:\pdftohtml\`) and place pdftohtml.exe there * Enables PDF to HTML conversion Adding Directories to System PATH[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#adding-directories-to-system-path "Direct link to Adding Directories to System PATH") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- After installing dependencies, you'll need to add their directories to your system's PATH. Here's how: 1. Open Windows Search (Windows key + S) 2. Type "Environment Variables" and click "Edit the system environment variables" 3. Click "Environment Variables" button at the bottom 4. Under "System variables", find and select "Path" 5. Click "Edit" 6. Click "New" to add each required path: * For Python: Should be added automatically during installation if "Add Python to PATH" was checked * For LibreOffice: `C:\Program Files\LibreOffice\program` * For Tesseract: `C:\Program Files\Tesseract-OCR` * For Weasyprint: `C:\weasyprint` (or your chosen directory) * For PDFtoHTML: `C:\pdftohtml` (or your chosen directory) * For QPDF: The installation directory (usually `C:\Program Files\qpdf\bin`) 7. Click "OK" on all windows to save changes Server Installation Steps[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-installation-steps-1 "Direct link to Server Installation Steps") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Download the latest Stirling PDF-server.exe or jar from the [releases page](https://github.com/Stirling-Tools/Stirling-PDF/releases/latest) 2. Install any desired optional dependencies following the instructions above 3. Launch the Stirling PDF executable 4. Access the web interface through your browser (the application will provide the URL) in the console logs normally [http://localhost:8080](http://localhost:8080/) Notes[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#notes "Direct link to Notes") -------------------------------------------------------------------------------------------------------- * The application hosts a web server that is accessible to anyone on your network * If you install multiple Python-based dependencies, ensure they're using the same Python installation to avoid conflicts * Make sure to restart Stirling PDF after installing new dependencies or modifying PATH variables * Some features will be unavailable until their required dependencies are installed Troubleshooting[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#troubleshooting "Direct link to Troubleshooting") -------------------------------------------------------------------------------------------------------------------------------------- 1. Verifying PATH Settings: * Open Command Prompt (cmd) * Type `echo %PATH%` to see all directories in your PATH * For each dependency, try running its command to verify it's accessible: python --versionunoserver --versionpython -c "import cv2"tesseract --version 2. Common Issues: * If changes to PATH don't take effect, try: * Logging out and back in * Restarting your computer * Opening a new Command Prompt window * If a dependency isn't found, double-check the exact path in File Explorer * For Tesseract issues, verify the tessdata directory contains language files * For LibreOffice conversions, ensure no LibreOffice windows are open when converting * For Python/OpenCV issues: * Make sure pip is up to date: `python -m pip install --upgrade pip` * Try installing with administrator privileges * Check if Python is properly added to PATH * For unoserver issues: * Verify both Python and LibreOffice are properly installed * Make sure LibreOffice is in PATH * Try running LibreOffice once before using unoserver Starting unoserver alongside Stirling PDF[​](https://docs.stirlingpdf.com/Installation/Windows%20Installation#starting-unoserver-alongside-stirling-pdf "Direct link to Starting unoserver alongside Stirling PDF") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command: unoserver --port 2003 --interface 0.0.0.0 You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF. Need help? Visit the [Stirling PDF GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) page. * [Desktop Application (Recommended for Personal Use)](https://docs.stirlingpdf.com/Installation/Windows%20Installation#desktop-application-recommended-for-personal-use) * [What You Get](https://docs.stirlingpdf.com/Installation/Windows%20Installation#what-you-get) * [Quick Installation](https://docs.stirlingpdf.com/Installation/Windows%20Installation#quick-installation) * [Connecting to a server](https://docs.stirlingpdf.com/Installation/Windows%20Installation#connecting-to-a-server) * [Using the Desktop App](https://docs.stirlingpdf.com/Installation/Windows%20Installation#using-the-desktop-app) * [Automated Installation (MSI Installer)](https://docs.stirlingpdf.com/Installation/Windows%20Installation#automated-installation-msi-installer) * [Server Version (For Hosting and Sharing)](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-version-for-hosting-and-sharing) * [Server Downloads](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-downloads) * [Server Installation Steps](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-installation-steps) * [Optional Dependencies](https://docs.stirlingpdf.com/Installation/Windows%20Installation#optional-dependencies) * [Adding Directories to System PATH](https://docs.stirlingpdf.com/Installation/Windows%20Installation#adding-directories-to-system-path) * [Server Installation Steps](https://docs.stirlingpdf.com/Installation/Windows%20Installation#server-installation-steps-1) * [Notes](https://docs.stirlingpdf.com/Installation/Windows%20Installation#notes) * [Troubleshooting](https://docs.stirlingpdf.com/Installation/Windows%20Installation#troubleshooting) * [Starting unoserver alongside Stirling PDF](https://docs.stirlingpdf.com/Installation/Windows%20Installation#starting-unoserver-alongside-stirling-pdf) --- # Docker Guide | Stirling PDF We use essential cookies to make our site work. With your consent, we may also use non-essential cookies to improve user experience and analyze website traffic. By clicking “Accept,” you agree to our website's cookie use as described in our Cookie Policy. You can change your cookie settings at any time by clicking “Preferences.” PreferencesDeclineAccept ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Docker%20Install#__docusaurus_skipToContent_fallback) On this page Run Stirling PDF in Docker for easy self-hosting, automatic updates, and flexible deployment. Quick Start[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#quick-start "Direct link to Quick Start") -------------------------------------------------------------------------------------------------------------------- * docker run * docker-compose docker run -d \ --name stirling-pdf \ -p 8080:8080 \ -v ./stirling-data:/configs \ stirlingtools/stirling-pdf:latest Create `docker-compose.yml`: services: stirling-pdf: image: stirlingtools/stirling-pdf:latest container_name: stirling-pdf ports: - '8080:8080' volumes: - ./stirling-data:/configs restart: unless-stopped Then run: docker-compose up -d Then open `http://localhost:8080` in your browser! Choosing Your Version[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#choosing-your-version "Direct link to Choosing Your Version") -------------------------------------------------------------------------------------------------------------------------------------------------- | Version | Tag | What's Included | Best For | | --- | --- | --- | --- | | **Standard** | `latest` | All PDF features | Most users, balanced features & size | | **Fat** | `latest-fat` | Everything + extra fonts & tools | Highest quality conversions, full format support | | **Ultra-Lite** | `latest-ultra-lite` | Core features only | Limited resources, minimal size | **Most users should use `latest`** - it has everything you need. ### When to use each version:[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#when-to-use-each-version "Direct link to When to use each version:") **Standard (`latest`)** - You want all PDF features, have normal server specs, or you're not sure which to pick. **Fat (`latest-fat`)** - You need the highest quality conversions with full font support, every conversion format, and all optional tools. Disk space isn't a concern. **Ultra-Lite (`latest-ultra-lite`)** - Running on very limited hardware (Raspberry Pi, low-end VPS), want fastest startup, or only need basic PDF operations. To use a different version, just change the tag: docker run -d stirlingtools/stirling-pdf:latest-ultra-lite Full Setup (With All Features)[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#full-setup-with-all-features "Direct link to Full Setup (With All Features)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Want OCR, custom settings, and logging? Add more volumes: * docker run * docker-compose 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 LANGS=en_GB \ stirlingtools/stirling-pdf:latest Create `docker-compose.yml`: services: stirling-pdf: image: stirlingtools/stirling-pdf:latest container_name: stirling-pdf ports: - '8080:8080' volumes: - ./stirling-data/tessdata:/usr/share/tessdata # OCR language files - ./stirling-data/configs:/configs # Settings & database - ./stirling-data/logs:/logs # Application logs - ./stirling-data/pipeline:/pipeline # Automation configs environment: - SECURITY_ENABLELOGIN=false # Set true to enable user authentication - LANGS=en_GB # Interface language restart: unless-stopped Then run: docker-compose up -d **What each volume does:** * `/configs` - Your settings and database * `/usr/share/tessdata` - OCR language files * `/logs` - Application logs * `/pipeline` - Automation configurations Updating Stirling PDF[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#updating-stirling-pdf "Direct link to Updating Stirling PDF") -------------------------------------------------------------------------------------------------------------------------------------------------- * docker run * docker-compose docker stop stirling-pdfdocker rm stirling-pdfdocker pull stirlingtools/stirling-pdf:latest# Then run your original docker run command docker-compose downdocker-compose pulldocker-compose up -d Your data is safe in the volumes and will persist across updates. Common Configurations[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#common-configurations "Direct link to Common Configurations") -------------------------------------------------------------------------------------------------------------------------------------------------- ### Enable User Authentication[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#enable-user-authentication "Direct link to Enable User Authentication") environment: - SECURITY_ENABLELOGIN=true ### Change Interface Language[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#change-interface-language "Direct link to Change Interface Language") environment: - LANGS=es_ES # Spanish, or en_GB, fr_FR, de_DE, etc. ### Custom Port[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#custom-port "Direct link to Custom Port") ports: - '9000:8080' # Access at http://localhost:9000 Next Steps[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#next-steps "Direct link to Next Steps") ----------------------------------------------------------------------------------------------------------------- * **Add OCR Languages**: See [OCR Configuration](https://docs.stirlingpdf.com/Configuration/OCR) * **Enable Authentication**: See [Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) * **Setup Automation**: See [Pipeline Configuration](https://docs.stirlingpdf.com/Configuration/Pipeline) * **More Settings**: See [Configuration](https://docs.stirlingpdf.com/Configuration) Troubleshooting[​](https://docs.stirlingpdf.com/Installation/Docker%20Install#troubleshooting "Direct link to Troubleshooting") -------------------------------------------------------------------------------------------------------------------------------- **Can't access at localhost:8080?** * Check if port 8080 is already in use * Try a different port: `-p 9000:8080` * Check firewall settings **Permission errors with volumes?** * Make sure the directories exist * Check folder permissions: `chmod -R 755 ./stirling-data` **Container keeps restarting?** * Check logs: `docker logs stirling-pdf` * Check system resources (RAM, disk space) * Try ultra-lite version for limited hardware * [Quick Start](https://docs.stirlingpdf.com/Installation/Docker%20Install#quick-start) * [Choosing Your Version](https://docs.stirlingpdf.com/Installation/Docker%20Install#choosing-your-version) * [When to use each version:](https://docs.stirlingpdf.com/Installation/Docker%20Install#when-to-use-each-version) * [Full Setup (With All Features)](https://docs.stirlingpdf.com/Installation/Docker%20Install#full-setup-with-all-features) * [Updating Stirling PDF](https://docs.stirlingpdf.com/Installation/Docker%20Install#updating-stirling-pdf) * [Common Configurations](https://docs.stirlingpdf.com/Installation/Docker%20Install#common-configurations) * [Enable User Authentication](https://docs.stirlingpdf.com/Installation/Docker%20Install#enable-user-authentication) * [Change Interface Language](https://docs.stirlingpdf.com/Installation/Docker%20Install#change-interface-language) * [Custom Port](https://docs.stirlingpdf.com/Installation/Docker%20Install#custom-port) * [Next Steps](https://docs.stirlingpdf.com/Installation/Docker%20Install#next-steps) * [Troubleshooting](https://docs.stirlingpdf.com/Installation/Docker%20Install#troubleshooting) --- # Contribution guidelines | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Contribute/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Thanks for taking a look at how to contribute to Stirling PDFs open-source codebase Please checkout our GitHub documentation Adding/Update translations[​](https://docs.stirlingpdf.com/1.5/Contribute/#addingupdate-translations "Direct link to Adding/Update translations") -------------------------------------------------------------------------------------------------------------------------------------------------- See [How To Add New Language guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md) Wanting to contribute to our codebase[​](https://docs.stirlingpdf.com/1.5/Contribute/#wanting-to-contribute-to-our-codebase "Direct link to Wanting to contribute to our codebase") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ See our [CONTRIBUTING guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) * [Adding/Update translations](https://docs.stirlingpdf.com/1.5/Contribute/#addingupdate-translations) * [Wanting to contribute to our codebase](https://docs.stirlingpdf.com/1.5/Contribute/#wanting-to-contribute-to-our-codebase) --- # Functionality | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/category/functionality/#__docusaurus_skipToContent_fallback) Version: 1.6.0 [📄️ The Technologies Behind Stirling PDF\ ----------------------------------------\ \ List of all technologies Stirling-PDF uses!](https://docs.stirlingpdf.com/1.5/Functionality/The%20Technologies) [📄️ Convert\ -----------\ \ List of all conversion related features](https://docs.stirlingpdf.com/1.5/Functionality/Convert/) [📄️ Miscellaneous\ -----------------\ \ List of all miscellaneous features](https://docs.stirlingpdf.com/1.5/Functionality/Miscellaneous/) [🗃️ Page Operations\ -------------------\ \ 1 item](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/) [📄️ Security\ ------------\ \ List of all Security related features](https://docs.stirlingpdf.com/1.5/Functionality/Security/) [📄️ Features - Pipeline\ -----------------------\ \ Pipeline Feature overview](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline) --- # FAQ | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/FAQ/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page ### Q1: Why are .htm files being downloaded when I use the application?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q1-why-are-htm-files-being-downloaded-when-i-use-the-application "Direct link to Q1: Why are .htm files being downloaded when I use the application?") This is often caused by your NGINX configuration. NGINX's default file upload size is 1MB, and any file larger than this will cause an .htm file to be downloaded instead. To fix this issue, you should modify your NGINX configuration to increase the maximum file upload size. ### Q2: Can I customize the appearance and language of the Stirling PDF application?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q2-can-i-customize-the-appearance-and-language-of-the-stirling-pdf-application "Direct link to Q2: Can I customize the appearance and language of the Stirling PDF application?") Yes, Stirling PDF provides several environment variables to allow customization of the application, custom HTML, CSS and other settings such as the visibility to search engines. Please refer to the [UI Customisation](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation) section for more details. ### Q3: I want to add a new feature to Stirling PDF. How can I contribute?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q3-i-want-to-add-a-new-feature-to-stirling-pdf-how-can-i-contribute "Direct link to Q3: I want to add a new feature to Stirling PDF. How can I contribute?") We welcome contributions from the community! Please open an issue on our GitHub page to discuss any large features before making any changes. Any small changes are fully welcome without discussion! After the feature has been discussed and approved, you can make the changes and submit a pull request. ### Q4: I have a cool idea can you add it?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q4-i-have-a-cool-idea-can-you-add-it "Direct link to Q4: I have a cool idea can you add it?") All feedback and suggestions are appreciated. It is best to submit these via a Github issue ticket with \[Feature Request\] in the title. You can also reach out in discord but without a ticket to track it the request can often get lost! ### Q5: I found a bug in Stirling PDF. Where can I report it?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q5-i-found-a-bug-in-stirling-pdf-where-can-i-report-it "Direct link to Q5: I found a bug in Stirling PDF. Where can I report it?") Please report any bugs or issues you encounter through our GitHub Issues page. Be sure to include as much detail as possible so we can diagnose and resolve the issue quickly. ### Q6: My Stirling-PDF Using high RAM at idle, How can I optimize memory usage?[​](https://docs.stirlingpdf.com/1.5/FAQ/#q6-my-stirling-pdf-using-high-ram-at-idle-how-can-i-optimize-memory-usage "Direct link to Q6: My Stirling-PDF Using high RAM at idle, How can I optimize memory usage?") Stirling-PDF's memory usage can be optimized in several ways: Disable security features: Set DOCKER\_ENABLE\_SECURITY=false to reduce RAM consumption. This can significantly lower memory usage, especially during idle periods. Use the Ultra Lite version: Pull the latest-ultra-lite tag from Docker Hub or GitHub, which is specifically designed for lower-end hardware. ### Q7: I'm experiencing connection errors when pulling from docker.stirlingpdf.com[​](https://docs.stirlingpdf.com/1.5/FAQ/#q7-im-experiencing-connection-errors-when-pulling-from-dockerstirlingpdfcom "Direct link to Q7: I'm experiencing connection errors when pulling from docker.stirlingpdf.com") If you experience connection issues, use these alternative endpoints: * Docker Hub: `docker pull stirlingtools/stirling-pdf:latest` * GitHub: `docker pull ghcr.io/stirling-tools/stirling-pdf:latest` All endpoints provide the same functionality. * [Q1: Why are .htm files being downloaded when I use the application?](https://docs.stirlingpdf.com/1.5/FAQ/#q1-why-are-htm-files-being-downloaded-when-i-use-the-application) * [Q2: Can I customize the appearance and language of the Stirling PDF application?](https://docs.stirlingpdf.com/1.5/FAQ/#q2-can-i-customize-the-appearance-and-language-of-the-stirling-pdf-application) * [Q3: I want to add a new feature to Stirling PDF. How can I contribute?](https://docs.stirlingpdf.com/1.5/FAQ/#q3-i-want-to-add-a-new-feature-to-stirling-pdf-how-can-i-contribute) * [Q4: I have a cool idea can you add it?](https://docs.stirlingpdf.com/1.5/FAQ/#q4-i-have-a-cool-idea-can-you-add-it) * [Q5: I found a bug in Stirling PDF. Where can I report it?](https://docs.stirlingpdf.com/1.5/FAQ/#q5-i-found-a-bug-in-stirling-pdf-where-can-i-report-it) * [Q6: My Stirling-PDF Using high RAM at idle, How can I optimize memory usage?](https://docs.stirlingpdf.com/1.5/FAQ/#q6-my-stirling-pdf-using-high-ram-at-idle-how-can-i-optimize-memory-usage) * [Q7: I'm experiencing connection errors when pulling from docker.stirlingpdf.com](https://docs.stirlingpdf.com/1.5/FAQ/#q7-im-experiencing-connection-errors-when-pulling-from-dockerstirlingpdfcom) --- # Analytics and Telemetry | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > Please note all the following applies to version 1.5.0 onward due to be released 15th October Stirling‑PDF uses analytics to understand usage patterns and improve the application. This page explains what data is collected, why we collect it, and how to disable analytics if desired. > **User control**: All analytics are **opt‑in via a consent banner** (Disabled unless user allows) unless a self‑hosted administrator disables analytics system‑wide. If analytics are disabled system‑wide, no banner is shown. Overview[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#overview "Direct link to Overview") ------------------------------------------------------------------------------------------------------ Stirling‑PDF uses two analytics services: 1. **[Scarf](https://scarf.sh/) ** — a privacy‑friendly tool designed for open‑source projects. 2. **[PostHog](https://posthog.com/) ** — an open‑source product analytics platform for detailed usage insights. Both services are designed with privacy in mind and can be completely disabled. * * * PostHog Analytics[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#posthog-analytics "Direct link to PostHog Analytics") --------------------------------------------------------------------------------------------------------------------------------- ### What is PostHog?[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#what-is-posthog "Direct link to What is PostHog?") PostHog is an open‑source product analytics platform that provides detailed insights into how users interact with Stirling‑PDF. It's hosted on PostHog's European servers (`eu.i.posthog.com`) for GDPR alignment. ### Data collected by PostHog[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-collected-by-posthog "Direct link to Data collected by PostHog") PostHog collects comprehensive system and usage information **only when analytics are enabled and consented**: #### System information[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#system-information "Direct link to System information") * Operating system name and version * Java version and vendor * CPU cores and memory allocation * Deployment type (Docker, JAR, EXE) * Docker/Kubernetes environment details (if applicable) * Timezone and locale settings #### Application configuration[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#application-configuration "Direct link to Application configuration") * Security settings (login enabled, OAuth/SAML configuration status) * UI customization settings * Feature flags and enabled functionality * Legal document URLs (terms, privacy policy, etc.) * System limits and quotas #### Usage data[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#usage-data "Direct link to Usage data") * Aggregate counts (e.g., total number of user accounts created) * Feature/tool usage (which tools/operations are used) * Error tracking * Browser and device information (for the web interface) **Important privacy notes**: * **No document content, PDF data, or file metadata is ever collected or transmitted.** * PostHog is configured with: * `opt_out_capturing_by_default: true` * `mask_all_text: true` * `mask_all_element_attributes: true` * Users must accept cookies before any data is captured. * Data is stored on EU servers. * Each instance has a unique UUID (not tied to individuals). ### Why we use PostHog[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#why-we-use-posthog "Direct link to Why we use PostHog") PostHog analytics help us: * Understand which features are most valuable * Identify and fix bugs proactively * Improve user experience based on actual usage patterns * Prioritize feature development * Ensure compatibility across different environments * Monitor application health and performance * * * Scarf[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#scarf "Direct link to Scarf") --------------------------------------------------------------------------------------------- ### What is Scarf?[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#what-is-scarf "Direct link to What is Scarf?") [Scarf](https://scarf.sh/) provides a simple tracking pixel (`pixel.stirlingpdf.com`) that collects basic, non‑personally identifiable information about Stirling‑PDF usage. ### Data collected by Scarf[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-collected-by-scarf "Direct link to Data collected by Scarf") The Scarf pixel collects the following information: * **Machine Type**: Deployment type (Docker, JAR, or EXE) * **App Version**: The version of Stirling‑PDF you're running * **License Type**: Whether you're using Community or Enterprise edition * **Login Enabled**: Whether authentication is enabled * **Page Endpoint Loaded**: Which Stirling‑PDF page was loaded (e.g., `/split-pdf`) **Important**: The Scarf pixel does **not** collect or store: * Personal information (PII) * IP addresses (IP addresses are not stored) * User‑specific identifiers * Document content or file metadata * Fine‑grained user behavior beyond which page/endpoint was loaded ### Why we use Scarf[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#why-we-use-scarf "Direct link to Why we use Scarf") Scarf helps us understand: * Which deployment types are most common * Version adoption rates * Which pages/tools are reached across different configurations This data helps prioritize development efforts and ensure compatibility across deployment scenarios. ### How to disable Scarf[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#how-to-disable-scarf "Direct link to How to disable Scarf") Scarf is opt‑in by default (via the cookie consent banner). To disable the Scarf tracking pixel **system‑wide** and suppress the banner for it: **Environment variable** SYSTEM_DISABLEPIXEL=true **settings.yml** system: disablePixel: true * * * Configuration and Control[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#configuration-and-control "Direct link to Configuration and Control") --------------------------------------------------------------------------------------------------------------------------------------------------------- Analytics are governed by a **global master toggle**, **component toggles**, and the **cookie consent banner**. ### 1) Global analytics toggle (master switch)[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#1-global-analytics-toggle-master-switch "Direct link to 1) Global analytics toggle (master switch)") Controls **all** analytics and whether a consent banner appears. **Environment variable** SYSTEM_ENABLEANALYTICS=false # true | false | (unset = null) **settings.yml** system: enableAnalytics: false # true | false | null (unset) **Behavior** * `false`: Disables **all** analytics (no consent banner; PostHog & Scarf are off). * `true`: Allows analytics (banner still required for user consent before any capture). * `null`/unset: **First‑run admin choice** — on the first ever connection to a self‑hosted instance, the first visitor (assumed admin) is prompted to choose, and that choice sets the global behavior for all users (either disabling analytics or enabling the consent banner for others). ### 2) Component toggles[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#2-component-toggles "Direct link to 2) Component toggles") Use these to selectively enable/disable providers **in addition** to the global toggle. **PostHog** SYSTEM_ENABLEPOSTHOG=false system: enablePosthog: false # true | false | null **Scarf tracking pixel** SYSTEM_DISABLEPIXEL=true system: disablePixel: true # true | false **Interaction** * If `enableAnalytics` is `false`, everything is off regardless of component toggles. * If `enableAnalytics` is `true`/`null`, the consent banner is shown (see below). After consent: * PostHog runs only if `enablePosthog` is `true`/`null` **and** the user consented. * Scarf runs only if `disablePixel` is `false` **and** the user consented. ### 3) Cookie consent banner[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#3-cookie-consent-banner "Direct link to 3) Cookie consent banner") When analytics are allowed globally (`system.enableAnalytics: true` or resolved via the first‑run admin choice), users see a cookie consent banner on their first visit. Users can: * **Accept all** → enables PostHog (if `enablePosthog` is `true`/`null`) and Scarf (if `disablePixel: false`) * **Accept only necessary** → disables PostHog and Scarf * **Customize** → granular selection where applicable **User control details** * Users can change preferences at any time. * Consent choices are stored locally in the user's browser. * PostHog and Scarf respect the consent decision immediately. * No tracking occurs until explicit consent is given. * * * Complete analytics disable (shortcut)[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#complete-analytics-disable-shortcut "Direct link to Complete analytics disable (shortcut)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you want to disable **all** analytics and telemetry (and suppress any consent prompts) at once: **Environment variable** SYSTEM_ENABLEANALYTICS=false **settings.yml** system: enableAnalytics: false **Docker Compose example** services: stirling-pdf: environment: - SYSTEM_ENABLEANALYTICS=false # ... other configuration * * * Privacy and Data Security[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#privacy-and-data-security "Direct link to Privacy and Data Security") --------------------------------------------------------------------------------------------------------------------------------------------------------- ### Data retention[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-retention "Direct link to Data retention") * PostHog data is retained according to PostHog’s configured retention policies. * Scarf pixel data is aggregated and anonymized. * No personal documents or content are ever transmitted. ### GDPR alignment[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#gdpr-alignment "Direct link to GDPR alignment") * PostHog servers are located in the EU. * Cookie consent is required before tracking. * Users can opt out at any time. * No cross‑site tracking or fingerprinting. * Text and element masking helps prevent accidental PII collection. ### Transparency[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#transparency "Direct link to Transparency") * All analytics‑related code is open source and visible in the repository. * Analytics can be completely disabled with simple configuration changes. * Users have full control over their data via cookie preferences (when analytics are allowed globally). * * * For Self‑Hosted Instances[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#for-selfhosted-instances "Direct link to For Self‑Hosted Instances") -------------------------------------------------------------------------------------------------------------------------------------------------------- If you're running Stirling‑PDF on your own infrastructure: 1. **Private networks**: Analytics from self‑hosted instances help us understand deployment patterns but don't expose your internal network. 2. **Air‑gapped environments**: Disable analytics; the application works perfectly without external connections. 3. **Corporate environments**: Disable analytics if your security policy requires it, or allow it to help improve the product. * * * Support[​](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#support "Direct link to Support") --------------------------------------------------------------------------------------------------- If you have questions or concerns about analytics: * Check our [Privacy Policy](https://www.stirlingpdf.com/privacy-policy) * Review the [source code](https://github.com/Stirling-Tools/Stirling-PDF) * Ask questions on [Discord](https://discord.gg/HYmhKj45pU) * Open an issue on [GitHub](https://github.com/Stirling-Tools/Stirling-PDF/issues) * [Overview](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#overview) * [PostHog Analytics](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#posthog-analytics) * [What is PostHog?](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#what-is-posthog) * [Data collected by PostHog](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-collected-by-posthog) * [Why we use PostHog](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#why-we-use-posthog) * [Scarf](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#scarf) * [What is Scarf?](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#what-is-scarf) * [Data collected by Scarf](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-collected-by-scarf) * [Why we use Scarf](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#why-we-use-scarf) * [How to disable Scarf](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#how-to-disable-scarf) * [Configuration and Control](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#configuration-and-control) * [1) Global analytics toggle (master switch)](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#1-global-analytics-toggle-master-switch) * [2) Component toggles](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#2-component-toggles) * [3) Cookie consent banner](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#3-cookie-consent-banner) * [Complete analytics disable (shortcut)](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#complete-analytics-disable-shortcut) * [Privacy and Data Security](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#privacy-and-data-security) * [Data retention](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#data-retention) * [GDPR alignment](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#gdpr-alignment) * [Transparency](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#transparency) * [For Self‑Hosted Instances](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#for-selfhosted-instances) * [Support](https://docs.stirlingpdf.com/1.5/analytics-telemetry/#support) --- # API | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/API/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF exposes a simple API for easy integration with external scripts. You can access the API documentation in two ways: 1. Local Swagger UI at `/swagger-ui/index.html` on your Stirling-PDF instance 2. Online [Swagger Documentation](https://app.swaggerhub.com/apis-docs/Frooodle/Stirling-PDF/) You can also access the documentation through the settings menu (gear icon in the top-right corner). Accessing API Documentation[​](https://docs.stirlingpdf.com/1.5/API/#accessing-api-documentation "Direct link to Accessing API Documentation") ----------------------------------------------------------------------------------------------------------------------------------------------- ### Local Swagger UI[​](https://docs.stirlingpdf.com/1.5/API/#local-swagger-ui "Direct link to Local Swagger UI") Your Stirling-PDF instance includes built-in API documentation: 1. Navigate to `http://your-instance:port/swagger-ui/index.html` 2. Or append `/swagger-ui/index.html` to your Stirling-PDF URL 3. This provides an interactive documentation interface where you can: * View all available endpoints * Test API calls directly * See request/response schemas * View authentication requirements ### Settings Menu Access[​](https://docs.stirlingpdf.com/1.5/API/#settings-menu-access "Direct link to Settings Menu Access") 1. Click the gear icon (⚙️) in the top-right corner 2. Look for the "API Documentation" or "API" link 3. This will take you to the local Swagger UI API Authentication[​](https://docs.stirlingpdf.com/1.5/API/#api-authentication "Direct link to API Authentication") -------------------------------------------------------------------------------------------------------------------- When security is enabled, all API requests require authentication. There are two ways to handle API authentication: ### User-Specific API Keys[​](https://docs.stirlingpdf.com/1.5/API/#user-specific-api-keys "Direct link to User-Specific API Keys") 1. Obtain your API key: * Log into Stirling-PDF * Go to Account Settings (via the gear icon) * Find your API key in the account details ### Global API Key[​](https://docs.stirlingpdf.com/1.5/API/#global-api-key "Direct link to Global API Key") You can set a custom global API key using the environment variable: SECURITY_CUSTOMGLOBALAPIKEY=your-custom-api-key This allows you to set a single API key that works regardless of user authentication. 2. Include the API key in all requests: X-API-KEY: your-api-key-here 3. Example authenticated request: curl -X POST "http://localhost:8080/add-watermark" \ -H "X-API-KEY: your-api-key-here" \ -H "Content-Type: multipart/form-data" \ ... API Limitations[​](https://docs.stirlingpdf.com/1.5/API/#api-limitations "Direct link to API Limitations") ----------------------------------------------------------------------------------------------------------- Stirling-PDF's feature set is not entirely confined to the backend, hence not all functionalities are accessible via the API. Certain operations, such as the "view-pdf" or "visually sign", are executed exclusively on the front-end, and as such, they are only available through the Web-UI. If you encounter a situation where some API endpoints appear to be absent, it is likely attributable to these front-end exclusive features. Stirling-PDF also has statistic and health endpoints to integrate with monitoring/dashboard applications. Example CURL Commands[​](https://docs.stirlingpdf.com/1.5/API/#example-curl-commands "Direct link to Example CURL Commands") ----------------------------------------------------------------------------------------------------------------------------- * Unix/Linux/MacOS * Windows CMD curl -X POST "http://localhost:8080/add-watermark" \ -H "Content-Type: multipart/form-data" \ -F "fileInput=@/Users/username/Downloads/sample-1_cropped.pdf" \ -F "watermarkType=text" \ -F "watermarkText=YOUR_WATERMARK_TEXT" \ -F "alphabet=roman" \ -F "fontSize=30" \ -F "rotation=0" \ -F "opacity=0.5" \ -F "widthSpacer=50" \ -F "heightSpacer=50" \ > "/Users/username/Downloads/output.pdf" curl -X POST "http://localhost:8080/add-watermark" ^ -H "Content-Type: multipart/form-data" ^ -F "fileInput=@C:\Users\systo\Downloads\sample-1_cropped.pdf" ^ -F "watermarkType=text" ^ -F "watermarkText=YOUR_WATERMARK_TEXT" ^ -F "alphabet=roman" ^ -F "fontSize=30" ^ -F "rotation=0" ^ -F "opacity=0.5" ^ -F "widthSpacer=50" ^ -F "heightSpacer=50" ^ > "C:\Users\systo\Downloads\output.pdf" * [Accessing API Documentation](https://docs.stirlingpdf.com/1.5/API/#accessing-api-documentation) * [Local Swagger UI](https://docs.stirlingpdf.com/1.5/API/#local-swagger-ui) * [Settings Menu Access](https://docs.stirlingpdf.com/1.5/API/#settings-menu-access) * [API Authentication](https://docs.stirlingpdf.com/1.5/API/#api-authentication) * [User-Specific API Keys](https://docs.stirlingpdf.com/1.5/API/#user-specific-api-keys) * [Global API Key](https://docs.stirlingpdf.com/1.5/API/#global-api-key) * [API Limitations](https://docs.stirlingpdf.com/1.5/API/#api-limitations) * [Example CURL Commands](https://docs.stirlingpdf.com/1.5/API/#example-curl-commands) --- # Versions | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Versions/#__docusaurus_skipToContent_fallback) On this page Stirling PDF is available in several formats, each catering to different needs and use cases: Docker Versions[​](https://docs.stirlingpdf.com/Installation/Versions/#docker-versions "Direct link to Docker Versions") ------------------------------------------------------------------------------------------------------------------------- For server deployments, we offer three pre-configured Docker images: * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest-fat?label=Stirling-PDF%20Fat) * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest?label=Stirling-PDF%20Full) * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest-ultra-lite?label=Stirling-PDF%20Ultra-Lite) * **Fat**: Includes all Full features plus additional fonts and pre-bundled jar security version * **Full**: All features pre-configured and ready to use * **Ultra-Lite**: Minimal installation with core features only Desktop Versions (Windows & Unix)[​](https://docs.stirlingpdf.com/Installation/Versions/#desktop-versions-windows--unix "Direct link to Desktop Versions (Windows & Unix)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The desktop versions of Stirling PDF use a dynamic feature system. They start with Ultra-Lite features as the base and automatically enable additional functionality based on installed dependencies: Base Features (Ultra-Lite): * Core PDF operations (merge, split, rotate, etc.) * Basic conversions * Password protection * All features marked with ✔️ in the Ultra-Lite column below Additional features become available automatically when you install: * LibreOffice: Enables document format conversions (PDF to Word, Excel, etc.) * Tesseract: Enables OCR functionality * QPDF: Enables compression and repair features * Other dependencies: Enable their respective features Feature Comparison[​](https://docs.stirlingpdf.com/Installation/Versions/#feature-comparison "Direct link to Feature Comparison") ---------------------------------------------------------------------------------------------------------------------------------- Here are the different technologies each version uses: | Technology | Ultra-Lite | Full | | --- | --- | --- | | Java | ✔️ | ✔️ | | JavaScript | ✔️ | ✔️ | | Libre | | ✔️ | | Python | | ✔️ | | OpenCV | | ✔️ | | Tesseract | | ✔️ | And here you see what functions are offered as part of each. | Operation | Ultra-Lite | Full | | --- | --- | --- | | add-page-numbers | ✔️ | ✔️ | | add-password | ✔️ | ✔️ | | add-image | ✔️ | ✔️ | | add-watermark | ✔️ | ✔️ | | adjust-contrast | ✔️ | ✔️ | | auto-split-pdf | ✔️ | ✔️ | | auto-redact | ✔️ | ✔️ | | auto-rename | ✔️ | ✔️ | | cert-sign | ✔️ | ✔️ | | crop | ✔️ | ✔️ | | change-metadata | ✔️ | ✔️ | | change-permissions | ✔️ | ✔️ | | compare | ✔️ | ✔️ | | extract-page | ✔️ | ✔️ | | extract-images | ✔️ | ✔️ | | flatten | ✔️ | ✔️ | | get-info-on-pdf | ✔️ | ✔️ | | img-to-pdf | ✔️ | ✔️ | | markdown-to-pdf | ✔️ | ✔️ | | merge-pdfs | ✔️ | ✔️ | | multi-page-layout | ✔️ | ✔️ | | overlay-pdf | ✔️ | ✔️ | | pdf-organizer | ✔️ | ✔️ | | pdf-to-csv | ✔️ | ✔️ | | pdf-to-img | ✔️ | ✔️ | | pdf-to-single-page | ✔️ | ✔️ | | remove-blanks | ✔️ | ✔️ | | remove-pages | ✔️ | ✔️ | | remove-password | ✔️ | ✔️ | | rotate-pdf | ✔️ | ✔️ | | sanitize-pdf | ✔️ | ✔️ | | scale-pages | ✔️ | ✔️ | | sign | ✔️ | ✔️ | | show-javascript | ✔️ | ✔️ | | split-by-size-or-count | ✔️ | ✔️ | | split-pdf-by-sections | ✔️ | ✔️ | | split-pdfs | ✔️ | ✔️ | | compress-pdf | | ✔️ | | extract-image-scans | | ✔️ | | ocr-pdf | | ✔️ | | pdf-to-pdfa | | ✔️ | | pdf-to-text | ✔️ | ✔️ | | pdf-to-html | | ✔️ | | pdf-to-word | | ✔️ | | pdf-to-presentation | | ✔️ | | pdf-to-xml | | ✔️ | | remove-annotations | ✔️ | ✔️ | | remove-cert-sign | ✔️ | ✔️ | | remove-image-pdf | ✔️ | ✔️ | | file-to-pdf | | ✔️ | | xlsx-to-pdf | | ✔️ | | html-to-pdf | | ✔️ | | url-to-pdf | | ✔️ | | repair | | ✔️ | * [Docker Versions](https://docs.stirlingpdf.com/Installation/Versions/#docker-versions) * [Desktop Versions (Windows & Unix)](https://docs.stirlingpdf.com/Installation/Versions/#desktop-versions-windows--unix) * [Feature Comparison](https://docs.stirlingpdf.com/Installation/Versions/#feature-comparison) --- # Pro / Enterprise | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Pro/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF offers a Pro edition of its software. This is the same great software, but with added features and comforts. Some users who seek additional features, bulk user discounts or SLA support may want our Enterprise package. What's included in Pro[​](https://docs.stirlingpdf.com/1.5/Pro/#whats-included-in-pro "Direct link to What's included in Pro") ------------------------------------------------------------------------------------------------------------------------------- * Support tickets via [\[email protected\]](https://docs.stirlingpdf.com/cdn-cgi/l/email-protection#cbb8bebbbba4b9bf8bb8bfa2b9a7a2a5acbbafade5a8a4a6) to reach the Stirling-PDF team for support * [Advanced SSO](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) , OAuth2 and SAML with automated login handling * [External Database](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database) support for optimised deployments and load-balancing support * Custom automated metadata handling * Google Drive integration * Advanced user configurations (Coming soon) * Plus other exciting features to come. What's included in Enterprise[​](https://docs.stirlingpdf.com/1.5/Pro/#whats-included-in-enterprise "Direct link to What's included in Enterprise") ---------------------------------------------------------------------------------------------------------------------------------------------------- * Prioritised Support tickets via [\[email protected\]](https://docs.stirlingpdf.com/cdn-cgi/l/email-protection#92e1e7e2e2fde0e6d2e1e6fbe0fefbfcf5e2f6f4bcf1fdff) to reach the Stirling-PDF team for support and 1:1 meetings where applicable (Provided they come from the same email domain registered with us) * Prioritised Enhancements to Stirling-PDF where applicable * Prometheus endpoint for advancing Usage monitoring * Usage Monitoring UI * Audit logs (Coming very soon) Cost[​](https://docs.stirlingpdf.com/1.5/Pro/#cost "Direct link to Cost") -------------------------------------------------------------------------- We charge 12$ per seat per month. This followed the 'Named User' model, meaning a company that requires 5 unique users logged in at any time would require 5 seats. Purchase[​](https://docs.stirlingpdf.com/1.5/Pro/#purchase "Direct link to Purchase") -------------------------------------------------------------------------------------- To purchase stirling PDF Pro, please navigate to [https://stirlingpdf.com/pricing](https://stirlingpdf.com/pricing) and select either Pro or Enterprise, depending on your use-case. For Pro, you will be redirected to Stripe to set up and handle a subscription, after which you will be automatically emailed your license key at the email provided to Stripe. Activation[​](https://docs.stirlingpdf.com/1.5/Pro/#activation "Direct link to Activation") -------------------------------------------------------------------------------------------- To activate, navigate to the Stirling PDF config folder and open the `settings.yml` Scroll down to the enterprise section, it should look like: premium: key: 00000000-0000-0000-0000-000000000000 enabled: false # Enable license key checks for pro/enterprise features Enter the general license key provided in the email received from purchasing Stirling PDF Pro and change enabled from false to true, then restart the Stirling-PDF instance. You should now see logs of your Stirling-PDF instance registering and authenticating the license and enabling the Pro features. If you need your application to be in a 100% offline air-gapped environment and are unable to authenticate a license key, we also offer a certificate file, which can be provided on request (For enterprise users only) in the format premium: key: file:config/cert.crt enabled: false # Enable license key checks for pro/enterprise features Under these settings, you will be able to customise other premium features such as premium: proFeatures: SSOAutoLogin: false CustomMetadata: autoUpdateMetadata: false author: username creator: Stirling-PDF producer: Stirling-PDF googleDrive: enabled: false clientId: '' apiKey: '' appId: '' ![Analytics Pixel](https://static.scarf.sh/a.png?x-pxid=421cf4e2-5028-4383-913e-31afed203780) * [What's included in Pro](https://docs.stirlingpdf.com/1.5/Pro/#whats-included-in-pro) * [What's included in Enterprise](https://docs.stirlingpdf.com/1.5/Pro/#whats-included-in-enterprise) * [Cost](https://docs.stirlingpdf.com/1.5/Pro/#cost) * [Purchase](https://docs.stirlingpdf.com/1.5/Pro/#purchase) * [Activation](https://docs.stirlingpdf.com/1.5/Pro/#activation) --- # Convert | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Convert/#__docusaurus_skipToContent_fallback) On this page Convert between PDF and 50+ file formats including documents, images, web pages, and more. * * * How to Use[​](https://docs.stirlingpdf.com/Functionality/Convert/#how-to-use "Direct link to How to Use") ---------------------------------------------------------------------------------------------------------- 1. **Select conversion type** - Choose what you're converting from and to 2. **Upload files** - Add one or multiple files 3. **Configure options** - Adjust quality, DPI, layout (optional) 4. **Convert** - Process and download * * * Supported Conversions[​](https://docs.stirlingpdf.com/Functionality/Convert/#supported-conversions "Direct link to Supported Conversions") ------------------------------------------------------------------------------------------------------------------------------------------- ### Convert TO PDF[​](https://docs.stirlingpdf.com/Functionality/Convert/#convert-to-pdf "Direct link to Convert TO PDF") | Category | Formats | | --- | --- | | **Office** | DOCX, DOC, ODT, XLSX, XLS, ODS, PPTX, PPT, ODP, TXT, RTF | | **Images** | JPG, JPEG, PNG, GIF, BMP, TIFF, WEBP, SVG | | **Web** | HTML (with CSS/images via ZIP), URL, Markdown | | **Email** | EML | | **Comics** | CBZ, CBR | ### Convert FROM PDF[​](https://docs.stirlingpdf.com/Functionality/Convert/#convert-from-pdf "Direct link to Convert FROM PDF") | Category | Formats | | --- | --- | | **Office** | DOCX, ODT, PPTX, ODP, TXT, RTF, Markdown | | **Images** | PNG, JPG, GIF, TIFF, BMP, WEBP | | **Data** | CSV, HTML, XML | | **Archival** | PDF/A | | **Comics** | CBZ, CBR | * * * Conversion Options[​](https://docs.stirlingpdf.com/Functionality/Convert/#conversion-options "Direct link to Conversion Options") ---------------------------------------------------------------------------------------------------------------------------------- ### Image Settings (when converting to/from images)[​](https://docs.stirlingpdf.com/Functionality/Convert/#image-settings-when-converting-tofrom-images "Direct link to Image Settings (when converting to/from images)") * **DPI:** 72 (screen), 150 (standard), 300 (print) * **Color Mode:** Color, Grayscale, Black & White * **Layout:** Fit to page, maintain aspect ratio, fill page * **Output:** Single PDF or separate files ### PDF to Word / Office[​](https://docs.stirlingpdf.com/Functionality/Convert/#pdf-to-word--office "Direct link to PDF to Word / Office") * Works best with digital PDFs (not scanned images) * For scanned PDFs, run [OCR](https://docs.stirlingpdf.com/Functionality/OCR) first * Complex layouts may need manual adjustment after conversion ### PDF to CSV[​](https://docs.stirlingpdf.com/Functionality/Convert/#pdf-to-csv "Direct link to PDF to CSV") * Works best with simple, well-structured tables in digital PDFs * Not reliable for scanned documents * * * API Usage[​](https://docs.stirlingpdf.com/Functionality/Convert/#api-usage "Direct link to API Usage") ------------------------------------------------------------------------------------------------------- * Image to PDF * PDF to Word curl -X POST http://stirling-pdf:8080/api/v1/convert/img/pdf \ -F "[email protected]" \ -F "colorType=color" \ -F "fitOption=maintainAspectRatio" \ -o output.pdf curl -X POST http://stirling-pdf:8080/api/v1/convert/pdf/word \ -F "[email protected]" \ -o output.docx See [API Documentation](https://docs.stirlingpdf.com/API) for complete endpoint reference. * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/Convert/#related-tools "Direct link to Related Tools") ------------------------------------------------------------------------------------------------------------------- * **[Compress](https://docs.stirlingpdf.com/Functionality/Compress) ** - Reduce file size after conversion * **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** - Make scanned PDFs searchable before converting * **[Merge](https://docs.stirlingpdf.com/Functionality/Page-Operations/) ** - Combine multiple converted PDFs * [How to Use](https://docs.stirlingpdf.com/Functionality/Convert/#how-to-use) * [Supported Conversions](https://docs.stirlingpdf.com/Functionality/Convert/#supported-conversions) * [Convert TO PDF](https://docs.stirlingpdf.com/Functionality/Convert/#convert-to-pdf) * [Convert FROM PDF](https://docs.stirlingpdf.com/Functionality/Convert/#convert-from-pdf) * [Conversion Options](https://docs.stirlingpdf.com/Functionality/Convert/#conversion-options) * [Image Settings (when converting to/from images)](https://docs.stirlingpdf.com/Functionality/Convert/#image-settings-when-converting-tofrom-images) * [PDF to Word / Office](https://docs.stirlingpdf.com/Functionality/Convert/#pdf-to-word--office) * [PDF to CSV](https://docs.stirlingpdf.com/Functionality/Convert/#pdf-to-csv) * [API Usage](https://docs.stirlingpdf.com/Functionality/Convert/#api-usage) * [Related Tools](https://docs.stirlingpdf.com/Functionality/Convert/#related-tools) --- # Page Operations | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Page-Operations/#__docusaurus_skipToContent_fallback) * `merge-pdfs`: With this feature, users can merge multiple PDF documents into a single PDF. * `split-pdfs`: This functionality enables users to split a single PDF document into multiple separate PDFs. * `reorganize-pages`: This feature gives users the ability to rearrange, add, or delete pages within a PDF document. * `extract-pages`: Extracts specific pages from a PDF document into a new separate PDF file * `rotate-pdf`: With this feature, users can rotate pages within a PDF document to their desired orientation. * `remove-pages`: This feature allows users to remove specified pages from a PDF document. * `multi-page-layout`: This functionality allows users to create a layout involving multiple pages of a PDF. * `scale-pages`: This feature enables users to adjust the scale of pages in a PDF document. * `auto-split-pdfs`: This allows a user to insert physical divider pages between their documents in their scanner to allow S-PDF to auto separate them * `adjust-contrast`: Lets the user adjust the contrast, brightness and saturation * `crop`: Allows user to crop the pages to set size * `pdf-to-single-page`: Converts multi pages PDF files into a single long pdf page. * `booklet-imposition`: Arranges PDF pages for booklet printing with proper page ordering for folding and binding. Creates printer-ready booklets with correct page sequences * `split-by-size-or-count`: Splits one or multiple PDF files into parts consisting of a maximum file size or page count definde by the user. * `overlay-pdf`: Can merge multiple PDFs into one another (ontop/behind etc) in various ways * `add-attachments`: Embed files as attachments within a PDF document. Attached files can be extracted later by PDF readers that support attachments * `split-pdf-by-sections`: Splits a page in multiple section vertically, horizontally or both. Can be used to split a page in half etc. * `add-page-numbers`: Add customizable page numbers and text to the edges of PDF pages with options for position, formatting, and page ranges. * `remove-blanks`: With this feature, users can remove blank pages from a PDF document automatically, detecting pages with little to no content. * `auto-split-pdf`: Automatically splits documents into separate files based on QR codes detected between pages. Designed for bulk scanning workflows where separator pages with QR codes are placed between documents. * `edit-table-of-contents`: Edit, add, or modify the table of contents (bookmarks) in a PDF document for better navigation. --- # Recommended Tools | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#__docusaurus_skipToContent_fallback) On this page The most frequently used PDF operations, prominently featured on the home page for quick access. * * * Multi-Tool[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#multi-tool "Direct link to Multi-Tool") -------------------------------------------------------------------------------------------------------------------- **Tool ID:** `multiTool` Page editor workspace - upload PDFs once and chain multiple page operations (rotate, reorder, delete, split) without re-uploading. **[Multi-Tool Guide →](https://docs.stirlingpdf.com/Functionality/Multi-Tool) ** * * * Merge PDFs[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#merge-pdfs "Direct link to Merge PDFs") -------------------------------------------------------------------------------------------------------------------- **Tool ID:** `merge` Combine multiple PDF documents into a single file. Drag and drop to reorder before merging. * * * Compare[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#compare "Direct link to Compare") ----------------------------------------------------------------------------------------------------------- **Tool ID:** `compare` Compare two PDF documents side-by-side with visual difference highlighting. **[Compare Guide →](https://docs.stirlingpdf.com/Functionality/Compare) ** * * * Compress[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#compress "Direct link to Compress") -------------------------------------------------------------------------------------------------------------- **Tool ID:** `compress-pdf` Reduce PDF file size (10-90% reduction) with configurable quality levels. **[Compress Guide →](https://docs.stirlingpdf.com/Functionality/Compress) ** * * * Convert[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#convert "Direct link to Convert") ----------------------------------------------------------------------------------------------------------- **Tool ID:** `convert` Convert between PDF and 50+ file formats including images, Office documents, HTML, and more. Batch conversion supported. **[Convert Guide →](https://docs.stirlingpdf.com/Functionality/Convert/) ** * * * OCR[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#ocr "Direct link to OCR") ----------------------------------------------------------------------------------------------- **Tool ID:** `ocr-pdf` Make scanned PDFs searchable by recognizing text in images. Supports 100+ languages via Tesseract OCR. **[OCR Guide →](https://docs.stirlingpdf.com/Functionality/OCR) ** * * * Redact[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#redact "Direct link to Redact") -------------------------------------------------------------------------------------------------------- **Tool ID:** `redact` Permanently remove sensitive information from PDFs. Supports manual redaction (draw boxes) and automatic redaction (text/regex patterns). **Common patterns:** * SSN: `\d{3}-\d{2}-\d{4}` * Phone: `\(\d{3}\) \d{3}-\d{4}` * Email: `[\w\.-]+@[\w\.-]+\.\w+` Redaction is permanent - original content cannot be recovered. **[Redaction Guide →](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact) ** * * * More Tools[​](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#more-tools "Direct link to More Tools") -------------------------------------------------------------------------------------------------------------------- * **[All Tools](https://docs.stirlingpdf.com/functionality) ** - Complete tool reference * **[Advanced Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools) ** - Automation, repair, overlay, and more * **[API Documentation](https://docs.stirlingpdf.com/API) ** - Programmatic access * [Multi-Tool](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#multi-tool) * [Merge PDFs](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#merge-pdfs) * [Compare](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#compare) * [Compress](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#compress) * [Convert](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#convert) * [OCR](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#ocr) * [Redact](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#redact) * [More Tools](https://docs.stirlingpdf.com/Functionality/Recommended-Tools/#more-tools) --- # Features - Security | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Security/#__docusaurus_skipToContent_fallback) On this page PDF Security Tools[​](https://docs.stirlingpdf.com/Functionality/Security/#pdf-security-tools "Direct link to PDF Security Tools") ----------------------------------------------------------------------------------------------------------------------------------- ### Password Protection[​](https://docs.stirlingpdf.com/Functionality/Security/#password-protection "Direct link to Password Protection") * **`add-password`**: Secure your PDFs by adding password protection. Supports user passwords (opens PDF) and owner passwords (controls permissions). * **`remove-password`**: Remove password protection from secured PDFs (requires the original password). ### Permissions & Access Control[​](https://docs.stirlingpdf.com/Functionality/Security/#permissions--access-control "Direct link to Permissions & Access Control") * **`change-permissions`**: Control how others can view and edit your PDFs. Set restrictions on printing, copying, editing, form filling, and more. * **`flatten`**: Flatten PDF form fields by merging them into the document, making them non-editable. Prevents further modifications to form data and interactive elements. * **`unlock-pdf-forms`**: Unlock form fields in a PDF document, allowing users to edit previously locked form fields and interactive elements. ### Signatures[​](https://docs.stirlingpdf.com/Functionality/Security/#signatures "Direct link to Signatures") * **`sign`**: Add handwritten, text, or image signatures to PDFs. Draw signatures with mouse/touchscreen, type your name, or upload signature images. For cryptographic digital signatures, use `cert-sign` instead. **Learn more:** [Sign PDF (Handwritten Signatures)](https://docs.stirlingpdf.com/Functionality/Security/Sign) * **`cert-sign`**: Digitally sign PDFs using X.509 certificates. Cryptographic signatures that prove identity and document integrity. Supports server-generated certificates, custom certificates, and organization certificates. **Learn more:** [Certificate Signing Guide](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) * **`shared-signing`** _(Pro/Enterprise, Alpha)_: Collaborative multi-participant signing workflows. A document owner uploads a PDF, invites registered users as participants, and each participant signs with their own certificate and optional wet signature. Includes progress tracking, signature summary pages, and automatic post-finalization data cleanup. **Learn more:** [Shared Signing Guide](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing) * **`validate-signature`**: Verify digital signatures and certificates in PDF documents. Check against trusted certificate chains including system trust, Adobe AATL, EU EUTL, and Mozilla CA bundle. **Learn more:** [Certificate Signing - Validation](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing#validating-signatures) * **`remove-cert-sign`**: Remove digital certificate signatures from PDFs. Useful when you need to edit a signed document. ### Content Security[​](https://docs.stirlingpdf.com/Functionality/Security/#content-security "Direct link to Content Security") * **`add-watermark`**: Add custom watermarks to PDFs. Supports text and image watermarks with configurable position, opacity, and rotation. * **`sanitize-pdf`**: Remove potentially dangerous elements from PDFs including JavaScript, embedded files, external links, fonts, and metadata. Essential for security-conscious workflows. * **`auto-redact`**: Redact (black out) sensitive information from PDFs. Supports text search and regex patterns to find and permanently remove sensitive content. ### Information & Metadata[​](https://docs.stirlingpdf.com/Functionality/Security/#information--metadata "Direct link to Information & Metadata") * **`get-info-on-pdf`**: Extract comprehensive PDF information including version, fonts, dimensions, permissions, metadata, and more. Output as JSON or visual tables. * * * Certificate Signature Validation[​](https://docs.stirlingpdf.com/Functionality/Security/#certificate-signature-validation "Direct link to Certificate Signature Validation") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Stirling PDF provides enterprise-grade PDF signature validation with configurable trust chains. ### Trust Sources[​](https://docs.stirlingpdf.com/Functionality/Security/#trust-sources "Direct link to Trust Sources") Configure which certificate authorities to trust: * **System Trust Store** - Operating system's trusted CAs * **Mozilla CA Bundle** - Mozilla's curated CA list * **Adobe AATL** - Adobe Approved Trust List * **EU EUTL** - EU Trusted List (eIDAS compliance) * **Server Certificates** - Trust server-generated certificates ### Revocation Checking[​](https://docs.stirlingpdf.com/Functionality/Security/#revocation-checking "Direct link to Revocation Checking") Verify certificates haven't been revoked: * **OCSP** - Online Certificate Status Protocol (fast, real-time) * **CRL** - Certificate Revocation Lists (works offline) * **Dual Mode** - Try OCSP first, fall back to CRL ### Configuration[​](https://docs.stirlingpdf.com/Functionality/Security/#configuration "Direct link to Configuration") security: validation: trust: serverAsAnchor: true # Trust server-generated certificates useSystemTrust: true # Use OS trust store useMozillaBundle: true # Mozilla CA bundle useAATL: false # Adobe Approved Trust List useEUTL: false # EU Trusted List allowAIA: false # Fetch intermediate certificates revocation: mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false # Fail if revocation check fails **Learn more:** [Certificate Signing - Configuration](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing#configuration-examples) * * * Related Configuration[​](https://docs.stirlingpdf.com/Functionality/Security/#related-configuration "Direct link to Related Configuration") -------------------------------------------------------------------------------------------------------------------------------------------- For advanced security configuration, see: * **[System and Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) ** - JWT, session management, server certificates * **[Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ** - Comprehensive signing and validation guide * **[Single Sign-On](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) ** - Enterprise authentication * [PDF Security Tools](https://docs.stirlingpdf.com/Functionality/Security/#pdf-security-tools) * [Password Protection](https://docs.stirlingpdf.com/Functionality/Security/#password-protection) * [Permissions & Access Control](https://docs.stirlingpdf.com/Functionality/Security/#permissions--access-control) * [Signatures](https://docs.stirlingpdf.com/Functionality/Security/#signatures) * [Content Security](https://docs.stirlingpdf.com/Functionality/Security/#content-security) * [Information & Metadata](https://docs.stirlingpdf.com/Functionality/Security/#information--metadata) * [Certificate Signature Validation](https://docs.stirlingpdf.com/Functionality/Security/#certificate-signature-validation) * [Trust Sources](https://docs.stirlingpdf.com/Functionality/Security/#trust-sources) * [Revocation Checking](https://docs.stirlingpdf.com/Functionality/Security/#revocation-checking) * [Configuration](https://docs.stirlingpdf.com/Functionality/Security/#configuration) * [Related Configuration](https://docs.stirlingpdf.com/Functionality/Security/#related-configuration) --- # Content & Editing | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Content-Editing/#__docusaurus_skipToContent_fallback) On this page Tools for adding, extracting, and modifying content within PDF documents. * * * Images[​](https://docs.stirlingpdf.com/Functionality/Content-Editing/#images "Direct link to Images") ------------------------------------------------------------------------------------------------------ * `add-image`: Add image files to your PDF documents. Insert logos, photos, or graphics with customizable position, size, and opacity. * `extract-images`: Extract all images from a PDF document. Saves each image as a separate file in common formats (PNG, JPG, etc). * `extract-image-scans`: Extract scanned images from PDF files. Specifically designed for PDFs containing scanned documents or photos. * * * Stamps & Annotations[​](https://docs.stirlingpdf.com/Functionality/Content-Editing/#stamps--annotations "Direct link to Stamps & Annotations") ----------------------------------------------------------------------------------------------------------------------------------------------- * `add-stamp`: Add user-defined text or image stamps to PDF pages with customizable position, size, rotation, and opacity. Can be applied to specific pages or all pages. * `remove-annotations`: Remove all annotations, comments, and markup from a PDF document while preserving the original content. * * * Visual Editing[​](https://docs.stirlingpdf.com/Functionality/Content-Editing/#visual-editing "Direct link to Visual Editing") ------------------------------------------------------------------------------------------------------------------------------ * `replace-color`: Replace specific colors in a PDF or invert all colors. * * * Metadata & Information[​](https://docs.stirlingpdf.com/Functionality/Content-Editing/#metadata--information "Direct link to Metadata & Information") ----------------------------------------------------------------------------------------------------------------------------------------------------- * `change-metadata`: Change the metadata of a PDF, including author name, title, subject, keywords, creation date, and more. * `get-info-on-pdf`: Extract and display comprehensive information about a PDF including: * PDF version and file size * Page count and dimensions * Fonts used * Security settings and permissions * Complete metadata * Export all information in JSON format * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/Content-Editing/#related-tools "Direct link to Related Tools") --------------------------------------------------------------------------------------------------------------------------- * **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** - Make scanned images searchable before extracting text * **[Compress](https://docs.stirlingpdf.com/Functionality/Compress) ** - Reduce file size after adding images * **[Security](https://docs.stirlingpdf.com/Functionality/Security/) ** - Add watermarks or sanitize metadata * [Images](https://docs.stirlingpdf.com/Functionality/Content-Editing/#images) * [Stamps & Annotations](https://docs.stirlingpdf.com/Functionality/Content-Editing/#stamps--annotations) * [Visual Editing](https://docs.stirlingpdf.com/Functionality/Content-Editing/#visual-editing) * [Metadata & Information](https://docs.stirlingpdf.com/Functionality/Content-Editing/#metadata--information) * [Related Tools](https://docs.stirlingpdf.com/Functionality/Content-Editing/#related-tools) --- # Compare PDFs | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Compare/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `compare` Compare two PDF documents and visually highlight word-level differences. Runs entirely in your browser - no files are sent to the server. * * * How to Use[​](https://docs.stirlingpdf.com/Functionality/Compare/#how-to-use "Direct link to How to Use") ---------------------------------------------------------------------------------------------------------- 1. **Upload Original PDF** - Select the original/older version 2. **Upload Modified PDF** - Select the new/revised version 3. **Compare** - Process the documents 4. **Review Differences** - View highlighted changes * * * Features[​](https://docs.stirlingpdf.com/Functionality/Compare/#features "Direct link to Features") ---------------------------------------------------------------------------------------------------- * **Side-by-side or stacked layout** - Toggle between horizontal and vertical views * **Word-level diff** - Removed words highlighted in red, added words highlighted in green * **Change navigation** - Dropdown selectors to jump between deletions and additions * **Synchronized scrolling** - Optional linked scrolling between the two panes * **Zoom and pan** - Scroll-wheel zoom, pinch-to-zoom, and drag to pan * * * Limitations[​](https://docs.stirlingpdf.com/Functionality/Compare/#limitations "Direct link to Limitations") ------------------------------------------------------------------------------------------------------------- * Works best with digital PDFs (not scanned). For scanned documents, run [OCR](https://docs.stirlingpdf.com/Functionality/OCR) first * Compares extracted text only - layout-only or image-only changes are not detected * Very large or highly dissimilar documents may be stopped early with a warning * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/Compare/#related-tools "Direct link to Related Tools") ------------------------------------------------------------------------------------------------------------------- * **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** - Make scanned PDFs searchable before comparing * [How to Use](https://docs.stirlingpdf.com/Functionality/Compare/#how-to-use) * [Features](https://docs.stirlingpdf.com/Functionality/Compare/#features) * [Limitations](https://docs.stirlingpdf.com/Functionality/Compare/#limitations) * [Related Tools](https://docs.stirlingpdf.com/Functionality/Compare/#related-tools) --- # Compress PDF | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Compress/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `compress-pdf` Reduce PDF file size by compressing images, optimizing structure, and removing unnecessary data. **Important:** Compression is permanent. Always keep a backup of the original if you might need maximum quality later. * * * How to Use[​](https://docs.stirlingpdf.com/Functionality/Compress/#how-to-use "Direct link to How to Use") ----------------------------------------------------------------------------------------------------------- 1. **Upload Your PDF** - Select one or more PDFs 2. **Choose Compression Level** - Select quality vs. size balance 3. **Configure Options** - Enable grayscale, line art, etc. (optional) 4. **Compress** - Process the files 5. **Download** - Get your compressed PDFs * * * Options[​](https://docs.stirlingpdf.com/Functionality/Compress/#options "Direct link to Options") -------------------------------------------------------------------------------------------------- | Option | Description | | --- | --- | | **Optimize Level** (1-9) | Controls compression aggressiveness. Higher = smaller file, lower quality. Levels 1-3 are light, 4-5 are moderate, 6+ trigger additional compression passes | | **Expected Output Size** | Set a target file size (e.g. `25MB`) and the tool will automatically adjust the optimize level to hit it | | **Grayscale** | Convert all images to grayscale. Can significantly reduce size for color documents where color isn't needed | | **Linearize** | Optimize PDF for fast web viewing - reorders the file so the first page loads before the entire file is downloaded | | **Normalize** | Normalize internal PDF structure for better compatibility | | **Line Art** | Convert images to high-contrast line art. Useful for documents with diagrams, sketches, or black-and-white illustrations | | **Line Art Threshold** (0-100) | Controls sensitivity of line art conversion. Default: 55. Only used when Line Art is enabled | | **Line Art Edge Level** (1-3) | Edge detection strength for line art. 1 = light, 3 = strong. Only used when Line Art is enabled | * * * What Happens at Each Level[​](https://docs.stirlingpdf.com/Functionality/Compress/#what-happens-at-each-level "Direct link to What Happens at Each Level") ----------------------------------------------------------------------------------------------------------------------------------------------------------- * **Levels 1-3** - Basic optimization, preserves quality * **Levels 4-5** - Image recompression enabled, moderate quality reduction * **Levels 6+** - Aggressive compression with additional processing passes * **Levels 8+** - Uses Zopfli compression on supported systems for maximum reduction * * * API Usage[​](https://docs.stirlingpdf.com/Functionality/Compress/#api-usage "Direct link to API Usage") -------------------------------------------------------------------------------------------------------- curl -X POST http://stirling-pdf:8080/api/v1/misc/compress-pdf \ -F "[email protected]" \ -F "optimizeLevel=5" \ -F "grayscale=false" \ -F "linearize=false" \ -F "lineArt=false" \ -o compressed.pdf With target size: curl -X POST http://stirling-pdf:8080/api/v1/misc/compress-pdf \ -F "[email protected]" \ -F "expectedOutputSize=10MB" \ -o compressed.pdf See [API Documentation](https://docs.stirlingpdf.com/API) for complete endpoint reference. * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/Compress/#related-tools "Direct link to Related Tools") -------------------------------------------------------------------------------------------------------------------- * **[OCR](https://docs.stirlingpdf.com/Functionality/OCR) ** - Make searchable before compressing * **[Convert](https://docs.stirlingpdf.com/Functionality/Convert/) ** - Convert formats before compressing * **[Merge](https://docs.stirlingpdf.com/Functionality/Page-Operations/) ** - Combine then compress * [How to Use](https://docs.stirlingpdf.com/Functionality/Compress/#how-to-use) * [Options](https://docs.stirlingpdf.com/Functionality/Compress/#options) * [What Happens at Each Level](https://docs.stirlingpdf.com/Functionality/Compress/#what-happens-at-each-level) * [API Usage](https://docs.stirlingpdf.com/Functionality/Compress/#api-usage) * [Related Tools](https://docs.stirlingpdf.com/Functionality/Compress/#related-tools) --- # Features - Pipeline / Automate | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline/#__docusaurus_skipToContent_fallback) On this page V2.0 Update In V2.0, the pipeline feature's frontend interface has been renamed to **"Automate"** with an improved user experience. All backend functionality remains the same - existing pipeline JSON files work without changes. The Pipeline/Automate feature in Stirling PDF enables automated, sequential processing of PDFs through multiple operations. This powerful automation tool allows you to: * `create-pipeline`: Create custom workflows combining multiple PDF operations into a single automated process. For example, you could create a pipeline that: * Splits a PDF * Adds watermarks to each part * Compresses the results * All in one automated sequence * `save-pipeline`: Save pipeline configurations for future use, share them with others, or use them in automated folder scanning processes * `folder-scanning`: Set up automated processing of files in watched folders using your pipeline configurations. The system will automatically process any files placed in these folders according to your pipeline rules Additional Features[​](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline/#additional-features "Direct link to Additional Features") ------------------------------------------------------------------------------------------------------------------------------------------------- * Web UI configuration interface for easy pipeline setup * JSON-based configuration for advanced users * Support for multiple pipeline configurations * Automatic unzipping of intermediate results * Error handling and validation * Ability to save and load pipeline configurations For detailed information on setting up and using pipelines, see: * [Pipeline Configuration Guide](https://docs.stirlingpdf.com/Configuration/Pipeline) * [Folder Scanning Guide](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) Current Limitations[​](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline/#current-limitations "Direct link to Current Limitations") ------------------------------------------------------------------------------------------------------------------------------------------------- * Cannot have multiple instances of the same operation in a single pipeline * Web UI does not support operations requiring multiple different types of inputs * Files and operations run in serial mode * Additional file inputs during processing are not supported via UI * [Additional Features](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline/#additional-features) * [Current Limitations](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline/#current-limitations) --- # Advanced Tools | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#__docusaurus_skipToContent_fallback) On this page Advanced tools for automation workflows and complex PDF operations. * * * Automation Tools[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#automation-tools "Direct link to Automation Tools") ----------------------------------------------------------------------------------------------------------------------------------- ### Automate (Pipeline)[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#automate-pipeline "Direct link to Automate (Pipeline)") **Tool ID:** `automate` Chain multiple operations into automated workflows. Save and reuse pipeline configurations, process files automatically with predefined steps, and set up folder watching for automatic processing. **[Read the complete Pipeline Automation Guide →](https://docs.stirlingpdf.com/Configuration/Pipeline) ** * * * ### Auto Rename[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#auto-rename "Direct link to Auto Rename") **Tool ID:** `autoRename` Automatically rename PDF files based on their content. Analyzes each PDF and suggests filenames using this priority: 1. PDF metadata title (if present) 2. Largest font text on first page 3. First heading or prominent text 4. First line of readable text Works best with documents that have clear titles. Scanned documents may need [OCR](https://docs.stirlingpdf.com/Functionality/OCR) first. * * * Formatting Tools[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#formatting-tools "Direct link to Formatting Tools") ----------------------------------------------------------------------------------------------------------------------------------- ### Adjust Contrast[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#adjust-contrast "Direct link to Adjust Contrast") **Tool ID:** `adjustContrast` Adjust brightness, contrast, and saturation of PDF content. Useful for improving readability of faded scans or creating high-contrast versions. * * * ### Repair[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#repair "Direct link to Repair") **Tool ID:** `repair` Attempt to repair corrupted or damaged PDF files. Can fix broken cross-reference tables, corrupted object streams, missing headers, and encoding errors. Cannot recover physically deleted data. Success depends on extent of corruption. * * * ### Scanner Image Split[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#scanner-image-split "Direct link to Scanner Image Split") **Tool ID:** `scannerImageSplit` Automatically detect and split individual scanned photos from multi-image PDF scans. Useful for batch-scanned photo collections. * * * ### Overlay PDFs[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#overlay-pdfs "Direct link to Overlay PDFs") **Tool ID:** `overlayPdfs` Layer one PDF on top of another. Control position, opacity, and whether the overlay appears in the foreground or background. Apply to specific pages or all pages. * * * ### Replace Color[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#replace-color "Direct link to Replace Color") **Tool ID:** `replaceColor` Replace specific colors in a PDF or invert all colors. Options include full color inversion, targeted color replacement, and adjustable matching threshold. * * * ### Add Image[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#add-image "Direct link to Add Image") **Tool ID:** `addImage` Insert images into PDF pages with precise positioning and sizing. Supports common image formats. * * * ### Scanner Effect[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#scanner-effect "Direct link to Scanner Effect") **Tool ID:** `scannerEffect` Apply realistic scanner-like effects to digital PDFs - slight rotation/skew and scan artifacts to make documents appear physically scanned. * * * Developer Tools[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#developer-tools "Direct link to Developer Tools") -------------------------------------------------------------------------------------------------------------------------------- ### Show JavaScript[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#show-javascript "Direct link to Show JavaScript") **Tool ID:** `showJS` Display any embedded JavaScript code within a PDF document. Useful for security auditing and understanding PDF form logic. * * * ### Quick Links[​](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#quick-links "Direct link to Quick Links") * **[API Documentation](https://docs.stirlingpdf.com/API) ** * **[Folder Scanning Setup](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) ** * **[SSO Configuration](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) ** * **[General Configuration](https://docs.stirlingpdf.com/Configuration) ** * [Automation Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#automation-tools) * [Automate (Pipeline)](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#automate-pipeline) * [Auto Rename](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#auto-rename) * [Formatting Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#formatting-tools) * [Adjust Contrast](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#adjust-contrast) * [Repair](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#repair) * [Scanner Image Split](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#scanner-image-split) * [Overlay PDFs](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#overlay-pdfs) * [Replace Color](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#replace-color) * [Add Image](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#add-image) * [Scanner Effect](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#scanner-effect) * [Developer Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#developer-tools) * [Show JavaScript](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#show-javascript) * [Quick Links](https://docs.stirlingpdf.com/Functionality/Advanced-Tools/#quick-links) --- # Multi-Tool Workbench | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `multiTool` Multi-Tool is Stirling PDF's visual page editor. Upload PDFs and manipulate pages directly - rotate, reorder, delete, split, and insert pages or files. tip Multi-Tool uses browser file storage so you can upload files once and work with them without re-uploading. * * * Features[​](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#features "Direct link to Features") ------------------------------------------------------------------------------------------------------- * **Thumbnail grid** - See every page at a glance with zoomable previews * **Rotate** pages left/right, individually or in bulk * **Reorder** pages by dragging and dropping * **Delete** unwanted pages * **Split** PDFs by toggling split positions between pages * **Insert page breaks** - add blank pages at any position * **Insert files** - add entire PDFs into the document at any point * **Select pages** individually, select all, or by page number range * **Export selected** pages or save the full document * **Undo/redo** all changes * * * How to Use[​](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#how-to-use "Direct link to How to Use") ------------------------------------------------------------------------------------------------------------- 1. **Upload** - Drag and drop one or more PDFs into the workspace 2. **Select pages** - Click thumbnails or use select all / page number input 3. **Edit** - Rotate, reorder, delete, split, or insert as needed 4. **Export** - Save changes to download the full PDF, or export selected pages only * * * Multi-Tool vs. Individual Tools vs. Automate[​](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#multi-tool-vs-individual-tools-vs-automate "Direct link to Multi-Tool vs. Individual Tools vs. Automate") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Multi-Tool | Individual Tools | Automate | | --- | --- | --- | --- | | Multiple operations | Yes | No | Yes | | Visual feedback | Yes | Limited | No | | Repeatable workflow | No | No | Yes | | Folder watching | No | No | Yes | * * * Related Documentation[​](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#related-documentation "Direct link to Related Documentation") ---------------------------------------------------------------------------------------------------------------------------------------------- * **[Automate (Pipeline)](https://docs.stirlingpdf.com/Functionality/Features%20Pipeline) ** - Automated workflows * **[Complete Tool Reference](https://docs.stirlingpdf.com/functionality) ** - All available tools * [Features](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#features) * [How to Use](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#how-to-use) * [Multi-Tool vs. Individual Tools vs. Automate](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#multi-tool-vs-individual-tools-vs-automate) * [Related Documentation](https://docs.stirlingpdf.com/Functionality/Multi-Tool/#related-documentation) --- # OCR (Optical Character Recognition) | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/OCR/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `ocr-pdf` Make scanned PDFs searchable and selectable by recognizing text in images. Uses the Tesseract OCR engine. * * * When You Need OCR[​](https://docs.stirlingpdf.com/Functionality/OCR/#when-you-need-ocr "Direct link to When You Need OCR") --------------------------------------------------------------------------------------------------------------------------- * Scanned paper documents (no text layer) * Photos of documents or whiteboards * Image-only PDFs where you can't select or search text * * * How to Use[​](https://docs.stirlingpdf.com/Functionality/OCR/#how-to-use "Direct link to How to Use") ------------------------------------------------------------------------------------------------------ 1. **Upload Your PDF** - Select a scanned or image-based PDF 2. **Select Language(s)** - Choose the language(s) in your document 3. **Configure Options** - Adjust OCR mode and preprocessing (optional) 4. **Process** - Run OCR 5. **Download** - Get your searchable PDF * * * Options[​](https://docs.stirlingpdf.com/Functionality/OCR/#options "Direct link to Options") --------------------------------------------------------------------------------------------- | Option | Values | Description | | --- | --- | --- | | **Languages** | Select from installed packs | Must match the languages in your document. Select multiple if needed | | **OCR Mode** | Auto (default), Force, Strict | Auto skips pages that already have text. Force re-OCRs everything. Strict aborts if any text is found | | **Compatibility Mode** | On/Off | Uses sandwich PDF format for better compatibility with older software (larger files) | ### Advanced Options[​](https://docs.stirlingpdf.com/Functionality/OCR/#advanced-options "Direct link to Advanced Options") | Option | Description | | --- | --- | | **Deskew** | Automatically straighten tilted/skewed pages | | **Clean Input** | Preprocess by removing noise and enhancing contrast for better recognition | | **Clean Output** | Post-process the final PDF to remove OCR artifacts | | **Create Text File** | Generate a separate .txt file with the extracted text (output as ZIP) | Advanced options require OCRmyPDF. With Tesseract only, they are ignored. * * * Language Packs[​](https://docs.stirlingpdf.com/Functionality/OCR/#language-packs "Direct link to Language Packs") ------------------------------------------------------------------------------------------------------------------ Available languages depend on which Tesseract language packs are installed. The default Docker image includes English, German, French, Portuguese, and Chinese Simplified. To add more languages, see the **[OCR Configuration Guide](https://docs.stirlingpdf.com/Configuration/OCR) **. * * * Limitations[​](https://docs.stirlingpdf.com/Functionality/OCR/#limitations "Direct link to Limitations") --------------------------------------------------------------------------------------------------------- * Handwritten text has limited accuracy * Stylized/decorative fonts and very small text (< 8pt) are challenging * For best results, use 300 DPI or higher scans with good contrast * * * API Usage[​](https://docs.stirlingpdf.com/Functionality/OCR/#api-usage "Direct link to API Usage") --------------------------------------------------------------------------------------------------- curl -X POST http://stirling-pdf:8080/api/v1/misc/ocr-pdf \ -F "[email protected]" \ -F "languages=eng" \ -F "languages=spa" \ -F "ocrType=skip-text" \ -F "ocrRenderType=hocr" \ -F "deskew=true" \ -F "clean=true" \ -F "cleanFinal=true" \ -F "sidecar=false" \ -o searchable.pdf See [API Documentation](https://docs.stirlingpdf.com/API) for complete endpoint reference. * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/OCR/#related-tools "Direct link to Related Tools") --------------------------------------------------------------------------------------------------------------- * **[Convert](https://docs.stirlingpdf.com/Functionality/Convert/) ** - Convert OCR'd PDFs to Word, text, or other formats * **[Compress](https://docs.stirlingpdf.com/Functionality/Compress) ** - Reduce file size after OCR * **[Auto-Rename](https://docs.stirlingpdf.com/Functionality/Advanced-Tools#auto-rename) ** - Rename files based on OCR'd content * [When You Need OCR](https://docs.stirlingpdf.com/Functionality/OCR/#when-you-need-ocr) * [How to Use](https://docs.stirlingpdf.com/Functionality/OCR/#how-to-use) * [Options](https://docs.stirlingpdf.com/Functionality/OCR/#options) * [Advanced Options](https://docs.stirlingpdf.com/Functionality/OCR/#advanced-options) * [Language Packs](https://docs.stirlingpdf.com/Functionality/OCR/#language-packs) * [Limitations](https://docs.stirlingpdf.com/Functionality/OCR/#limitations) * [API Usage](https://docs.stirlingpdf.com/Functionality/OCR/#api-usage) * [Related Tools](https://docs.stirlingpdf.com/Functionality/OCR/#related-tools) --- # Read & Annotate PDFs | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `read` Interactive PDF viewer and annotation system. Read PDFs directly in your browser while adding comments, highlights, drawings, shapes, and other markup. tip Built with **[EmbedPDF](https://www.embedpdf.com/) **, an advanced open-source PDF viewer with full support for PDF annotation standards. * * * Annotation Tools[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#annotation-tools "Direct link to Annotation Tools") -------------------------------------------------------------------------------------------------------------------------------------- ### Text Markup[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#text-markup "Direct link to Text Markup") * **Highlight**, **Underline**, **Strikeout**, **Squiggly underline** * Full color picker and opacity control (10-100%) ### Drawing[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#drawing "Direct link to Drawing") * **Pen** - Freehand drawing with adjustable width (1-12px) * **Freehand Highlighter** - Width (1-20px) and opacity control ### Shapes[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#shapes "Direct link to Shapes") * **Square**, **Circle**, **Line**, **Arrow**, **Polyline**, **Polygon** * Independent stroke and fill color, border width (0-12px), opacity ### Comments & Text[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#comments--text "Direct link to Comments & Text") * **Text Comment** - Attach comments to any location * **Insert Text** / **Replace Text** - Mark text insertions and replacements * **Text Box** - Free text with font size, alignment, and background color * **Note** - Sticky notes with background color ### Stamps & Signatures[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#stamps--signatures "Direct link to Stamps & Signatures") * **Stamp** - Add images/photos * **Signature Stamp** - Signature images * **Signature Ink** - Handwritten signatures ### Comment Threads[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#comment-threads "Direct link to Comment Threads") * Reply threads on any annotation * Author attribution and timestamps * Comments sidebar listing all comments grouped by page * Click to navigate to the source annotation * * * Viewer Features[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#viewer-features "Direct link to Viewer Features") ----------------------------------------------------------------------------------------------------------------------------------- * Page navigation (first/prev/next/last, direct page jump) * Zoom in/out with manual percentage entry * Single page and dual-page spread modes * Thumbnail sidebar, bookmark sidebar, attachment sidebar * Full-text search (Ctrl+F) with result highlighting and navigation * Print (Ctrl+P) * * * Keyboard Shortcuts[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#keyboard-shortcuts "Direct link to Keyboard Shortcuts") -------------------------------------------------------------------------------------------------------------------------------------------- | Shortcut | Action | | --- | --- | | **Ctrl+F** | Search | | **Ctrl+P** | Print | | **Ctrl+S** | Save changes | | **Ctrl+Z** | Undo | | **Ctrl+Shift+Z / Ctrl+Y** | Redo | | **Ctrl++/-** | Zoom in/out | | **Ctrl+0** | Fit to width | | **Home / End** | First / last page | | **PageUp / PageDown** | Previous / next page | * * * Saving[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#saving "Direct link to Saving") -------------------------------------------------------------------------------------------------------- * **Save Changes** button or Ctrl+S to apply annotations * Undo/redo history available before saving * Annotations are embedded in standard PDF format and compatible with Adobe Acrobat, Foxit Reader, PDF-XChange, and macOS Preview * * * Related Documentation[​](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#related-documentation "Direct link to Related Documentation") ----------------------------------------------------------------------------------------------------------------------------------------------------- * **[Multi-Tool](https://docs.stirlingpdf.com/Functionality/Multi-Tool) ** - Page editing workspace * **[Sign PDFs](https://docs.stirlingpdf.com/Functionality/Security/Sign) ** - Add signatures * [Annotation Tools](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#annotation-tools) * [Text Markup](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#text-markup) * [Drawing](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#drawing) * [Shapes](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#shapes) * [Comments & Text](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#comments--text) * [Stamps & Signatures](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#stamps--signatures) * [Comment Threads](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#comment-threads) * [Viewer Features](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#viewer-features) * [Keyboard Shortcuts](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#keyboard-shortcuts) * [Saving](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#saving) * [Related Documentation](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate/#related-documentation) --- # Mobile Scanner | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#__docusaurus_skipToContent_fallback) On this page The Mobile Scanner lets you scan documents using your phone camera and upload them directly to your Stirling PDF instance. Generate a QR code on your desktop, scan it with your phone, and your photos are transferred automatically - no cables, no cloud services, no manual file handling. Depending on your [server settings](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner) , uploaded images can be automatically converted to PDF with configurable page format, resolution, and scaling options. How It Works[​](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#how-it-works "Direct link to How It Works") ----------------------------------------------------------------------------------------------------------------------- 1. Desktop generates a QR code with a unique session ID 2. Mobile device scans the QR code 3. Mobile uploads photos or images 4. Desktop retrieves files 5. Files auto-delete after 10 minutes of inactivity or upon download Privacy & Security[​](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#privacy--security "Direct link to Privacy & Security") ---------------------------------------------------------------------------------------------------------------------------------------- * Files stored temporarily in system temp directory only * No permanent storage on server * Auto-deleted after 10 minutes * Works on local network or HTTPS tunnel * No cloud storage involved Configuration[​](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#configuration "Direct link to Configuration") -------------------------------------------------------------------------------------------------------------------------- See [Mobile Scanner Configuration](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner) for enable/disable and PDF conversion settings. * [How It Works](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#how-it-works) * [Privacy & Security](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#privacy--security) * [Configuration](https://docs.stirlingpdf.com/Functionality/Mobile-Scanner/#configuration) --- # Third-Party Credits | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#__docusaurus_skipToContent_fallback) On this page Stirling PDF is built on these open-source projects. Server-Side[​](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#server-side "Direct link to Server-Side") ------------------------------------------------------------------------------------------------------------------------ * **[PDFBox](https://pdfbox.apache.org/) ** - Core PDF manipulation * **[LibreOffice](https://www.libreoffice.org/) ** - Office document conversions * **[qpdf](https://qpdf.sourceforge.io/) ** - Specialized PDF operations * **[Tesseract OCR](https://github.com/tesseract-ocr/tesseract) ** - Text recognition from images * **[OpenCV](https://opencv.org/) ** - Image processing Frontend[​](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#frontend "Direct link to Frontend") --------------------------------------------------------------------------------------------------------------- * **[React](https://react.dev/) ** + **[TypeScript](https://www.typescriptlang.org/) ** with **[Vite](https://vitejs.dev/) ** * **[EmbedPDF](https://www.embedpdf.com/) ** / **[PDF.js](https://mozilla.github.io/pdf.js/) ** - PDF viewing and annotation * **[pdf-lib](https://pdf-lib.js.org/) ** - Client-side PDF manipulation * **[Mantine](https://mantine.dev/) ** - UI components * **[i18next](https://www.i18next.com/) ** - 30+ language translations Desktop[​](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#desktop "Direct link to Desktop") ------------------------------------------------------------------------------------------------------------ * **[Tauri](https://tauri.app/) ** - Native app framework (Windows, Mac, Linux) Browser File Storage[​](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#browser-file-storage "Direct link to Browser File Storage") --------------------------------------------------------------------------------------------------------------------------------------------------- Files are stored locally in your browser's [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) between operations. They never leave your device until you process them. Clear storage when done on shared computers. Source Code[​](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#source-code "Direct link to Source Code") ------------------------------------------------------------------------------------------------------------------------ * [GitHub](https://github.com/Stirling-Tools/Stirling-PDF) * [Server-Side](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#server-side) * [Frontend](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#frontend) * [Desktop](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#desktop) * [Browser File Storage](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#browser-file-storage) * [Source Code](https://docs.stirlingpdf.com/Functionality/The%20Technologies/#source-code) --- # Sign PDF (Handwritten Signatures) | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Security/Sign/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `sign` Add handwritten signatures, text signatures, or image-based signatures to PDF documents. This tool is for visual/handwritten signatures - for certificate-based digital signatures, see [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) . * * * Signature Methods[​](https://docs.stirlingpdf.com/Functionality/Security/Sign/#signature-methods "Direct link to Signature Methods") ------------------------------------------------------------------------------------------------------------------------------------- * Draw * Type * Upload Image 1. Upload PDF and navigate to the signing location 2. Click "Draw Signature" to open the signature pad 3. Draw using mouse or touchscreen 4. Position and resize the signature on the page 5. Apply and download A touchscreen or stylus gives the best results. 1. Upload PDF 2. Click "Text Signature" 3. Type your name and choose a cursive/script font 4. Position and apply 1. Upload PDF 2. Click "Upload Signature" 3. Select a PNG/JPG of your signature 4. Position, resize, and apply Use a PNG with transparent background for best results. * * * Pre-stored Signatures[​](https://docs.stirlingpdf.com/Functionality/Security/Sign/#pre-stored-signatures "Direct link to Pre-stored Signatures") ------------------------------------------------------------------------------------------------------------------------------------------------- Configure Stirling PDF to load pre-stored signature files for quick, consistent signing across documents. **Configuration:** [Sign with Custom Files](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files) * * * Signature Options[​](https://docs.stirlingpdf.com/Functionality/Security/Sign/#signature-options "Direct link to Signature Options") ------------------------------------------------------------------------------------------------------------------------------------- * **Transparency** - Make signature background transparent * **Color** - Blue, black, or custom ink color * **Size** - Adjust to fit signature line * **Rotation** - Adjust angle if needed * **Pages** - Sign on single page, multiple pages, or different signatures per page * * * Visual vs. Digital Signatures[​](https://docs.stirlingpdf.com/Functionality/Security/Sign/#visual-vs-digital-signatures "Direct link to Visual vs. Digital Signatures") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Visual Signature (This Tool) | Digital Signature ([Certificate](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing)
) | | --- | --- | --- | | **Security** | Visual only, can be copied | Cryptographically secure | | **Authentication** | No verification | Proves signer identity | | **Tamper Detection** | None | Detects changes after signing | | **Setup** | None required | Requires certificate | Visual signatures do **not** provide authentication, tamper protection, or guaranteed legal standing. For legally binding signatures requiring verification, use [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) . * * * Related Tools[​](https://docs.stirlingpdf.com/Functionality/Security/Sign/#related-tools "Direct link to Related Tools") ------------------------------------------------------------------------------------------------------------------------- * **[Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ** - Digital signatures with certificates * **[Add Stamp](https://docs.stirlingpdf.com/Functionality/Content-Editing#stamps--annotations) ** - Add official stamps * **[Add Password](https://docs.stirlingpdf.com/Functionality/Security#password-protection) ** - Protect signed documents * [Signature Methods](https://docs.stirlingpdf.com/Functionality/Security/Sign/#signature-methods) * [Pre-stored Signatures](https://docs.stirlingpdf.com/Functionality/Security/Sign/#pre-stored-signatures) * [Signature Options](https://docs.stirlingpdf.com/Functionality/Security/Sign/#signature-options) * [Visual vs. Digital Signatures](https://docs.stirlingpdf.com/Functionality/Security/Sign/#visual-vs-digital-signatures) * [Related Tools](https://docs.stirlingpdf.com/Functionality/Security/Sign/#related-tools) --- # One doc tagged with "Paid" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/paid/#__docusaurus_skipToContent_fallback) [Paid Offerings\ --------------](https://docs.stirlingpdf.com/Paid-Offerings) Server and Enterprise paid plans for Stirling PDF --- # One doc tagged with "Pricing" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/pricing/#__docusaurus_skipToContent_fallback) [Paid Offerings\ --------------](https://docs.stirlingpdf.com/Paid-Offerings) Server and Enterprise paid plans for Stirling PDF --- # One doc tagged with "API" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/api/#__docusaurus_skipToContent_fallback) [API\ ---](https://docs.stirlingpdf.com/API) Overview of API offering in S-PDF --- # 6 docs tagged with "enterprise" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/enterprise/#__docusaurus_skipToContent_fallback) [Audit Logging\ -------------](https://docs.stirlingpdf.com/Configuration/Audit%20Logging) Tier: Enterprise [OAuth 2.0 Single Sign-On Configuration\ --------------------------------------](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) Tier: Server [Paid Offerings\ --------------](https://docs.stirlingpdf.com/Paid-Offerings) Server and Enterprise paid plans for Stirling PDF [SAML 2.0 Single Sign-On Configuration\ -------------------------------------](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) Tier: Enterprise [Single Sign-On (SSO) Overview\ -----------------------------](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) Stirling PDF supports Single Sign-On (SSO) authentication through two protocols: [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) Tier: Enterprise --- # 4 docs tagged with "server" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/server/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/Configuration/DATABASE) Tier: Server [External Database\ -----------------](https://docs.stirlingpdf.com/Configuration/External%20Database) Tier: Server [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker) Tier: Server [Paid Offerings\ --------------](https://docs.stirlingpdf.com/Paid-Offerings) Server and Enterprise paid plans for Stirling PDF --- # Settings Changes from V1 to V2 | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Migration/Settings-Changes/#__docusaurus_skipToContent_fallback) On this page This page documents all `settings.yml` changes between V1 and V2. * * * New Settings in V2[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#new-settings-in-v2 "Direct link to New Settings in V2") --------------------------------------------------------------------------------------------------------------------------------------- ### PDF Signature Validation[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#pdf-signature-validation "Direct link to PDF Signature Validation") **Entire new section added:** security: validation: # NEW in V2 trust: serverAsAnchor: true useSystemTrust: true useMozillaBundle: true useAATL: false # Adobe Approved Trust List useEUTL: false # EU Trusted List allowAIA: false aatl: url: https://trustlist.adobe.com/tl.pdf eutl: lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml acceptTransitional: false revocation: mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false **What it does:** Comprehensive PDF signature validation with configurable trust chains. **Migration:** No action needed, defaults are safe for most users. **Learn more:** [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) | [Security Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#signature-validation) * * * ### Server Certificate Management[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#server-certificate-management "Direct link to Server Certificate Management") **New section added:** system: serverCertificate: # NEW in V2 enabled: true organizationName: Stirling-PDF validity: 365 # days regenerateOnStartup: false **What it does:** Auto-generates signing certificates for "Sign with Stirling PDF" feature. **Migration:** Works automatically with defaults. **Learn more:** [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) | [Certificate Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#server-certificates) * * * ### Enhanced JWT Configuration[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#enhanced-jwt-configuration "Direct link to Enhanced JWT Configuration") **Changed settings:** # V1 (OLD)security: jwt: enabled: false keyCleanup: false secureCookie: true # REMOVED# V2 (NEW)security: jwt: persistence: true # replaces 'enabled' enableKeyRotation: true # NEW enableKeyCleanup: true # replaces 'keyCleanup' keyRetentionDays: 7 **Migration:** * Replace `jwt.enabled` with `jwt.persistence` * Replace `jwt.keyCleanup` with `jwt.enableKeyCleanup` * Add `jwt.enableKeyRotation: true` * Remove `jwt.secureCookie` (no longer used) * * * ### Email Invites[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#email-invites "Direct link to Email Invites") **New setting added:** mail: enableInvites: false # NEW in V2 **What it does:** Enable email invitations for user registration. **Requirements:** * `mail.enabled: true` * `security.enableLogin: true` **Migration:** Set to `true` if you want invite functionality. * * * ### UI Logo Customization[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#ui-logo-customization "Direct link to UI Logo Customization") **New setting added:** ui: logoStyle: classic # NEW in V2 - Options: 'classic' or 'modern' **What it does:** Choose between classic S icon or modern minimalist logo. **Migration:** Leave as `classic` (default) or set to `modern` for new look. * * * Removed Settings in V2[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#removed-settings-in-v2 "Direct link to Removed Settings in V2") --------------------------------------------------------------------------------------------------------------------------------------------------- ### UI Settings Moved to In-App Configuration[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#ui-settings-moved-to-in-app-configuration "Direct link to UI Settings Moved to In-App Configuration") **V1 settings (REMOVED):** ui: appName: '' # REMOVED homeDescription: '' # REMOVED **Migration:** 1. Enable login: `SECURITY_ENABLELOGIN=true` 2. Log in as admin 3. Go to Settings in UI 4. Configure app name and description there **Why:** In-app settings are more user-friendly and apply immediately. **Learn more:** [UI Customisation](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) * * * ### Google Drive Integration[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#google-drive-integration "Direct link to Google Drive Integration") **V1 settings (REMOVED):** premium: proFeatures: googleDrive: # REMOVED in V2 enabled: false clientId: '' apiKey: '' appId: '' **Migration:** Remove this section from your `settings.yml`. **Why:** Feature discontinued in V2. * * * ### Database Notifications[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#database-notifications "Direct link to Database Notifications") **V1 settings (REMOVED):** premium: enterpriseFeatures: databaseNotifications: # REMOVED in V2 backups: successful: false failed: false imports: successful: false failed: false **Migration:** Remove this section from your `settings.yml`. **Why:** Replaced with more comprehensive audit logging. * * * ### Calibre Custom Path[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#calibre-custom-path "Direct link to Calibre Custom Path") **V1 setting (REMOVED):** system: customPaths: operations: calibre: '' # REMOVED in V2 **Migration:** Remove this line. **Why:** Path detection improved, no longer needs custom configuration. * * * Migration Checklist[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#migration-checklist "Direct link to Migration Checklist") ------------------------------------------------------------------------------------------------------------------------------------------ Use this checklist when upgrading your `settings.yml`: ### Required Changes[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#required-changes "Direct link to Required Changes") * **JWT Settings:** * [ ] Replace `jwt.enabled` with `jwt.persistence` * [ ] Replace `jwt.keyCleanup` with `jwt.enableKeyCleanup` * [ ] Add `jwt.enableKeyRotation: true` * [ ] Remove `jwt.secureCookie` line * **Remove Deprecated Sections:** * [ ] Remove `premium.proFeatures.googleDrive` section * [ ] Remove `premium.enterpriseFeatures.databaseNotifications` section * [ ] Remove `system.customPaths.operations.calibre` line * **UI Settings:** * [ ] Remove `ui.appName` (use in-app settings) * [ ] Remove `ui.homeDescription` (use in-app settings) ### Optional Additions[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#optional-additions "Direct link to Optional Additions") * [ ] **Add `ui.logoStyle: classic`** if you want to explicitly set logo * [ ] **Configure `security.validation`** if you need custom signature validation * [ ] **Set `system.serverCertificate`** options if needed * [ ] **Enable `mail.enableInvites`** if you want email invitations * * * Environment Variable Changes[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#environment-variable-changes "Direct link to Environment Variable Changes") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### New Environment Variables in V2[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#new-environment-variables-in-v2 "Direct link to New Environment Variables in V2") # Signature validationSECURITY_VALIDATION_TRUST_SERVERASANCHOR=trueSECURITY_VALIDATION_TRUST_USESYSTEMTRUST=trueSECURITY_VALIDATION_TRUST_USEMOZILLABUNDLE=trueSECURITY_VALIDATION_TRUST_USEAATL=falseSECURITY_VALIDATION_TRUST_USEEUTL=falseSECURITY_VALIDATION_REVOCATION_MODE=none# Server certificatesSYSTEM_SERVERCERTIFICATE_ENABLED=trueSYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"SYSTEM_SERVERCERTIFICATE_VALIDITY=365# JWTSECURITY_JWT_PERSISTENCE=trueSECURITY_JWT_ENABLEKEYROTATION=trueSECURITY_JWT_ENABLEKEYCLEANUP=true# Email configurationMAIL_FROM=[email protected]MAIL_ENABLEINVITES=true# LogoUI_LOGOSTYLE=modern ### Deprecated Environment Variables[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#deprecated-environment-variables "Direct link to Deprecated Environment Variables") # These no longer work in V2SECURITY_JWT_ENABLED # Use SECURITY_JWT_PERSISTENCESECURITY_JWT_KEYCLEANUP # Use SECURITY_JWT_ENABLEKEYCLEANUPSECURITY_JWT_SECURECOOKIE # RemovedUI_APPNAME # Use in-app settingsUI_HOMEDESCRIPTION # Use in-app settings * * * Configuration Examples[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#configuration-examples "Direct link to Configuration Examples") --------------------------------------------------------------------------------------------------------------------------------------------------- ### Minimal V2 Configuration (Works Out of Box)[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#minimal-v2-configuration-works-out-of-box "Direct link to Minimal V2 Configuration (Works Out of Box)") security: enableLogin: falsesystem: defaultLocale: en-USui: appNameNavbar: '' All new V2 features use sensible defaults. * * * ### V1 to V2 Configuration Diff[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#v1-to-v2-configuration-diff "Direct link to V1 to V2 Configuration Diff") **V1 Configuration:** security: jwt: enabled: false keyCleanup: false secureCookie: trueui: appName: 'My PDF Tool' homeDescription: 'Welcome!' appNameNavbar: 'PDF Tool'premium: proFeatures: googleDrive: enabled: false **V2 Configuration:** security: jwt: persistence: true # Changed enableKeyRotation: true # NEW enableKeyCleanup: true # Changed keyRetentionDays: 7 validation: # NEW section trust: serverAsAnchor: true useSystemTrust: truesystem: serverCertificate: # NEW section enabled: true organizationName: Stirling-PDFui: appNameNavbar: 'PDF Tool' logoStyle: classic # NEW # appName and homeDescription removed - use in-app settings * * * Troubleshooting[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------------------ ### "Unknown configuration key" warnings[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#unknown-configuration-key-warnings "Direct link to "Unknown configuration key" warnings") **Symptom:** Warnings about unrecognized settings on startup. **Cause:** Old V1 settings still in your `settings.yml`. **Solution:** Remove deprecated settings listed in this guide. * * * ### JWT tokens invalid after upgrade[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#jwt-tokens-invalid-after-upgrade "Direct link to JWT tokens invalid after upgrade") **Symptom:** Users logged out, need to re-login. **Cause:** JWT key format changed. **Solution:** Expected behavior, users just need to log in again once. * * * ### Custom app name not showing[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#custom-app-name-not-showing "Direct link to Custom app name not showing") **Symptom:** App name doesn't appear after setting `ui.appName`. **Cause:** Setting moved to in-app configuration. **Solution:** 1. Log in as admin 2. Go to Settings → UI 3. Configure there * * * Related Documentation[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#related-documentation "Direct link to Related Documentation") ------------------------------------------------------------------------------------------------------------------------------------------------ * **[New Features](https://docs.stirlingpdf.com/Migration/New-Features) ** - What's new in V2 * **[Breaking Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes) ** - Important changes * **[Configuration Options](https://docs.stirlingpdf.com/Configuration/Extra-Settings) ** - All configuration variables * **[System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) ** - Advanced config * * * Summary[​](https://docs.stirlingpdf.com/Migration/Settings-Changes/#summary "Direct link to Summary") ------------------------------------------------------------------------------------------------------ **Key Takeaways:** * ✅ Most settings remain the same * 🔄 JWT settings have new names * ➕ Many new optional features * ➖ Google Drive and database notifications removed * 🎨 UI settings moved to in-app configuration **Action Required:** * Update JWT setting names * Remove deprecated sections * Optionally configure new features Your existing configuration will work in V2 with minimal changes! * [New Settings in V2](https://docs.stirlingpdf.com/Migration/Settings-Changes/#new-settings-in-v2) * [PDF Signature Validation](https://docs.stirlingpdf.com/Migration/Settings-Changes/#pdf-signature-validation) * [Server Certificate Management](https://docs.stirlingpdf.com/Migration/Settings-Changes/#server-certificate-management) * [Enhanced JWT Configuration](https://docs.stirlingpdf.com/Migration/Settings-Changes/#enhanced-jwt-configuration) * [Email Invites](https://docs.stirlingpdf.com/Migration/Settings-Changes/#email-invites) * [UI Logo Customization](https://docs.stirlingpdf.com/Migration/Settings-Changes/#ui-logo-customization) * [Removed Settings in V2](https://docs.stirlingpdf.com/Migration/Settings-Changes/#removed-settings-in-v2) * [UI Settings Moved to In-App Configuration](https://docs.stirlingpdf.com/Migration/Settings-Changes/#ui-settings-moved-to-in-app-configuration) * [Google Drive Integration](https://docs.stirlingpdf.com/Migration/Settings-Changes/#google-drive-integration) * [Database Notifications](https://docs.stirlingpdf.com/Migration/Settings-Changes/#database-notifications) * [Calibre Custom Path](https://docs.stirlingpdf.com/Migration/Settings-Changes/#calibre-custom-path) * [Migration Checklist](https://docs.stirlingpdf.com/Migration/Settings-Changes/#migration-checklist) * [Required Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes/#required-changes) * [Optional Additions](https://docs.stirlingpdf.com/Migration/Settings-Changes/#optional-additions) * [Environment Variable Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes/#environment-variable-changes) * [New Environment Variables in V2](https://docs.stirlingpdf.com/Migration/Settings-Changes/#new-environment-variables-in-v2) * [Deprecated Environment Variables](https://docs.stirlingpdf.com/Migration/Settings-Changes/#deprecated-environment-variables) * [Configuration Examples](https://docs.stirlingpdf.com/Migration/Settings-Changes/#configuration-examples) * [Minimal V2 Configuration (Works Out of Box)](https://docs.stirlingpdf.com/Migration/Settings-Changes/#minimal-v2-configuration-works-out-of-box) * [V1 to V2 Configuration Diff](https://docs.stirlingpdf.com/Migration/Settings-Changes/#v1-to-v2-configuration-diff) * [Troubleshooting](https://docs.stirlingpdf.com/Migration/Settings-Changes/#troubleshooting) * ["Unknown configuration key" warnings](https://docs.stirlingpdf.com/Migration/Settings-Changes/#unknown-configuration-key-warnings) * [JWT tokens invalid after upgrade](https://docs.stirlingpdf.com/Migration/Settings-Changes/#jwt-tokens-invalid-after-upgrade) * [Custom app name not showing](https://docs.stirlingpdf.com/Migration/Settings-Changes/#custom-app-name-not-showing) * [Related Documentation](https://docs.stirlingpdf.com/Migration/Settings-Changes/#related-documentation) * [Summary](https://docs.stirlingpdf.com/Migration/Settings-Changes/#summary) --- # Breaking Changes in V2 | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#__docusaurus_skipToContent_fallback) On this page Most V1 deployments will upgrade smoothly to V2, but there are some important changes you should know about. This page documents breaking changes and how to handle them. * * * ⚠️ Impact Summary[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-impact-summary "Direct link to ⚠️ Impact Summary") ------------------------------------------------------------------------------------------------------------------------------------------- | Change | Impact | Action Required | | --- | --- | --- | | **Template Customization** | High | Rewrite customizations | | **UI Settings Location** | Medium | Use in-app settings | | **Session Management** | Low | Update setting names | | **Database Notifications** | Low | Use audit logs instead | * * * 🎨 UI Customization Architecture Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-ui-customization-architecture-changed "Direct link to 🎨 UI Customization Architecture Changed") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** HIGH for users who customized UI using `customFiles/templates/` ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed "Direct link to What Changed") **V1 Architecture:** customFiles/ └── templates/ ├── fragments/ │ └── navbar.html # Custom Thymeleaf template └── home.html # Custom Thymeleaf template V1 used **server-side rendering** with Thymeleaf templates. HTML was generated dynamically on the server for each request. **V2 Architecture:** V2 uses a **React frontend** with client-side rendering. The UI is built into **static files** (HTML, CSS, JavaScript) that are served to the browser. **What this means:** * ❌ Thymeleaf templates (`.html` with `th:*` attributes) no longer work because there's no server-side rendering * ✅ Static file overrides **still work** via `customFiles/static/` - same concept, different paths * The file paths are different because they're now built React files instead of Thymeleaf templates ### Migration Path[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-path "Direct link to Migration Path") Your V1 Thymeleaf templates cannot be directly reused in V2, but you have three options: #### Option 1: Use Built-In Customization (Recommended)[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#option-1-use-built-in-customization-recommended "Direct link to Option 1: Use Built-In Customization (Recommended)") V2 provides in-app settings for most common customizations: **Available Customizations:** * App name and description * Navbar branding * Logo style (classic/modern) * Custom logo upload * Homepage description **How to use:** 1. Enable login: `SECURITY_ENABLELOGIN=true` 2. Log in as admin 3. Go to Settings → UI 4. Configure branding there **Learn more:** [UI Customisation](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) #### Option 2: Static File Overrides (Same Concept as V1, Different Paths)[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#option-2-static-file-overrides-same-concept-as-v1-different-paths "Direct link to Option 2: Static File Overrides (Same Concept as V1, Different Paths)") **✅ Still supported in V2!** The static file override system works the same way conceptually - place files in `customFiles/static/` to override defaults. **How it works:** 1. V2 checks `customFiles/static/` **first** for any requested file 2. If not found, falls back to the bundled static files 3. This lets you override logos, CSS, HTML, JavaScript, or any other static asset **Example Docker compose:** volumes: - ./customFiles:/customFiles:rw **Key difference from V1:** * V1 paths: `customFiles/templates/fragments/navbar.html` (Thymeleaf) * V2 paths: `customFiles/static/index.html` (React build output) The file paths are different because V2 serves the **compiled React app** instead of Thymeleaf templates. See [Other Customisations - Static File Overrides](https://docs.stirlingpdf.com/Configuration/Other%20Customisations#static-file-overrides) for: * How to determine the correct file paths in V2 * Examples of common customizations * Understanding the build output structure **Use cases:** * Custom favicon or logo * Modified `index.html` for advanced branding * Custom CSS to override styles * Additional static assets #### Option 3: Fork the Frontend (Advanced)[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#option-3-fork-the-frontend-advanced "Direct link to Option 3: Fork the Frontend (Advanced)") For complete UI customization: **Steps:** 1. Fork Stirling PDF repository 2. Modify React components in `frontend/src/` 3. Build custom frontend 4. Deploy in split mode with custom frontend **Trade-offs:** * ✅ Complete control * ❌ Must maintain your fork * ❌ Manual merges for updates ### What No Longer Works[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-no-longer-works "Direct link to What No Longer Works") These V1 **Thymeleaf template features** no longer work because V2 uses React (client-side) instead of Thymeleaf (server-side):
Custom content
**Why they don't work:** These are Thymeleaf-specific features that require server-side HTML generation. V2 uses React which compiles to static JavaScript that runs in the browser. **Alternative:** You can still customize the **output** by overriding the built static files in `customFiles/static/`, but you'll be editing the compiled HTML/CSS/JS instead of Thymeleaf templates. * * * ⚙️ UI Settings Moved to In-App Configuration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-ui-settings-moved-to-in-app-configuration "Direct link to ⚙️ UI Settings Moved to In-App Configuration") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** MEDIUM - Settings moved, but easy to reconfigure ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-1 "Direct link to What Changed") **V1 Configuration:** ui: appName: 'My PDF Tool' homeDescription: 'Welcome to our PDF service!' **V2 Configuration:** ui: appNameNavbar: 'My PDF Tool' # Still in YAML # appName and homeDescription REMOVED # Configure these in-app instead ### Why the Change[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-the-change "Direct link to Why the Change") **Benefits:** * ✅ No container restart needed * ✅ Visual interface with preview * ✅ Validation prevents errors * ✅ Changes apply immediately * ✅ Role-based access control ### Migration Steps[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-steps "Direct link to Migration Steps") 1. **Note your current settings:** # From V1 settings.ymlui: appName: 'CompanyName PDF' homeDescription: 'Internal document processing' 2. **Remove from settings.yml:** ui: appNameNavbar: 'CompanyName PDF' # appName - REMOVE THIS LINE # homeDescription - REMOVE THIS LINE 3. **Configure in UI:** * Enable login: `SECURITY_ENABLELOGIN=true` * Start V2 * Log in as admin * Go to Settings → UI * Enter app name and description * Save ### Environment Variables[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#environment-variables "Direct link to Environment Variables") These environment variables **no longer work**: # V1 (NO LONGER WORKS)UI_APPNAME="My PDF Tool"UI_HOMEDESCRIPTION="Welcome!"# V2 (USE IN-APP SETTINGS INSTEAD)# Set through UI after logging in `UI_APPNAMENAVBAR` still works for navbar branding. * * * 🔐 Session Management Improvements[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-session-management-improvements "Direct link to 🔐 Session Management Improvements") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - New session features with simple setting updates ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-2 "Direct link to What Changed") Session management enhanced with new JWT-based features and improved settings: | V1 Setting | V2 Setting | Change | | --- | --- | --- | | `jwt.enabled` | `jwt.persistence` | Renamed | | `jwt.keyCleanup` | `jwt.enableKeyCleanup` | Renamed | | `jwt.secureCookie` | _(removed)_ | Always secure now | | _(new)_ | `jwt.enableKeyRotation` | New feature | | _(new)_ | `jwt.keyRetentionDays` | New feature | ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration "Direct link to Migration") **V1 Configuration:** security: jwt: enabled: false keyCleanup: false secureCookie: true **V2 Configuration:** security: jwt: persistence: true # was 'enabled' enableKeyCleanup: true # was 'keyCleanup' enableKeyRotation: true # NEW keyRetentionDays: 7 # NEW # secureCookie REMOVED ### Environment Variables[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#environment-variables-1 "Direct link to Environment Variables") **V1 (NO LONGER WORKS):** SECURITY_JWT_ENABLED=falseSECURITY_JWT_KEYCLEANUP=falseSECURITY_JWT_SECURECOOKIE=true **V2 (USE THESE):** SECURITY_JWT_PERSISTENCE=trueSECURITY_JWT_ENABLEKEYCLEANUP=trueSECURITY_JWT_ENABLEKEYROTATION=trueSECURITY_JWT_KEYRETENTIONDAYS=7 ### After Upgrade[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#after-upgrade "Direct link to After Upgrade") **Expected behavior:** Users will be logged out once after upgrade. **Why:** Session token format changed with new JWT implementation. **Action:** Users just need to log in again. Normal behavior. **Learn more:** [Settings Changes - JWT Configuration](https://docs.stirlingpdf.com/Migration/Settings-Changes#enhanced-jwt-configuration) * * * 🔕 Database Notifications Removed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-database-notifications-removed "Direct link to 🔕 Database Notifications Removed") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Replaced with better alternative ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-3 "Direct link to What Changed") Database backup/import notifications removed. **V1 Configuration (NO LONGER WORKS):** premium: enterpriseFeatures: databaseNotifications: backups: successful: false failed: false imports: successful: false failed: false ### Why Removed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-removed "Direct link to Why Removed") Replaced with comprehensive audit logging system that provides: * More detailed information * Searchable history * Export capabilities * Better retention policies ### Migration to Audit Logs[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-to-audit-logs "Direct link to Migration to Audit Logs") **V2 Alternative:** 1. **Enable audit logging:** system: logging: level: INFO 2. **Monitor logs:** docker logs stirling-pdf | grep "Database backup"docker logs stirling-pdf | grep "Database import" 3. **Or use audit log UI:** * Log in as admin * Go to Settings → Audit Logs * Filter by operation type * Export as needed ### What You Get Instead[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-you-get-instead "Direct link to What You Get Instead") **Audit logs provide:** * ✅ Database operations (backup, import, export) * ✅ User actions (login, logout, operations) * ✅ Admin actions (settings changes, user management) * ✅ Failed operations with error details * ✅ Search and filter capabilities * ✅ Export to CSV/JSON **Example audit log entry:** { "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" }} * * * 🔧 Calibre Custom Path Removed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-calibre-custom-path-removed "Direct link to 🔧 Calibre Custom Path Removed") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Auto-detection improved ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-4 "Direct link to What Changed") Custom Calibre path no longer needed. **V1 Configuration (NO LONGER WORKS):** system: customPaths: operations: calibre: '/usr/bin/calibre' ### Why Removed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-removed-1 "Direct link to Why Removed") V2 has improved path detection: * Automatically finds Calibre in standard locations * Checks multiple common paths * Better error messages if not found ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-1 "Direct link to Migration") 1. **Remove from settings.yml:** system: customPaths: operations: # calibre: '' # DELETE THIS LINE 2. **Verify Calibre is installed:** docker exec stirling-pdf which ebook-convert 3. **If not found, install in container:** # In your DockerfileRUN apt-get update && apt-get install -y calibre ### Standard Detection Paths[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#standard-detection-paths "Direct link to Standard Detection Paths") V2 automatically checks: * `/usr/bin/ebook-convert` * `/usr/local/bin/ebook-convert` * `ebook-convert` (in PATH) If Calibre is in any standard location, it will be found automatically. * * * 📦 Docker Image Changes[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-docker-image-changes "Direct link to 📦 Docker Image Changes") ---------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Most users unaffected ### Tag Changes[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#tag-changes "Direct link to Tag Changes") **V1 Tags:** stirlingtools/s-pdf:latest # OLD NAMEstirlingtools/s-pdf:0.xx.x **V2 Tags:** stirlingtools/stirling-pdf:latest # NEW NAMEstirlingtools/stirling-pdf:2.x.x ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-2 "Direct link to Migration") Update your docker-compose.yml: **V1:** services: stirling-pdf: image: stirlingtools/s-pdf:latest # OLD **V2:** services: stirling-pdf: image: stirlingtools/stirling-pdf:latest # NEW ### Backwards Compatibility[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#backwards-compatibility "Direct link to Backwards Compatibility") The old `s-pdf` image is deprecated but still receives updates for now. However, you should migrate to the new image name. * * * 🌐 API Compatibility[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-api-compatibility "Direct link to 🌐 API Compatibility") ------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Most endpoints unchanged ### What Stayed the Same[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-stayed-the-same "Direct link to What Stayed the Same") ✅ All existing API endpoints work ✅ Request/response formats unchanged ✅ Authentication methods compatible ✅ API keys still valid ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-5 "Direct link to What Changed") **New endpoints added:** * `/api/v1/security/validate-signature` - PDF signature validation * `/api/v1/misc/remove-cert-sign` - Remove certificate signatures * `/api/v1/misc/booklet-imposition` - Booklet printing layout * `/api/v1/misc/unlock-pdf-forms` - Unlock form fields * `/api/v1/misc/replace-color` - Color replacement * `/api/v1/misc/add-attachments` - Add file attachments * `/api/v1/misc/edit-toc` - Edit table of contents **Enhanced endpoints:** * Better error messages * Consistent error format * Progress tracking for long operations ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-3 "Direct link to Migration") **No action needed** for existing API integrations. New endpoints are additive. **If using OpenAPI spec:** 1. Download updated spec from `/v3/api-docs` 2. Regenerate client code if needed * * * 🗄️ Database Schema[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-database-schema "Direct link to 🗄️ Database Schema") ------------------------------------------------------------------------------------------------------------------------------------------------ **Impact:** NONE - Automatic migration ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-6 "Direct link to What Changed") Database schema updated to support: * Enhanced audit logging * JWT key rotation * User invitation system * In-app settings storage ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-4 "Direct link to Migration") **Automatic!** On first V2 startup: 1. V2 detects V1 schema 2. Runs migration scripts 3. Updates to V2 schema 4. All data preserved **No manual action needed.** ### Rollback Considerations[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#rollback-considerations "Direct link to Rollback Considerations") Database is **forward-compatible only**: * ✅ V1 → V2 upgrade: Automatic * ⚠️ V2 → V1 rollback: Database needs manual downgrade **If you need to rollback:** 1. Restore database backup from before V2 upgrade 2. Or use V1-compatible database dump **Recommendation:** Take database backup before upgrading. * * * 📱 Browser Compatibility[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-browser-compatibility "Direct link to 📱 Browser Compatibility") ------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Modern browsers required ### Minimum Browser Versions[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#minimum-browser-versions "Direct link to Minimum Browser Versions") **V2 Requirements:** | Browser | Minimum Version | Notes | | --- | --- | --- | | **Chrome** | 90+ | Recommended | | **Firefox** | 88+ | Recommended | | **Safari** | 14+ | Some limitations | | **Edge** | 90+ | Chromium-based | **V1 vs V2:** * V1 supported older browsers (IE11, old Safari) * V2 requires modern browsers for IndexedDB, modern JavaScript ### Why the Change[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-the-change-1 "Direct link to Why the Change") V2 features require modern browser APIs: * IndexedDB for file storage * ES2020+ JavaScript * Modern CSS features * Web Workers for performance ### If Users Have Old Browsers[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#if-users-have-old-browsers "Direct link to If Users Have Old Browsers") **Options:** 1. **Update browser** (recommended) 2. **Use desktop app** (supports older systems) 3. **Stay on V1** (still receives security updates) * * * 🔒 Security Changes[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-security-changes "Direct link to 🔒 Security Changes") ---------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Generally more secure ### HTTPS Enforcement[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#https-enforcement "Direct link to HTTPS Enforcement") **V2 Change:** Secure cookies always enabled for production. **V1:** security: jwt: secureCookie: true # Configurable **V2:** # secureCookie removed - always secure in production **Impact:** * ✅ More secure by default * ⚠️ Requires HTTPS in production * Development mode (localhost) still works over HTTP **Migration:** If running in production, ensure HTTPS is configured: server: ssl: enabled: true key-store: /path/to/keystore.p12 key-store-password: ${SSL_PASSWORD} ### Session Management[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#session-management "Direct link to Session Management") **V2 Changes:** * Shorter default session timeout (4 hours → 2 hours) * Better session invalidation * Stricter CORS policies **To increase timeout:** security: sessionTimeout: 14400 # 4 hours in seconds * * * 🎯 Feature Flag Changes[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-feature-flag-changes "Direct link to 🎯 Feature Flag Changes") ---------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** LOW - Endpoint customization still works ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-7 "Direct link to What Changed") Tool IDs updated for consistency: | Old ID (V1) | New ID (V2) | Tool Name | | --- | --- | --- | | `pdf-organizer` | `reorganize-pages` | Reorganize Pages | | `sign-forms` | `sign` | Sign PDF | ### Migration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-5 "Direct link to Migration") Update `settings.yml` endpoint customization: **V1:** endpoints: toRemove: ['pdf-organizer'] **V2:** endpoints: toRemove: ['reorganize-pages'] **Complete tool ID list:** [Endpoint Customisation](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation) * * * 📖 Documentation Structure[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-documentation-structure "Direct link to 📖 Documentation Structure") ------------------------------------------------------------------------------------------------------------------------------------------------------------- **Impact:** NONE - Just informational ### What Changed[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-8 "Direct link to What Changed") Documentation reorganized for clarity: * "V2 Guides" → "Guides" (current features) * "Migration" section added (V1→V2 transition) * Dedicated pages for super tools * Comprehensive tool reference ### Old Links[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#old-links "Direct link to Old Links") Documentation has been reorganized: * Guides section contains current features (File Storage, Undo/Redo, Desktop vs Web) * Migration section contains V1→V2 transition information * Individual pages moved to appropriate sections * * * ✅ Pre-Upgrade Checklist[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-pre-upgrade-checklist "Direct link to ✅ Pre-Upgrade Checklist") ----------------------------------------------------------------------------------------------------------------------------------------------------- Before upgrading to V2, verify: ### 1\. Customizations[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#1-customizations "Direct link to 1. Customizations") * [ ] **Using custom templates?** → Plan rewrite or use built-in settings * [ ] **Custom logo?** → Will work in V2 ### 2\. Configuration[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#2-configuration "Direct link to 2. Configuration") * [ ] **Backup settings.yml** before modifying * [ ] **Note UI settings** (appName, homeDescription) * [ ] **Update JWT settings** (enabled → persistence) * [ ] **Remove deprecated sections** (database notifications) ### 3\. Infrastructure[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#3-infrastructure "Direct link to 3. Infrastructure") * [ ] **Backup database** before upgrade * [ ] **Test in staging** environment first * [ ] **Verify HTTPS** configured for production * [ ] **Check browser versions** for users ### 4\. Features[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#4-features "Direct link to 4. Features") * [ ] **Using database notifications?** → Switch to audit logs * [ ] **Custom Calibre path?** → Remove, auto-detection works ### 5\. API Integrations[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#5-api-integrations "Direct link to 5. API Integrations") * [ ] **Using deprecated tool IDs?** → Update to new IDs * [ ] **Update OpenAPI spec** if using generated clients * [ ] **Test API endpoints** in staging * * * 🆘 Troubleshooting[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-troubleshooting "Direct link to 🆘 Troubleshooting") ------------------------------------------------------------------------------------------------------------------------------------- ### "Unknown configuration key" warnings[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#unknown-configuration-key-warnings "Direct link to "Unknown configuration key" warnings") **Symptom:** WARN: Unknown configuration key: premium.proFeatures.googleDrive **Solution:** Remove deprecated settings from settings.yml. See [Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) . * * * ### Custom templates not loading[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#custom-templates-not-loading "Direct link to Custom templates not loading") **Symptom:** Custom navbar/homepage not appearing. **Solution:** Template system removed. Use in-app settings or custom CSS instead. * * * ### Users logged out after upgrade[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#users-logged-out-after-upgrade "Direct link to Users logged out after upgrade") **Symptom:** All users need to re-login after V2 upgrade. **Solution:** Expected behavior due to JWT format change. Users just need to log in once. * * * ### API returns 404 for tool[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#api-returns-404-for-tool "Direct link to API returns 404 for tool") **Symptom:** API call fails with tool not found. **Solution:** Update tool IDs. Example: `pdf-organizer` → `reorganize-pages`. See [Feature Flag Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-feature-flag-changes) . * * * ### App name not showing[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#app-name-not-showing "Direct link to App name not showing") **Symptom:** `ui.appName` in settings.yml not displaying. **Solution:** Setting moved to in-app configuration. Log in as admin, go to Settings → UI. See [UI Settings](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-ui-settings-moved-to-in-app-configuration) . * * * 🔄 Rollback Guide[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-rollback-guide "Direct link to 🔄 Rollback Guide") ---------------------------------------------------------------------------------------------------------------------------------- If you need to return to V1: ### 1\. Stop V2[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#1-stop-v2 "Direct link to 1. Stop V2") docker stop stirling-pdf ### 2\. Restore Database[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#2-restore-database "Direct link to 2. Restore Database") # Option A: Restore from backupdocker exec -i postgres psql -U stirling < backup-before-v2.sql# Option B: Use existing (database is backward compatible for rollback) ### 3\. Restore Settings[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#3-restore-settings "Direct link to 3. Restore Settings") # Restore V1 settings.yml from backupcp settings.yml.v1.backup configs/settings.yml ### 4\. Start V1[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#4-start-v1 "Direct link to 4. Start V1") # Update docker-compose.ymlimage: stirlingtools/stirling-pdf:1.5.0docker-compose up -d ### Data Preservation[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#data-preservation "Direct link to Data Preservation") Your data remains intact: * ✅ User accounts * ✅ API keys * ✅ Configurations * ✅ Custom files * * * 📚 Related Documentation[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-related-documentation "Direct link to 📚 Related Documentation") ------------------------------------------------------------------------------------------------------------------------------------------------------- * **[Migration Overview](https://docs.stirlingpdf.com/Migration/Overview) ** - General upgrade guide * **[New Features](https://docs.stirlingpdf.com/Migration/New-Features) ** - What's new in V2 * **[Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) ** - Configuration updates * **[FAQ](https://docs.stirlingpdf.com/FAQ) ** - Common questions * * * Summary[​](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#summary "Direct link to Summary") ------------------------------------------------------------------------------------------------------ **Breaking changes are minimal:** ✅ Most configurations work unchanged ✅ All data migrates automatically ✅ API compatibility maintained ⚠️ Template customizations need rewrite ⚠️ UI settings moved to in-app config ⚠️ JWT settings renamed **Action required:** 1. Update JWT setting names 2. Remove deprecated configurations 3. Reconfigure UI settings in-app 4. Rewrite template customizations (if any) **Most users can upgrade with minimal changes!** * [⚠️ Impact Summary](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-impact-summary) * [🎨 UI Customization Architecture Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-ui-customization-architecture-changed) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed) * [Migration Path](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-path) * [What No Longer Works](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-no-longer-works) * [⚙️ UI Settings Moved to In-App Configuration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-ui-settings-moved-to-in-app-configuration) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-1) * [Why the Change](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-the-change) * [Migration Steps](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-steps) * [Environment Variables](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#environment-variables) * [🔐 Session Management Improvements](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-session-management-improvements) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-2) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration) * [Environment Variables](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#environment-variables-1) * [After Upgrade](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#after-upgrade) * [🔕 Database Notifications Removed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-database-notifications-removed) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-3) * [Why Removed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-removed) * [Migration to Audit Logs](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-to-audit-logs) * [What You Get Instead](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-you-get-instead) * [🔧 Calibre Custom Path Removed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-calibre-custom-path-removed) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-4) * [Why Removed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-removed-1) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-1) * [Standard Detection Paths](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#standard-detection-paths) * [📦 Docker Image Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-docker-image-changes) * [Tag Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#tag-changes) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-2) * [Backwards Compatibility](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#backwards-compatibility) * [🌐 API Compatibility](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-api-compatibility) * [What Stayed the Same](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-stayed-the-same) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-5) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-3) * [🗄️ Database Schema](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#%EF%B8%8F-database-schema) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-6) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-4) * [Rollback Considerations](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#rollback-considerations) * [📱 Browser Compatibility](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-browser-compatibility) * [Minimum Browser Versions](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#minimum-browser-versions) * [Why the Change](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#why-the-change-1) * [If Users Have Old Browsers](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#if-users-have-old-browsers) * [🔒 Security Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-security-changes) * [HTTPS Enforcement](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#https-enforcement) * [Session Management](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#session-management) * [🎯 Feature Flag Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-feature-flag-changes) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-7) * [Migration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#migration-5) * [📖 Documentation Structure](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-documentation-structure) * [What Changed](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#what-changed-8) * [Old Links](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#old-links) * [✅ Pre-Upgrade Checklist](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-pre-upgrade-checklist) * [1\. Customizations](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#1-customizations) * [2\. Configuration](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#2-configuration) * [3\. Infrastructure](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#3-infrastructure) * [4\. Features](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#4-features) * [5\. API Integrations](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#5-api-integrations) * [🆘 Troubleshooting](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-troubleshooting) * ["Unknown configuration key" warnings](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#unknown-configuration-key-warnings) * [Custom templates not loading](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#custom-templates-not-loading) * [Users logged out after upgrade](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#users-logged-out-after-upgrade) * [API returns 404 for tool](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#api-returns-404-for-tool) * [App name not showing](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#app-name-not-showing) * [🔄 Rollback Guide](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-rollback-guide) * [1\. Stop V2](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#1-stop-v2) * [2\. Restore Database](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#2-restore-database) * [3\. Restore Settings](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#3-restore-settings) * [4\. Start V1](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#4-start-v1) * [Data Preservation](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#data-preservation) * [📚 Related Documentation](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#-related-documentation) * [Summary](https://docs.stirlingpdf.com/Migration/Breaking-Changes/#summary) --- # Path Structure | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Path%20Structure/#__docusaurus_skipToContent_fallback) On this page Server Deployment[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#server-deployment "Direct link to Server Deployment") --------------------------------------------------------------------------------------------------------------------------------------- When running in server mode, the base path defaults to `./` (current directory) Desktop Deployment[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#desktop-deployment "Direct link to Desktop Deployment") ------------------------------------------------------------------------------------------------------------------------------------------ When running as a desktop application (non-server deployment), the base path is set according to the operating system: * **Windows**: `%APPDATA%\Stirling-PDF\` * **macOS**: `~/Library/Application Support/Stirling-PDF/` * **Linux/Unix**: `~/.config/Stirling-PDF/` Directory Structure =================== All paths below are relative to the BASE\_PATH. The File.separator ensures cross-platform compatibility. Root Directories[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#root-directories "Direct link to Root Directories") ------------------------------------------------------------------------------------------------------------------------------------ * `logs/` - Application logs storage * `configs/` - Configuration files * `pipeline/` - Pipeline-related operations * `customFiles/` - Custom assets and templates * `clientWebUI/` - Web interface assets Configuration Files[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#configuration-files "Direct link to Configuration Files") --------------------------------------------------------------------------------------------------------------------------------------------- * `configs/settings.yml` - Main settings file * `configs/custom_settings.yml` - User-specific settings Pipeline Directories[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#pipeline-directories "Direct link to Pipeline Directories") ------------------------------------------------------------------------------------------------------------------------------------------------ * `pipeline/watchedFolders/` - Monitored directories for automated processing * `pipeline/finishedFolders/` - Completed processing output location Custom Files Structure[​](https://docs.stirlingpdf.com/Installation/Path%20Structure/#custom-files-structure "Direct link to Custom Files Structure") ------------------------------------------------------------------------------------------------------------------------------------------------------ * `customFiles/static/` - Static asset overrides (logos, images, favicons, etc.) * `customFiles/templates/` - Legacy template files (deprecated, not used) * `customFiles/signatures/` - Digital signature files * [Server Deployment](https://docs.stirlingpdf.com/Installation/Path%20Structure/#server-deployment) * [Desktop Deployment](https://docs.stirlingpdf.com/Installation/Path%20Structure/#desktop-deployment) * [Root Directories](https://docs.stirlingpdf.com/Installation/Path%20Structure/#root-directories) * [Configuration Files](https://docs.stirlingpdf.com/Installation/Path%20Structure/#configuration-files) * [Pipeline Directories](https://docs.stirlingpdf.com/Installation/Path%20Structure/#pipeline-directories) * [Custom Files Structure](https://docs.stirlingpdf.com/Installation/Path%20Structure/#custom-files-structure) --- # New Features in V2 | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Migration/New-Features/#__docusaurus_skipToContent_fallback) On this page V2 brings powerful new features that fundamentally improve how you work with PDFs. This page documents everything new in V2. * * * 📁 Browser File Storage[​](https://docs.stirlingpdf.com/Migration/New-Features/#-browser-file-storage "Direct link to 📁 Browser File Storage") ------------------------------------------------------------------------------------------------------------------------------------------------ **The Game Changer:** Upload PDFs once, use them across multiple tools without re-uploading. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new "Direct link to What's New") * **Persistent Storage:** Files stored locally in your browser using IndexedDB * **Cross-Tool Usage:** Access uploaded files from any tool * **Smart Management:** Automatic cleanup, manual delete options * **Large File Support:** Up to 10GB storage (browser-dependent) ### How It Works[​](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works "Direct link to How It Works") Upload PDF → Stored in Browser → Use in Any Tool → Delete When Done **Example Workflow:** 1. Upload `report.pdf` in Multi-Tool 2. Compress it 3. Switch to Add Page Numbers (file still there!) 4. Add watermark (still no re-upload!) 5. Download final result ### Storage Limits[​](https://docs.stirlingpdf.com/Migration/New-Features/#storage-limits "Direct link to Storage Limits") | Browser | Storage Limit | Notes | | --- | --- | --- | | Chrome/Edge | ~10GB | 60% of available disk space | | Firefox | ~10GB | User-configurable | | Safari | ~1GB | More restrictive | * * * ⏮️ Undo, Redo & Version History[​](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-undo-redo--version-history "Direct link to ⏮️ Undo, Redo & Version History") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Made a mistake?** Just undo it! V2 introduces comprehensive version control. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-1 "Direct link to What's New") * **Undo/Redo:** Undo and redo buttons in toolbar * **Version History:** See all previous versions with timestamps * **Jump to Version:** Restore any previous state * **Visual Indicators:** See current version in timeline * **All Local:** History stored in your browser, fully private ### How It Works[​](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-1 "Direct link to How It Works") Every operation creates a new version: Original.pdf → [Compress] → v1 → [Add Pages] → v2 → [Watermark] → v3 ↑ ↑ ↑ ↑ Can restore to any point in history ### Accessing Features[​](https://docs.stirlingpdf.com/Migration/New-Features/#accessing-features "Direct link to Accessing Features") * **Undo Button:** Click undo in toolbar * **Redo Button:** Click redo in toolbar * **History Panel:** Click history icon in Multi-Tool ### Example Use Case[​](https://docs.stirlingpdf.com/Migration/New-Features/#example-use-case "Direct link to Example Use Case") **Scenario:** You compressed a PDF too aggressively and text is blurry. **Solution:** 1. Click undo button to undo compression 2. Open Version History panel 3. See: Original → Compress (MEDIUM) ← You are here 4. Click "Restore" on Original 5. Re-compress with LIGHT setting instead * * * 🖥️ Desktop Applications[​](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-desktop-applications "Direct link to 🖥️ Desktop Applications") ----------------------------------------------------------------------------------------------------------------------------------------------------------- **NEW:** Native desktop apps for Windows, Mac, and Linux. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-2 "Direct link to What's New") * **Lightning Fast:** 0.3 second startup time * **Native Integration:** "Open with Stirling PDF" in file explorer * **System Default:** Set as default PDF viewer * **Sign in with Stirling Cloud or self-hosted server** - Choose your connection on launch * **Resource Efficient:** Uses ~50MB RAM vs browser ~200MB ### Platform Support[​](https://docs.stirlingpdf.com/Migration/New-Features/#platform-support "Direct link to Platform Support") | Platform | Format | Features | | --- | --- | --- | | **Windows** | `.exe` installer | Context menu integration | | **macOS** | `.dmg` | Dock integration | | **Linux** | `.deb` | Desktop file integration | ### Key Differences from Web[​](https://docs.stirlingpdf.com/Migration/New-Features/#key-differences-from-web "Direct link to Key Differences from Web") | Feature | Desktop | Web Browser | | --- | --- | --- | | Startup Speed | 0.3s | 2-3s | | File Association | ✅ Yes | ❌ No | | Default Viewer | ✅ Yes | ❌ No | | System Integration | ✅ Native | ⚠️ Limited | | Storage | Unlimited | Browser limits | | Updates | Manual | Automatic | ### Right-Click Integration[​](https://docs.stirlingpdf.com/Migration/New-Features/#right-click-integration "Direct link to Right-Click Integration") After installation: 1. Right-click any PDF in file explorer 2. Select "Open with Stirling PDF" 3. PDF opens directly in app 4. Sign in (if needed) 5. Process immediately **Learn More:** * [Windows Installation](https://docs.stirlingpdf.com/Installation/Windows%20Installation) * [Mac Installation](https://docs.stirlingpdf.com/Installation/Mac%20Installation) * [Linux Installation](https://docs.stirlingpdf.com/Installation/Unix%20Installation) * * * * * * ⌨️ Custom Keyboard Shortcuts[​](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-custom-keyboard-shortcuts "Direct link to ⌨️ Custom Keyboard Shortcuts") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **NEW:** Configure your own keyboard shortcuts for quick tool access. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-3 "Direct link to What's New") * **Custom Hotkeys:** Assign keyboard shortcuts to any tool * **Quick Access:** Default shortcuts for 7 most popular tools (Cmd/Ctrl+Alt+1-7) * **Flexible Mapping:** Use any combination of Ctrl, Alt, Shift, Cmd keys * **Visual Feedback:** See all shortcuts in settings * **Conflict Detection:** Prevents duplicate shortcut assignments * **Easy Reset:** Restore default shortcuts anytime ### Default Shortcuts[​](https://docs.stirlingpdf.com/Migration/New-Features/#default-shortcuts "Direct link to Default Shortcuts") The 7 Recommended Tools come with pre-configured shortcuts: | Tool | Windows/Linux | Mac | | --- | --- | --- | | Multi-Tool | Ctrl+Alt+1 | Cmd+Option+1 | | Read & Annotate | Ctrl+Alt+2 | Cmd+Option+2 | | Merge | Ctrl+Alt+3 | Cmd+Option+3 | | Compare | Ctrl+Alt+4 | Cmd+Option+4 | | Compress | Ctrl+Alt+5 | Cmd+Option+5 | | OCR | Ctrl+Alt+6 | Cmd+Option+6 | | Redact | Ctrl+Alt+7 | Cmd+Option+7 | ### Customizing Shortcuts[​](https://docs.stirlingpdf.com/Migration/New-Features/#customizing-shortcuts "Direct link to Customizing Shortcuts") **To configure:** 1. Open Settings (gear icon) 2. Navigate to "Keyboard Shortcuts" section 3. Find the tool you want to assign 4. Click "Set Shortcut" 5. Press your desired key combination 6. Save changes **Example:** * Want to open Convert with Ctrl+Alt+C? * Navigate to Convert tool in shortcuts list * Click "Set Shortcut" * Press Ctrl+Alt+C ### Tips[​](https://docs.stirlingpdf.com/Migration/New-Features/#tips "Direct link to Tips") * **Don't override browser shortcuts:** Avoid Ctrl+T, Ctrl+W, etc. * **Use Alt/Option combos:** Less likely to conflict with system shortcuts * **Keep it memorable:** Use letters that relate to tool names * **Test after setting:** Make sure shortcuts work in practice * * * ⚙️ In-App Settings Management[​](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-in-app-settings-management "Direct link to ⚙️ In-App Settings Management") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **NEW:** Configure everything through the UI (admin only). ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-4 "Direct link to What's New") * **Visual Configuration:** No more editing YAML files * **Instant Validation:** See errors before saving * **Live Preview:** Some settings apply immediately * **Organized Sections:** Settings grouped logically * **Search Settings:** Find what you need quickly * **Import/Export:** Backup and restore configurations ### Settings You Can Configure[​](https://docs.stirlingpdf.com/Migration/New-Features/#settings-you-can-configure "Direct link to Settings You Can Configure") **System:** * Default locale and timezone * Resource limits * Logging levels * CORS origins **Security:** * Login requirements * User registration * Session timeout * Password policies **UI Customization:** * App name and description * Logo style (classic/modern) * Navbar branding * Homepage content **Features:** * Enable/disable tools * Endpoint customization * OCR languages * Conversion settings ### How to Access[​](https://docs.stirlingpdf.com/Migration/New-Features/#how-to-access "Direct link to How to Access") 1. Enable login: `SECURITY_ENABLELOGIN=true` 2. Log in as admin 3. Click Settings icon in navbar 4. Configure through UI 5. Save changes **Benefits Over File Configuration:** * No container restart needed (for most settings) * Validation prevents errors * Changes tracked in audit log * Role-based access control * * * 🔐 PDF Signature Validation[​](https://docs.stirlingpdf.com/Migration/New-Features/#-pdf-signature-validation "Direct link to 🔐 PDF Signature Validation") ------------------------------------------------------------------------------------------------------------------------------------------------------------ **NEW:** Comprehensive certificate chain validation for signed PDFs. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-5 "Direct link to What's New") Full trust chain validation system: * **Multiple Trust Sources:** * System trust store * Mozilla CA bundle * Adobe Approved Trust List (AATL) * EU Trusted List (EUTL) * Server-generated anchor certificates * **Revocation Checking:** * OCSP (Online Certificate Status Protocol) * CRL (Certificate Revocation Lists) * Configurable hard/soft fail * **AIA (Authority Information Access):** * Automatic intermediate cert fetching * Chain building support ### Configuration[​](https://docs.stirlingpdf.com/Migration/New-Features/#configuration "Direct link to Configuration") security: validation: trust: serverAsAnchor: true # Trust server-generated certs useSystemTrust: true # Use OS trust store useMozillaBundle: true # Mozilla CA certificates useAATL: false # Adobe trust list useEUTL: false # EU trust list allowAIA: false # Fetch intermediate certs revocation: mode: none # none, ocsp, crl, ocsp+crl hardFail: false # Fail if revocation check fails ### Use Cases[​](https://docs.stirlingpdf.com/Migration/New-Features/#use-cases "Direct link to Use Cases") **Enterprise:** * Validate invoices signed by partners * Verify contract signatures * Compliance with legal requirements **Government:** * Validate officially signed documents * EU eIDAS compliance * EUTL integration **General:** * Verify PDF authenticity * Check if signature still valid * Detect tampered documents **Learn More:** [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) * * * 🔑 Server Certificate Management[​](https://docs.stirlingpdf.com/Migration/New-Features/#-server-certificate-management "Direct link to 🔑 Server Certificate Management") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **NEW:** Automatic certificate generation for signing PDFs. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-6 "Direct link to What's New") * **Auto-Generated Certs:** Server creates signing certificates on startup * **Customizable:** Configure organization name, validity period * **No Manual Setup:** Works out of the box * **Renewable:** Regenerate certificates as needed * **"Sign with Stirling PDF" Feature:** Users can sign with server cert ### Configuration[​](https://docs.stirlingpdf.com/Migration/New-Features/#configuration-1 "Direct link to Configuration") system: serverCertificate: enabled: true organizationName: Stirling-PDF validity: 365 # days regenerateOnStartup: false ### How It Works[​](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-2 "Direct link to How It Works") 1. **First Startup:** * Server generates self-signed certificate * Stored in `configs/` directory * Used for "Sign with Stirling PDF" feature 2. **Subsequent Startups:** * Uses existing certificate (unless `regenerateOnStartup: true`) * Certificate persists across restarts 3. **User Signs PDF:** * Selects "Sign with Stirling PDF" * Server signs using generated certificate * Signature embedded in PDF ### Custom Certificates[​](https://docs.stirlingpdf.com/Migration/New-Features/#custom-certificates "Direct link to Custom Certificates") You can also provide your own certificates: configs/ ├── keystore.p12 # Your certificate └── settings.yml Then disable auto-generation: system: serverCertificate: enabled: false # Use custom cert instead **Learn More:** * [Certificate Signing Guide](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) * [Configuration](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#server-certificates) * * * 🎯 Multi-Tool Workbench[​](https://docs.stirlingpdf.com/Migration/New-Features/#-multi-tool-workbench "Direct link to 🎯 Multi-Tool Workbench") ------------------------------------------------------------------------------------------------------------------------------------------------ **NEW:** Dedicated workspace for chaining unlimited operations. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-7 "Direct link to What's New") * **Visual Workbench:** See all loaded files and their history * **Unlimited Operations:** Chain as many tools as needed * **Operation History:** See what you've done to each file * **Undo/Redo:** Per-file version control * **Batch Processing:** Process multiple files simultaneously * **Result Management:** Keep, download, or discard results ### Example Workflow[​](https://docs.stirlingpdf.com/Migration/New-Features/#example-workflow "Direct link to Example Workflow") Multi-Tool Workbench├── invoice.pdf│ ├── [Original]│ ├── [OCR - English]│ ├── [Compress - MEDIUM]│ └── [Add Page Numbers] ← Current├── report.pdf│ ├── [Original]│ └── [Add Watermark] ← Current└── contract.pdf └── [Original] ← No operations yet ### Key Features[​](https://docs.stirlingpdf.com/Migration/New-Features/#key-features "Direct link to Key Features") 1. **Smart Tool Switching:** * Switch tools without losing files * Context preserved between operations * No re-uploading needed 2. **Operation Queue:** * See pending operations * Reorder before processing * Cancel if needed 3. **Result Preview:** * Preview before downloading * Compare before/after * Verify operations succeeded **Learn More:** [Multi-Tool Workbench Guide](https://docs.stirlingpdf.com/Functionality/Multi-Tool) * * * 📖 Read & Annotate Tool[​](https://docs.stirlingpdf.com/Migration/New-Features/#-read--annotate-tool "Direct link to 📖 Read & Annotate Tool") ----------------------------------------------------------------------------------------------------------------------------------------------- **NEW:** Full-featured PDF viewer with annotation capabilities. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-8 "Direct link to What's New") * **PDF Viewer:** Read PDFs directly in browser * **Annotation Tools:** * Highlight text * Add comments * Draw shapes * Insert text boxes * Sticky notes * **Navigation:** * Thumbnail sidebar * Table of contents * Page search * Zoom controls * **Collaboration:** * Export annotations * Share annotated PDFs * Comment threads ### Use Cases[​](https://docs.stirlingpdf.com/Migration/New-Features/#use-cases-1 "Direct link to Use Cases") **Review:** * Mark up documents for approval * Add review comments * Highlight important sections **Collaboration:** * Annotate contracts before signing * Review proposals with team * Provide feedback on drafts **Study:** * Highlight key passages * Add study notes * Mark important pages ### Annotation Types[​](https://docs.stirlingpdf.com/Migration/New-Features/#annotation-types "Direct link to Annotation Types") | Tool | Use Case | Example | | --- | --- | --- | | **Highlight** | Mark important text | Legal clauses | | **Comment** | Add feedback | "Needs revision" | | **Text Box** | Add missing text | Corrections | | **Shape** | Circle/underline | Draw attention | | **Sticky Note** | Quick notes | "Follow up" | **Learn More:** [Read & Annotate Guide](https://docs.stirlingpdf.com/Functionality/Read-and-Annotate) * * * 🔄 Enhanced Session Management[​](https://docs.stirlingpdf.com/Migration/New-Features/#-enhanced-session-management "Direct link to 🔄 Enhanced Session Management") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Improved:** Better session and token management with rotation and cleanup. ### What's New in V2[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-in-v2 "Direct link to What's New in V2") | Feature | V1 | V2 | | --- | --- | --- | | Token Persistence | Optional | Configurable | | Key Rotation | ❌ No | ✅ Yes | | Key Cleanup | Manual | Automatic | | Key Retention | N/A | Configurable days | | Secure Cookie | Hardcoded | Removed (always secure) | ### New Settings[​](https://docs.stirlingpdf.com/Migration/New-Features/#new-settings "Direct link to New Settings") security: jwt: persistence: true # Store keys across restarts enableKeyRotation: true # Rotate signing keys periodically enableKeyCleanup: true # Auto-delete old keys keyRetentionDays: 7 # How long to keep old keys ### Benefits[​](https://docs.stirlingpdf.com/Migration/New-Features/#benefits "Direct link to Benefits") **Key Rotation:** * Improved security through regular key changes * Seamless for users (old tokens still work during grace period) * Configurable rotation schedule **Automatic Cleanup:** * No manual key management needed * Prevents key accumulation * Configurable retention period **Persistence:** * Keys survive container restarts * No user re-login after restart * Optional for stateless deployments * * * ✉️ Email Invitation System[​](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-email-invitation-system "Direct link to ✉️ Email Invitation System") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ **NEW:** Invite users via email instead of manual registration. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-9 "Direct link to What's New") * **Email Invites:** Send registration links via email * **Token-Based:** Secure one-time registration tokens * **Expiration:** Invites expire after configurable period * **Role Assignment:** Set user role in invite * **Bulk Invites:** Invite multiple users at once ### Configuration[​](https://docs.stirlingpdf.com/Migration/New-Features/#configuration-2 "Direct link to Configuration") mail: enabled: true from: [email protected] smtp: host: smtp.example.com port: 587 username: [email protected] password: ${MAIL_PASSWORD} ### Requirements[​](https://docs.stirlingpdf.com/Migration/New-Features/#requirements "Direct link to Requirements") * `mail.enabled: true` * `security.enableLogin: true` * Valid SMTP configuration ### How It Works[​](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-3 "Direct link to How It Works") **Admin perspective:** 1. Go to User Management 2. Click "Invite User" 3. Enter email and select role 4. Send invite **User perspective:** 1. Receive email with invite link 2. Click link (valid for 48 hours) 3. Create account with password 4. Automatically logged in ### Environment Variables[​](https://docs.stirlingpdf.com/Migration/New-Features/#environment-variables "Direct link to Environment Variables") MAIL_ENABLED=trueMAIL_FROM=[email protected]MAIL_ENABLEINVITES=trueMAIL_HOST=smtp.gmail.comMAIL_PORT=587MAIL_USERNAME=[email protected]MAIL_PASSWORD=your-app-passwordMAIL_TLS_ENABLED=true * * * 🎨 Logo Customization[​](https://docs.stirlingpdf.com/Migration/New-Features/#-logo-customization "Direct link to 🎨 Logo Customization") ------------------------------------------------------------------------------------------------------------------------------------------ **NEW:** Choose between logo styles and customize branding. ### What's New[​](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-10 "Direct link to What's New") ui: logoStyle: classic # Options: 'classic' or 'modern' ### Logo Styles[​](https://docs.stirlingpdf.com/Migration/New-Features/#logo-styles "Direct link to Logo Styles") | Style | Description | Best For | | --- | --- | --- | | **Classic** | Traditional "S" icon | Established brands | | **Modern** | Minimalist design | Clean, modern look | ### Custom Logo[​](https://docs.stirlingpdf.com/Migration/New-Features/#custom-logo "Direct link to Custom Logo") You can still provide custom logo files: customFiles/ └── static/ └── logo.svg # Your custom logo Then reference in settings: ui: appNameNavbar: 'My Company PDF' logoStyle: classic # Or use custom logo * * * Summary[​](https://docs.stirlingpdf.com/Migration/New-Features/#summary "Direct link to Summary") -------------------------------------------------------------------------------------------------- **V2's Major Features:** * 📁 **Browser File Storage** - Upload once, use across multiple tools * ⏮️ **Undo/Redo & Version History** - Never lose work * 🖥️ **Desktop Applications** - Native Windows, Mac, Linux apps * 🎨 **Multi-Tool Workbench** - Chain unlimited operations * 📖 **Read & Annotate** - Full PDF viewer with annotation support * ⚙️ **In-App Settings** - Configure everything through UI * 🔐 **Enhanced Security** - PDF signature validation, server certificates * ✉️ **Email Invitations** - Streamlined user onboarding * ⌨️ **Custom Keyboard Shortcuts** - Quick tool access * 🔄 **Enhanced Session Management** - Better token management with rotation * * * Learn More[​](https://docs.stirlingpdf.com/Migration/New-Features/#learn-more "Direct link to Learn More") ----------------------------------------------------------------------------------------------------------- * **[Migration Overview](https://docs.stirlingpdf.com/Migration/Overview) ** - How to upgrade * **[Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes) ** - Configuration updates * **[Breaking Changes](https://docs.stirlingpdf.com/Migration/Breaking-Changes) ** - What changed * **[Getting Started](https://docs.stirlingpdf.com/) ** - Start using V2 * [📁 Browser File Storage](https://docs.stirlingpdf.com/Migration/New-Features/#-browser-file-storage) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new) * [How It Works](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works) * [Storage Limits](https://docs.stirlingpdf.com/Migration/New-Features/#storage-limits) * [⏮️ Undo, Redo & Version History](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-undo-redo--version-history) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-1) * [How It Works](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-1) * [Accessing Features](https://docs.stirlingpdf.com/Migration/New-Features/#accessing-features) * [Example Use Case](https://docs.stirlingpdf.com/Migration/New-Features/#example-use-case) * [🖥️ Desktop Applications](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-desktop-applications) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-2) * [Platform Support](https://docs.stirlingpdf.com/Migration/New-Features/#platform-support) * [Key Differences from Web](https://docs.stirlingpdf.com/Migration/New-Features/#key-differences-from-web) * [Right-Click Integration](https://docs.stirlingpdf.com/Migration/New-Features/#right-click-integration) * [⌨️ Custom Keyboard Shortcuts](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-custom-keyboard-shortcuts) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-3) * [Default Shortcuts](https://docs.stirlingpdf.com/Migration/New-Features/#default-shortcuts) * [Customizing Shortcuts](https://docs.stirlingpdf.com/Migration/New-Features/#customizing-shortcuts) * [Tips](https://docs.stirlingpdf.com/Migration/New-Features/#tips) * [⚙️ In-App Settings Management](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-in-app-settings-management) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-4) * [Settings You Can Configure](https://docs.stirlingpdf.com/Migration/New-Features/#settings-you-can-configure) * [How to Access](https://docs.stirlingpdf.com/Migration/New-Features/#how-to-access) * [🔐 PDF Signature Validation](https://docs.stirlingpdf.com/Migration/New-Features/#-pdf-signature-validation) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-5) * [Configuration](https://docs.stirlingpdf.com/Migration/New-Features/#configuration) * [Use Cases](https://docs.stirlingpdf.com/Migration/New-Features/#use-cases) * [🔑 Server Certificate Management](https://docs.stirlingpdf.com/Migration/New-Features/#-server-certificate-management) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-6) * [Configuration](https://docs.stirlingpdf.com/Migration/New-Features/#configuration-1) * [How It Works](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-2) * [Custom Certificates](https://docs.stirlingpdf.com/Migration/New-Features/#custom-certificates) * [🎯 Multi-Tool Workbench](https://docs.stirlingpdf.com/Migration/New-Features/#-multi-tool-workbench) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-7) * [Example Workflow](https://docs.stirlingpdf.com/Migration/New-Features/#example-workflow) * [Key Features](https://docs.stirlingpdf.com/Migration/New-Features/#key-features) * [📖 Read & Annotate Tool](https://docs.stirlingpdf.com/Migration/New-Features/#-read--annotate-tool) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-8) * [Use Cases](https://docs.stirlingpdf.com/Migration/New-Features/#use-cases-1) * [Annotation Types](https://docs.stirlingpdf.com/Migration/New-Features/#annotation-types) * [🔄 Enhanced Session Management](https://docs.stirlingpdf.com/Migration/New-Features/#-enhanced-session-management) * [What's New in V2](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-in-v2) * [New Settings](https://docs.stirlingpdf.com/Migration/New-Features/#new-settings) * [Benefits](https://docs.stirlingpdf.com/Migration/New-Features/#benefits) * [✉️ Email Invitation System](https://docs.stirlingpdf.com/Migration/New-Features/#%EF%B8%8F-email-invitation-system) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-9) * [Configuration](https://docs.stirlingpdf.com/Migration/New-Features/#configuration-2) * [Requirements](https://docs.stirlingpdf.com/Migration/New-Features/#requirements) * [How It Works](https://docs.stirlingpdf.com/Migration/New-Features/#how-it-works-3) * [Environment Variables](https://docs.stirlingpdf.com/Migration/New-Features/#environment-variables) * [🎨 Logo Customization](https://docs.stirlingpdf.com/Migration/New-Features/#-logo-customization) * [What's New](https://docs.stirlingpdf.com/Migration/New-Features/#whats-new-10) * [Logo Styles](https://docs.stirlingpdf.com/Migration/New-Features/#logo-styles) * [Custom Logo](https://docs.stirlingpdf.com/Migration/New-Features/#custom-logo) * [Summary](https://docs.stirlingpdf.com/Migration/New-Features/#summary) * [Learn More](https://docs.stirlingpdf.com/Migration/New-Features/#learn-more) --- # Certificate Signing | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#__docusaurus_skipToContent_fallback) On this page Digitally sign PDFs with X.509 certificates and validate existing signatures against trusted certificate chains. * * * Signing PDFs[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#signing-pdfs "Direct link to Signing PDFs") ------------------------------------------------------------------------------------------------------------------------------------- * Server Certificate * Custom Certificate * Organization Certificate Easiest option - uses an auto-generated server certificate. No setup needed for users. 1. Go to **Certificate Sign** tool 2. Upload PDF 3. Select "Sign with Stirling PDF" 4. Configure signature appearance (optional) 5. Sign and download **Configuration:** * Settings File * Environment Variable system: serverCertificate: enabled: true organizationName: Stirling-PDF validity: 365 regenerateOnStartup: false SYSTEM_SERVERCERTIFICATE_ENABLED=trueSYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"SYSTEM_SERVERCERTIFICATE_VALIDITY=365 Use your own X.509 certificate (PKCS#12 `.p12`/`.pfx` or PEM format). 1. Go to **Certificate Sign** tool 2. Upload PDF 3. Select "Upload Certificate" 4. Upload certificate file and enter password 5. Configure signature appearance 6. Sign and download # Generate a test certificateopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365# Convert to PKCS#12openssl pkcs12 -export -out mycert.p12 -inkey key.pem -in cert.pem Place your organization certificate in the configs directory so all users can sign without uploading their own: configs/ └── keystore.p12 system: serverCertificate: enabled: false # Disable auto-generation KEYSTORE_PASSWORD=your-password Users will see a "Sign with \[Organization Name\]" option. * * * ### Signature Appearance[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#signature-appearance "Direct link to Signature Appearance") **Visible:** Appears as a box on the PDF page with configurable position, size, page, and displayed text (name, date, reason). **Invisible:** Embedded in PDF metadata only, not visible on the page. * * * Validating Signatures[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#validating-signatures "Direct link to Validating Signatures") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Verify that a PDF was signed by the claimed certificate, the certificate is trusted, the PDF hasn't been modified, and the certificate hasn't been revoked. ### Trust Sources[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#trust-sources "Direct link to Trust Sources") | Source | Config Key | What It Trusts | | --- | --- | --- | | Server certificates | `serverAsAnchor` | PDFs signed by your Stirling PDF instance | | System trust store | `useSystemTrust` | OS-trusted CAs | | Mozilla CA bundle | `useMozillaBundle` | Mozilla's curated CA list | | Adobe AATL | `useAATL` | Adobe Approved Trust List | | EU EUTL | `useEUTL` | EU Trusted List (eIDAS) | ### Revocation Checking[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#revocation-checking "Direct link to Revocation Checking") Certificates can be revoked (invalidated) after they're issued - for example if a private key is compromised. Revocation checking lets Stirling PDF verify that a certificate is still valid at the time of use. security: validation: revocation: mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false | Mode | What it does | | --- | --- | | `none` | Skip revocation checks entirely | | `ocsp` | Check in real-time against the certificate authority's server (requires internet) | | `crl` | Download a list of revoked certificates (can work offline with cached lists) | | `ocsp+crl` | Try real-time check first, fall back to the list if that fails | **`hardFail`** controls what happens when the revocation check itself fails (e.g. server unreachable): * `false` (default) - validation passes with a warning * `true` - validation fails entirely. Use this in high-security environments where you'd rather reject a signature than skip the check. * * * Configuration Examples[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#configuration-examples "Direct link to Configuration Examples") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Minimal (Default) * Enterprise * High-Security * EU eIDAS system: serverCertificate: enabled: truesecurity: validation: trust: serverAsAnchor: true useSystemTrust: true system: serverCertificate: enabled: true organizationName: Acme Corp validity: 365security: validation: trust: serverAsAnchor: true useSystemTrust: true useMozillaBundle: true useAATL: false allowAIA: false revocation: mode: ocsp hardFail: false security: validation: trust: serverAsAnchor: false useSystemTrust: true useMozillaBundle: true useAATL: true useEUTL: true allowAIA: false revocation: mode: ocsp+crl hardFail: true security: validation: trust: serverAsAnchor: false useSystemTrust: false useMozillaBundle: false useAATL: false useEUTL: true eutl: lotlUrl: https://ec.europa.eu/tools/lotl/eu-lotl.xml acceptTransitional: true allowAIA: false revocation: mode: ocsp+crl hardFail: true * * * API Usage[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#api-usage "Direct link to API Usage") ---------------------------------------------------------------------------------------------------------------------------- * Sign (Server Cert) * Sign (Custom Cert) * Validate curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ -F "[email protected]" \ -F "certType=server" \ -F "reason=Approved" \ -F "location=bottom-right" \ -F "showSignature=true" \ -o signed.pdf curl -X POST http://stirling-pdf:8080/api/v1/security/cert-sign \ -F "[email protected]" \ -F "certType=custom" \ -F "[email protected]" \ -F "password=certpass" \ -o signed.pdf curl -X POST http://stirling-pdf:8080/api/v1/security/validate-signature \ -F "[email protected]" See [API Documentation](https://docs.stirlingpdf.com/API) for complete endpoint reference. * * * Troubleshooting[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------------------------------------------------------------------------------- ### "Certificate not trusted"[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#certificate-not-trusted "Direct link to "Certificate not trusted"") Enable the appropriate trust source in config, or add your CA certificate to the system trust store: docker cp ca-cert.crt stirling-pdf:/usr/local/share/ca-certificates/docker exec stirling-pdf update-ca-certificates ### Revocation check fails[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#revocation-check-fails "Direct link to Revocation check fails") Check that the container has HTTPS access to OCSP/CRL servers. Use `hardFail: false` or switch to `crl` mode for restricted networks. ### Server certificate not generated[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#server-certificate-not-generated "Direct link to Server certificate not generated") Ensure `SYSTEM_SERVERCERTIFICATE_ENABLED=true` is set. Check logs with `docker logs stirling-pdf | grep -i certificate`. * * * Related[​](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#related "Direct link to Related") ---------------------------------------------------------------------------------------------------------------------- * [System and Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security#signature-validation) * [Sign (Handwritten)](https://docs.stirlingpdf.com/Functionality/Security/Sign) * [Settings Changes](https://docs.stirlingpdf.com/Migration/Settings-Changes#pdf-signature-validation) * [Signing PDFs](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#signing-pdfs) * [Signature Appearance](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#signature-appearance) * [Validating Signatures](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#validating-signatures) * [Trust Sources](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#trust-sources) * [Revocation Checking](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#revocation-checking) * [Configuration Examples](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#configuration-examples) * [API Usage](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#api-usage) * [Troubleshooting](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#troubleshooting) * ["Certificate not trusted"](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#certificate-not-trusted) * [Revocation check fails](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#revocation-check-fails) * [Server certificate not generated](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#server-certificate-not-generated) * [Related](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing/#related) --- # Manual Redaction | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#__docusaurus_skipToContent_fallback) On this page Overview[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#overview "Direct link to Overview") ------------------------------------------------------------------------------------------------------------------- The Document Redaction Tool allows you to securely redact sensitive information from documents using three different methods: text selection, area drawing, or entire page redaction. Redaction Methods[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#redaction-methods "Direct link to Redaction Methods") ---------------------------------------------------------------------------------------------------------------------------------------------- ### 1\. Text Selection Redaction[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#1-text-selection-redaction "Direct link to 1. Text Selection Redaction") Perfect for redacting specific words, sentences, or paragraphs. **How to use:** 1. Click the text selection icon in the toolbar ![image](https://github.com/user-attachments/assets/e66dbfc1-0b06-4f65-8f60-7277b8acca91) 2. Select the text you want to redact 3. Apply the redaction by either: * Pressing `Ctrl + S` * Clicking the save icon in the toolbar ![image](https://github.com/user-attachments/assets/73d4b1f0-a454-452b-ab60-028b9728004b) ### 2\. Area Drawing Redaction[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#2-area-drawing-redaction "Direct link to 2. Area Drawing Redaction") Ideal for redacting images, tables, or irregular content blocks. **How to use:** 1. Click the drawing tool icon in the toolbar ![image](https://github.com/user-attachments/assets/8597abed-0992-48d3-baf4-0e7673fb500c) 2. Click and hold at your starting point 3. Drag to create a rectangle over the area 4. Click again to confirm and apply the redaction * A red border means unsaved ![image](https://github.com/user-attachments/assets/42809be3-34e6-4725-920b-b4d51eb72e4f) * A green border means saved and active ![image](https://github.com/user-attachments/assets/0711ff11-da1a-41c3-9d57-82067ee0f8b8) ### 3\. Page Redaction[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#3-page-redaction "Direct link to 3. Page Redaction") Used when you need to redact entire pages. **How to use:** 1. Open the page redaction dialog ![image](https://github.com/user-attachments/assets/fae58a19-1f54-463e-bc81-027bd4f403bf) ![image](https://github.com/user-attachments/assets/66c1b1aa-7da1-4262-a476-0551924ed509) 2. Enter page numbers or ranges (e.g., "1,3-5,7") 3. Select your preferred color 4. Click "Apply" to save changes Customizing Redactions[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#customizing-redactions "Direct link to Customizing Redactions") ------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Changing Colors[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#changing-colors "Direct link to Changing Colors") **For new redactions:** 1. Click the color palette icon in the toolbar ![image](https://github.com/user-attachments/assets/788fd325-489e-4404-8377-07ec500a77dd) 2. Select your preferred color 3. Any new redactions will use this color **For existing redactions:** 1. Click the redacted area 2. Click the color palette icon that appears 3. Choose your new color ![redaction_color](https://github.com/user-attachments/assets/0bc05461-6427-4a62-8cd4-745c3104c04f) ### Removing Redactions[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#removing-redactions "Direct link to Removing Redactions") 1. Click the redacted area you want to remove 2. Either: * Click the trash icon that appears * Press the `Delete` key ![redaction_removal](https://github.com/user-attachments/assets/9bd3be2a-d2ec-4468-a229-bf81efb36bcc) ### Converting PDF to PDF-image (Used in removing text behind the box)[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#converting-pdf-to-pdf-image-used-in-removing-text-behind-the-box "Direct link to Converting PDF to PDF-image (Used in removing text behind the box)") To enable PDF to PDF-image option: 1. Click on the image icon ![image](https://github.com/user-attachments/assets/8c480923-05e1-46d3-8f59-5f78db6d87f8) To disable PDF to PDF-image option: 1. Click on the image icon ![image](https://github.com/user-attachments/assets/e2e07e31-8eb0-41ac-80ab-ffd8520f5795) * If the image icon is green, then the option is enabled, if it is red then it is disabled. Keyboard Shortcuts[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#keyboard-shortcuts "Direct link to Keyboard Shortcuts") ------------------------------------------------------------------------------------------------------------------------------------------------- * `Ctrl + S`: Save/apply redaction * `Delete`: Remove selected redaction * `Escape`: Cancel unsaved area drawing Tips[​](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#tips "Direct link to Tips") ------------------------------------------------------------------------------------------------------- * If you're in drawing mode and need to delete a redaction, temporarily disable drawing mode first * You can combine different redaction methods in the same document * Always review your redactions before finalizing the document * Redaction colors can be changed at any time, even after applying * [Overview](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#overview) * [Redaction Methods](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#redaction-methods) * [1\. Text Selection Redaction](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#1-text-selection-redaction) * [2\. Area Drawing Redaction](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#2-area-drawing-redaction) * [3\. Page Redaction](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#3-page-redaction) * [Customizing Redactions](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#customizing-redactions) * [Changing Colors](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#changing-colors) * [Removing Redactions](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#removing-redactions) * [Converting PDF to PDF-image (Used in removing text behind the box)](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#converting-pdf-to-pdf-image-used-in-removing-text-behind-the-box) * [Keyboard Shortcuts](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#keyboard-shortcuts) * [Tips](https://docs.stirlingpdf.com/Functionality/Page-Operations/redact/#tips) --- # Kubernetes Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#__docusaurus_skipToContent_fallback) On this page ### Run stirling-pdf helm chart[​](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#run-stirling-pdf-helm-chart "Direct link to Run stirling-pdf helm chart") helm repo add stirling-pdf https://stirling-tools.github.io/Stirling-PDF-charthelm repo updatehelm install stirling-pdf stirling-pdf/stirling-pdf-chart --namespace stirling-pdf --create-namespace ### Override stirling-pdf default values[​](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#override-stirling-pdf-default-values "Direct link to Override stirling-pdf default values") Create a `values.yaml` file with the values you want to override from the [documentation](https://github.com/Stirling-Tools/Stirling-PDF-chart/tree/main/charts/stirling-pdf) . (For examples, see the comments in the default [values.yml](https://github.com/Stirling-Tools/Stirling-PDF-chart/blob/main/charts/stirling-pdf/values.yaml) file.) Then, add `-f values.yaml` to the `helm install` command. ### Upgrade the helm chart[​](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#upgrade-the-helm-chart "Direct link to Upgrade the helm chart") helm repo updatehelm upgrade stirling-pdf stirling-pdf/stirling-pdf-chart --namespace stirling-pdf --reuse-values * [Run stirling-pdf helm chart](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#run-stirling-pdf-helm-chart) * [Override stirling-pdf default values](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#override-stirling-pdf-default-values) * [Upgrade the helm chart](https://docs.stirlingpdf.com/Installation/Kubernetes%20Install/#upgrade-the-helm-chart) --- # Pipeline Automation (Automate) | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Pipeline/#__docusaurus_skipToContent_fallback) On this page **Tool ID:** `automate` Create powerful automated workflows that combine multiple PDF operations into sequential processes. The Automate tool (formerly called "Pipeline") lets you build, save, and reuse complex PDF processing workflows. V2.0 Update - New "Automate" Feature In V2.0, the pipeline frontend interface has been redesigned as the **"Automate"** feature with an improved user experience for creating and managing automation workflows. The backend pipeline system (JSON configuration and folder scanning) continues to work the same way. **What changed:** * ✅ Backend pipeline processing - **No changes** * ✅ JSON pipeline configurations - **Still work exactly the same** * ✅ Folder scanning with pipelines - **Still works the same** * 🆕 Frontend interface - **Now called "Automate" with better UX** If you have existing pipeline JSON files, they continue to work in V2.0's Automate feature. * * * What is Pipeline Automation?[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#what-is-pipeline-automation "Direct link to What is Pipeline Automation?") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Pipeline automation allows you to: * **Chain operations** - Combine multiple PDF tools in sequence * **Save workflows** - Reuse common operation sequences * **Automate processing** - Process files automatically with folder scanning * **Standardize procedures** - Ensure consistent processing across teams * **Batch process** - Apply same workflow to multiple files Think of it as **"macros for PDFs"** - record your steps once, replay them unlimited times. * * * Why Use Pipelines?[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#why-use-pipelines "Direct link to Why Use Pipelines?") ---------------------------------------------------------------------------------------------------------------------------------- ### Without Pipelines:[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#without-pipelines "Direct link to Without Pipelines:") 1. Upload PDF to Split tool → Download split files 2. Upload each split file to Watermark tool → Download watermarked files 3. Upload each watermarked file to Compress tool → Download final files 4. Repeat for every batch of documents 😫 ### With Pipelines:[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#with-pipelines "Direct link to With Pipelines:") 1. Create "Split-Watermark-Compress" pipeline once 2. Upload PDFs → Automatic processing → Download results 3. Reuse same pipeline for all future batches 🎉 **Time saved:** Minutes per file, hours per day! * * * Key Concepts[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#key-concepts "Direct link to Key Concepts") ----------------------------------------------------------------------------------------------------------------- ### Operations[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#operations "Direct link to Operations") Individual PDF tools that perform specific tasks: * Split, Merge, Compress, Watermark, etc. * Each operation has configurable parameters * Operations execute in the order you define ### Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline "Direct link to Pipeline") A sequence of operations with saved configurations: * Named workflow (e.g., "Invoice Processing") * Ordered list of operations * Pre-configured settings for each operation * Reusable across multiple files ### Pipeline Configuration (JSON)[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-configuration-json "Direct link to Pipeline Configuration (JSON)") Text file that defines your pipeline: * Lists operations in order * Specifies parameters for each operation * Can be shared, versioned, and backed up * Human-readable and editable ### Folder Scanning[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning "Direct link to Folder Scanning") Automated processing mode: * Watch a folder for new files * Automatically apply pipeline to new files * Move processed files to output folder * Unattended batch processing * * * Getting Started with Automate[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#getting-started-with-automate "Direct link to Getting Started with Automate") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Accessing the Automate Tool[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#accessing-the-automate-tool "Direct link to Accessing the Automate Tool") 1. **From Home Page** * Click "Automate" in Advanced Tools section * Or search for "automate" or "pipeline" 2. **Open Configuration Builder** * Click "Configure Pipeline" button * Pipeline builder interface opens * * * Building Your First Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#building-your-first-pipeline "Direct link to Building Your First Pipeline") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Steps to Configure and Use Your Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#steps-to-configure-and-use-your-pipeline "Direct link to Steps to Configure and Use Your Pipeline") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. **Access Configuration** * Upon entering the screen, click on the **Configure** button. 2. **Enter Pipeline Name** * Provide a name for your pipeline in the designated field. 3. **Select Operations** * Choose the operations for your pipeline (e.g., **Split Pages**), then click **Add Operation**. 4. **Configure Operation Settings** * Input the necessary settings for each added operation. Settings are highlighted in yellow if customization is needed. 5. **Add More Operations** * You can add and adjust the order of multiple operations. Ensure each operation's settings are customized. 6. **Save Settings** * Click **Save Operation Settings** after customizing settings for each operation. 7. **Validate Pipeline** * Use the **Validation** button to check your pipeline. A green indicator signifies correct setup; a pop-out error indicates issues. 8. **Download Pipeline Configuration** * To use the configuration for [folder scanning](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) (or save it for future use and re-upload it), download a JSON file in this menu. You can also pre-load it for future use by placing it in `/pipeline/defaultWebUIConfigs/`. It will then appear in the dropdown menu for all users to use. 9. **Submit Files for Processing** * If your pipeline is correctly set up, close the configure menu, input the files, and hit **Submit**. 10. **Note on Web UI Limitations** * The current web UI version does not support operations that require multiple different types of inputs, such as adding a separate image to a PDF. ### Current Limitations[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#current-limitations "Direct link to Current Limitations") * Cannot have more than one of the same operation. * Cannot input additional files via UI. * All files and operations run in serial mode. * * * Example Pipelines[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-pipelines "Direct link to Example Pipelines") -------------------------------------------------------------------------------------------------------------------------------- ### Example 1: Invoice Processing[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-1-invoice-processing "Direct link to Example 1: Invoice Processing") **Goal:** Process scanned invoices for archival **Pipeline Steps:** 1. **OCR** - Make invoices searchable * Language: English * Preserve formatting: Yes 2. **Crop** - Remove scanner edges * Margins: 0.5 inches all sides 3. **Add Watermark** - Mark as processed * Text: "PROCESSED \[DATE\]" * Position: Bottom right * Opacity: 50% 4. **Compress** - Reduce file size * Level: Medium 5. **Add Password** - Secure documents * Password: \[configured per run\] **Use Case:** Accounting department processing hundreds of invoices monthly * * * ### Example 2: Report Distribution[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-2-report-distribution "Direct link to Example 2: Report Distribution") **Goal:** Prepare reports for external sharing **Pipeline Steps:** 1. **Remove Pages** - Remove internal pages * Pages: 2,3 (remove cover sheets) 2. **Add Page Numbers** - Number all pages * Position: Bottom center * Format: "Page X of Y" 3. **Add Stamp** - Add "CONFIDENTIAL" stamp * Position: Top right * Color: Red 4. **Change Permissions** - Restrict editing * Allow printing: Yes * Allow editing: No 5. **Compress** - Optimize for email * Level: High **Use Case:** Monthly reports sent to clients * * * ### Example 3: Document Standardization[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-3-document-standardization "Direct link to Example 3: Document Standardization") **Goal:** Standardize format of received documents **Pipeline Steps:** 1. **Rotate** - Fix orientation * Mode: Auto-detect 2. **Scale Pages** - Standardize to Letter size * Target: 8.5 x 11 inches 3. **Add Metadata** - Tag documents * Title: \[Auto-extracted\] * Author: "Company Name" * Keywords: "Standardized, Processed" 4. **Remove Annotations** - Clean markup 5. **Flatten** - Remove form fields **Use Case:** HR department standardizing employee submissions * * * ### Example 4: Batch Conversion[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-4-batch-conversion "Direct link to Example 4: Batch Conversion") **Goal:** Convert and optimize image scans **Pipeline Steps:** 1. **Convert** - Images to PDF * Source: JPG, PNG 2. **OCR** - Add text layer * Language: Multiple 3. **Remove Blanks** - Delete empty pages * Threshold: 95% 4. **Compress** - Optimize size * Level: Medium 5. **PDF/A** - Convert for archival * Version: PDF/A-2b **Use Case:** Digitization project for paper archives * * * Common Pipeline Patterns[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#common-pipeline-patterns "Direct link to Common Pipeline Patterns") ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Quality Enhancement Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#quality-enhancement-pipeline "Direct link to Quality Enhancement Pipeline") **Pattern:** Improve scanned document quality OCR → Remove Blanks → Adjust Contrast → Compress → Add Metadata ### Security Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#security-pipeline "Direct link to Security Pipeline") **Pattern:** Secure documents for distribution Remove Metadata → Add Watermark → Add Password → Change Permissions ### Compression Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#compression-pipeline "Direct link to Compression Pipeline") **Pattern:** Reduce file sizes for storage/email Remove Annotations → Remove Images (optional) → Compress → Validate ### Branding Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#branding-pipeline "Direct link to Branding Pipeline") **Pattern:** Add company branding to documents Add Watermark → Add Stamp → Add Page Numbers → Add Metadata ### Preparation Pipeline[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#preparation-pipeline "Direct link to Preparation Pipeline") **Pattern:** Prepare documents for printing Rotate → Scale Pages → Booklet Imposition → Remove Annotations * * * Configuration[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#configuration "Direct link to Configuration") -------------------------------------------------------------------------------------------------------------------- ### JSON Pipeline Format[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#json-pipeline-format "Direct link to JSON Pipeline Format") Basic structure of a pipeline configuration: { "name": "My Pipeline", "pipeline": [ { "operation": "split-pages", "parameters": { "splitType": "EVERY_N_PAGES", "numberOfPagesPerSplit": 2 } }, { "operation": "compress-pdf", "parameters": { "compressionLevel": "MEDIUM" } } ]} ### Operation Names[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#operation-names "Direct link to Operation Names") Use these exact operation names in JSON: * `split-pages`, `merge-pdfs`, `rotate-pdf` * `compress-pdf`, `add-watermark`, `add-stamp` * `ocr-pdf`, `add-password`, `remove-password` * `crop`, `scale-pages`, `add-page-numbers` * See [Endpoint Customisation](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation) for complete list ### Parameter Configuration[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#parameter-configuration "Direct link to Parameter Configuration") Each operation has specific parameters: **Split Pages:** { "splitType": "EVERY_N_PAGES", // or "SPLIT_BY_SIZE", "BY_SECTIONS" "numberOfPagesPerSplit": 5} **Add Watermark:** { "watermarkText": "CONFIDENTIAL", "fontSize": 36, "opacity": 0.5, "rotation": 45, "position": "CENTER"} **Compress:** { "compressionLevel": "MEDIUM", // "LOW", "MEDIUM", "HIGH" "optimizeImages": true} * * * Folder Scanning Setup[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-setup "Direct link to Folder Scanning Setup") -------------------------------------------------------------------------------------------------------------------------------------------- Automate processing of files placed in watched folders. ### How Folder Scanning Works[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#how-folder-scanning-works "Direct link to How Folder Scanning Works") 1. **Watch Input Folder** - Monitor for new files 2. **Detect New Files** - Identify PDFs added to folder 3. **Apply Pipeline** - Process with configured pipeline 4. **Output Results** - Save to output folder 5. **Archive Originals** - Move processed files (optional) ### Directory Structure[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#directory-structure "Direct link to Directory Structure") /pipeline/ ├── watchedFolders/ │ ├── invoice-processing/ │ │ ├── input/ # Drop files here │ │ ├── output/ # Results appear here │ │ └── config.json # Pipeline configuration │ └── report-prep/ │ ├── input/ │ ├── output/ │ └── config.json └── defaultWebUIConfigs/ # Pre-loaded pipelines for UI ├── invoice.json └── reports.json ### Configuration File[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#configuration-file "Direct link to Configuration File") Create `config.json` in each watched folder: { "name": "Invoice Processing", "pipeline": [...], // Your pipeline operations "watchSchedule": "*/5 * * * *", // Every 5 minutes (cron format) "deleteOriginal": false, // Keep original files "archiveFolder": "./processed/" // Move originals here} ### Cron Schedule Format[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#cron-schedule-format "Direct link to Cron Schedule Format") * * * * *│ │ │ │ ││ │ │ │ └─ Day of week (0-7, 0 and 7 = Sunday)│ │ │ └─── Month (1-12)│ │ └───── Day of month (1-31)│ └─────── Hour (0-23)└───────── Minute (0-59) **Examples:** * `*/5 * * * *` - Every 5 minutes * `0 * * * *` - Every hour * `0 9 * * *` - Daily at 9 AM * `0 9 * * 1` - Every Monday at 9 AM **Learn more:** [Folder Scanning Guide](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) * * * Best Practices[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#best-practices "Direct link to Best Practices") ----------------------------------------------------------------------------------------------------------------------- ### Pipeline Design[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-design "Direct link to Pipeline Design") 1. **Test Incrementally** * Build pipeline one operation at a time * Test each step before adding the next * Verify output at each stage 2. **Order Operations Logically** * Do OCR before text-based operations * Remove pages before processing remaining pages * Compress last to optimize final output 3. **Use Descriptive Names** * Name pipelines clearly: "Invoice-OCR-Watermark-Archive" * Add descriptions in comments * Version your pipeline files 4. **Handle Errors Gracefully** * Test with various file types * Consider edge cases (empty PDFs, locked files) * Monitor logs for errors ### Performance Optimization[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#performance-optimization "Direct link to Performance Optimization") 1. **Minimize Operations** * Combine similar operations when possible * Remove unnecessary steps * Don't duplicate efforts 2. **Optimize Compression** * Compress once at the end, not multiple times * Choose appropriate compression level * Balance quality vs. file size 3. **Batch Intelligently** * Group similar files together * Process during off-peak hours * Monitor system resources ### Maintenance[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#maintenance "Direct link to Maintenance") 1. **Version Control** * Keep pipeline JSONs in git repository * Track changes over time * Document modifications 2. **Regular Review** * Audit pipelines quarterly * Remove unused pipelines * Update for new requirements 3. **Monitor Performance** * Check processing times * Review error logs * Optimize slow operations * * * Troubleshooting[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#troubleshooting "Direct link to Troubleshooting") -------------------------------------------------------------------------------------------------------------------------- ### Pipeline Fails to Execute[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-fails-to-execute "Direct link to Pipeline Fails to Execute") **Symptoms:** Pipeline starts but doesn't complete **Common Causes:** * Invalid parameter values * Unsupported file format * Missing dependencies (OCR languages, fonts) * File permissions issues **Solutions:** 1. Validate JSON configuration 2. Test each operation individually 3. Check server logs for errors 4. Verify required dependencies installed * * * ### Folder Scanning Not Working[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-not-working "Direct link to Folder Scanning Not Working") **Symptoms:** Files not processed automatically **Possible Issues:** * Folder permissions incorrect * Cron schedule not configured * Pipeline configuration invalid * Folder scanning not enabled **Solutions:** 1. Check folder permissions (read/write access) 2. Verify cron schedule format 3. Test pipeline manually first 4. Check `docker logs` for errors 5. Ensure folder scanning feature enabled * * * ### Operation Parameters Not Applying[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#operation-parameters-not-applying "Direct link to Operation Parameters Not Applying") **Symptoms:** Pipeline runs but doesn't use specified settings **Causes:** * Incorrect parameter names * Wrong parameter data types * Parameters not supported in operation **Solutions:** 1. Check parameter names match documentation 2. Verify parameter value types (string, number, boolean) 3. Review operation's available parameters 4. Test parameters manually first * * * ### Results Not as Expected[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#results-not-as-expected "Direct link to Results Not as Expected") **Symptoms:** Pipeline completes but output incorrect **Debugging Steps:** 1. Test each operation individually 2. Check intermediate outputs 3. Verify operation order makes sense 4. Review parameter values 5. Test with simpler input files * * * Pipeline vs. Multi-Tool vs. Manual[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-vs-multi-tool-vs-manual "Direct link to Pipeline vs. Multi-Tool vs. Manual") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Use Pipeline/Automate When:[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-pipelineautomate-when "Direct link to Use Pipeline/Automate When:") ✅ Same workflow repeated frequently ✅ Predictable, consistent operations ✅ Automated folder processing needed ✅ No manual intervention required ✅ Standardizing team processes ✅ Large batch processing ✅ Scheduled/unattended processing ### Use Multi-Tool When:[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-multi-tool-when "Direct link to Use Multi-Tool When:") ✅ Workflow varies per file ✅ Need visual feedback at each step ✅ Experimenting with different settings ✅ Manual decision points in workflow ✅ One-time complex tasks ### Use Individual Tools When:[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-individual-tools-when "Direct link to Use Individual Tools When:") ✅ Single, simple operation ✅ Quick one-off task ✅ Learning how operations work ✅ No need for automation * * * Security Considerations[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#security-considerations "Direct link to Security Considerations") -------------------------------------------------------------------------------------------------------------------------------------------------- ### Pipeline Files[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-files "Direct link to Pipeline Files") * **Protect JSON configs** - May contain passwords or sensitive settings * **Restrict folder access** - Limit who can create/modify pipelines * **Review before deploying** - Audit pipelines for security issues ### Folder Scanning[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-1 "Direct link to Folder Scanning") * **Isolate watched folders** - Don't expose to untrusted users * **Monitor activity** - Log all processing for audit trail * **Secure output folders** - Protect processed documents appropriately ### Automated Processing[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#automated-processing "Direct link to Automated Processing") * **Validate inputs** - Ensure only expected files processed * **Error handling** - Don't expose sensitive error messages * **Resource limits** - Prevent resource exhaustion attacks * * * Related Documentation[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#related-documentation "Direct link to Related Documentation") -------------------------------------------------------------------------------------------------------------------------------------------- * **[Folder Scanning Setup](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning) ** - Detailed folder scanning guide * **[Multi-Tool](https://docs.stirlingpdf.com/Functionality/Multi-Tool) ** - Interactive multi-operation tool * **[Endpoint Customisation](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation) ** - Operation names and IDs * **[API Documentation](https://docs.stirlingpdf.com/API) ** - Programmatic pipeline execution * **[Advanced Tools](https://docs.stirlingpdf.com/Functionality/Advanced-Tools) ** - Other automation features * * * Summary[​](https://docs.stirlingpdf.com/Configuration/Pipeline/#summary "Direct link to Summary") -------------------------------------------------------------------------------------------------- Pipeline automation (Automate tool) transforms Stirling PDF into a workflow engine: * 🔗 **Chain operations** - Combine multiple PDF tools sequentially * 💾 **Save workflows** - Reusable pipeline configurations * 📁 **Folder scanning** - Automated unattended processing * 🎯 **Standardization** - Consistent processing across teams * ⚡ **Efficiency** - Minutes saved per file, hours per day **Perfect for:** Repetitive workflows, batch processing, automated document preparation, and standardized procedures. Ready to automate? Create your first pipeline and transform how you process PDFs! * [What is Pipeline Automation?](https://docs.stirlingpdf.com/Configuration/Pipeline/#what-is-pipeline-automation) * [Why Use Pipelines?](https://docs.stirlingpdf.com/Configuration/Pipeline/#why-use-pipelines) * [Without Pipelines:](https://docs.stirlingpdf.com/Configuration/Pipeline/#without-pipelines) * [With Pipelines:](https://docs.stirlingpdf.com/Configuration/Pipeline/#with-pipelines) * [Key Concepts](https://docs.stirlingpdf.com/Configuration/Pipeline/#key-concepts) * [Operations](https://docs.stirlingpdf.com/Configuration/Pipeline/#operations) * [Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline) * [Pipeline Configuration (JSON)](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-configuration-json) * [Folder Scanning](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning) * [Getting Started with Automate](https://docs.stirlingpdf.com/Configuration/Pipeline/#getting-started-with-automate) * [Accessing the Automate Tool](https://docs.stirlingpdf.com/Configuration/Pipeline/#accessing-the-automate-tool) * [Building Your First Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#building-your-first-pipeline) * [Steps to Configure and Use Your Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#steps-to-configure-and-use-your-pipeline) * [Current Limitations](https://docs.stirlingpdf.com/Configuration/Pipeline/#current-limitations) * [Example Pipelines](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-pipelines) * [Example 1: Invoice Processing](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-1-invoice-processing) * [Example 2: Report Distribution](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-2-report-distribution) * [Example 3: Document Standardization](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-3-document-standardization) * [Example 4: Batch Conversion](https://docs.stirlingpdf.com/Configuration/Pipeline/#example-4-batch-conversion) * [Common Pipeline Patterns](https://docs.stirlingpdf.com/Configuration/Pipeline/#common-pipeline-patterns) * [Quality Enhancement Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#quality-enhancement-pipeline) * [Security Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#security-pipeline) * [Compression Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#compression-pipeline) * [Branding Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#branding-pipeline) * [Preparation Pipeline](https://docs.stirlingpdf.com/Configuration/Pipeline/#preparation-pipeline) * [Configuration](https://docs.stirlingpdf.com/Configuration/Pipeline/#configuration) * [JSON Pipeline Format](https://docs.stirlingpdf.com/Configuration/Pipeline/#json-pipeline-format) * [Operation Names](https://docs.stirlingpdf.com/Configuration/Pipeline/#operation-names) * [Parameter Configuration](https://docs.stirlingpdf.com/Configuration/Pipeline/#parameter-configuration) * [Folder Scanning Setup](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-setup) * [How Folder Scanning Works](https://docs.stirlingpdf.com/Configuration/Pipeline/#how-folder-scanning-works) * [Directory Structure](https://docs.stirlingpdf.com/Configuration/Pipeline/#directory-structure) * [Configuration File](https://docs.stirlingpdf.com/Configuration/Pipeline/#configuration-file) * [Cron Schedule Format](https://docs.stirlingpdf.com/Configuration/Pipeline/#cron-schedule-format) * [Best Practices](https://docs.stirlingpdf.com/Configuration/Pipeline/#best-practices) * [Pipeline Design](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-design) * [Performance Optimization](https://docs.stirlingpdf.com/Configuration/Pipeline/#performance-optimization) * [Maintenance](https://docs.stirlingpdf.com/Configuration/Pipeline/#maintenance) * [Troubleshooting](https://docs.stirlingpdf.com/Configuration/Pipeline/#troubleshooting) * [Pipeline Fails to Execute](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-fails-to-execute) * [Folder Scanning Not Working](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-not-working) * [Operation Parameters Not Applying](https://docs.stirlingpdf.com/Configuration/Pipeline/#operation-parameters-not-applying) * [Results Not as Expected](https://docs.stirlingpdf.com/Configuration/Pipeline/#results-not-as-expected) * [Pipeline vs. Multi-Tool vs. Manual](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-vs-multi-tool-vs-manual) * [Use Pipeline/Automate When:](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-pipelineautomate-when) * [Use Multi-Tool When:](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-multi-tool-when) * [Use Individual Tools When:](https://docs.stirlingpdf.com/Configuration/Pipeline/#use-individual-tools-when) * [Security Considerations](https://docs.stirlingpdf.com/Configuration/Pipeline/#security-considerations) * [Pipeline Files](https://docs.stirlingpdf.com/Configuration/Pipeline/#pipeline-files) * [Folder Scanning](https://docs.stirlingpdf.com/Configuration/Pipeline/#folder-scanning-1) * [Automated Processing](https://docs.stirlingpdf.com/Configuration/Pipeline/#automated-processing) * [Related Documentation](https://docs.stirlingpdf.com/Configuration/Pipeline/#related-documentation) * [Summary](https://docs.stirlingpdf.com/Configuration/Pipeline/#summary) --- # Mobile Scanner Configuration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner/#__docusaurus_skipToContent_fallback) On this page Enable and configure the Mobile Scanner feature, which lets users scan documents with their phone camera and upload them directly to Stirling PDF via QR code. Settings[​](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner/#settings "Direct link to Settings") ----------------------------------------------------------------------------------------------------------- * Settings File * Environment Variables * Docker Run * Docker Compose system: enableMobileScanner: true mobileScannerSettings: convertToPdf: true # Convert images to PDF (true/false) imageResolution: full # 'full' (original size) or 'reduced' (max 1200px) pageFormat: A4 # 'keep' (original dimensions), 'A4', or 'letter' stretchToFit: false # Stretch images to fill page (may distort) SYSTEM_ENABLEMOBILESCANNER=trueSYSTEM_MOBILESCANNERSETTINGS_CONVERTTOPDF=trueSYSTEM_MOBILESCANNERSETTINGS_IMAGERESOLUTION=fullSYSTEM_MOBILESCANNERSETTINGS_PAGEFORMAT=A4SYSTEM_MOBILESCANNERSETTINGS_STRETCHTOFIT=false docker run -d \ -p 8080:8080 \ -e SYSTEM_ENABLEMOBILESCANNER=true \ -e SYSTEM_MOBILESCANNERSETTINGS_CONVERTTOPDF=true \ -e SYSTEM_MOBILESCANNERSETTINGS_IMAGERESOLUTION=full \ -e SYSTEM_MOBILESCANNERSETTINGS_PAGEFORMAT=A4 \ -e SYSTEM_MOBILESCANNERSETTINGS_STRETCHTOFIT=false \ stirlingtools/stirling-pdf:latest environment: SYSTEM_ENABLEMOBILESCANNER: true SYSTEM_MOBILESCANNERSETTINGS_CONVERTTOPDF: true SYSTEM_MOBILESCANNERSETTINGS_IMAGERESOLUTION: full SYSTEM_MOBILESCANNERSETTINGS_PAGEFORMAT: A4 SYSTEM_MOBILESCANNERSETTINGS_STRETCHTOFIT: false Configuration Options[​](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner/#configuration-options "Direct link to Configuration Options") -------------------------------------------------------------------------------------------------------------------------------------------------- | Setting | Values | Description | | --- | --- | --- | | `enableMobileScanner` | `true` / `false` | Enable/disable Mobile Scanner feature | | `convertToPdf` | `true` / `false` | Automatically convert uploaded images to PDF. If false, images are kept as-is. | | `imageResolution` | `full` / `reduced` | Image resolution for PDF conversion: `full` = original size, `reduced` = max 1200px on longest side. Only applies when `convertToPdf` is true. | | `pageFormat` | `keep` / `A4` / `letter` | Page format for converted PDFs: `keep` = original image dimensions, `A4` = A4 page size, `letter` = US Letter page size. Only applies when `convertToPdf` is true. | | `stretchToFit` | `true` / `false` | Stretch images to fill entire page (may distort aspect ratio). If false, images are centered with preserved aspect ratio. Only applies when `convertToPdf` is true. | * [Settings](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner/#settings) * [Configuration Options](https://docs.stirlingpdf.com/Configuration/Mobile-Scanner/#configuration-options) --- # External Database | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/External%20Database/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Server It is possible to use your own external database with Stirling PDF rather than the default H2 database if you wish. PostgreSQL is currently the only supported variant, others will be added on request. ### Setting Up External Database Configuration[​](https://docs.stirlingpdf.com/Configuration/External%20Database/#setting-up-external-database-configuration "Direct link to Setting Up External Database Configuration") You can configure the new `Datasource` property in your `settings.yml` to connect to your external database: > #### ⚠️ Note[​](https://docs.stirlingpdf.com/Configuration/External%20Database/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _To use the external database feature, you will need to have a valid enterprise license and set the environment variable `DISABLE_ADDITIONAL_FEATURES` to `false`._ * Settings File * Docker Compose datasource: enableCustomDatabase: false customDatabackendUrl: jdbc:postgresql://localhost:5432/postgres username: postgres password: postgres type: postgresql hostName: localhost port: 5432 name: postgres * `enableCustomDatabase`: Set this property to `true` to enable use of the custom database **Note: An enterprise license to use this feature** * `customDatabackendUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabackendUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** * `username`: The username for the database * `password`: The password for the database If you would like more fine-grained control of the database connection, you can also use the following properties: #### Fine-grained Database Configuration[​](https://docs.stirlingpdf.com/Configuration/External%20Database/#fine-grained-database-configuration "Direct link to Fine-grained Database Configuration") * `type`: The database type. Available options are `h2` and `postgresql` * `hostName`: The host name of the database connection url (e.g. 'localhost') * `port`: The port number of the database connection url (e.g. 8080) * `name`: The name of the custom database. This should match the name you have set for your database services: db: image: 'postgres:17.2-alpine' container_name: db ports: - "5432:5432" environment: POSTGRES_DB: "stirling_pdf" POSTGRES_USER: "admin" POSTGRES_PASSWORD: "stirling" * `container_name`: This is the name of your database container. This should match the name of the container under `services` as this is what Docker will use to refer to your database * `ports`: Specify the port number for your database. The number on the left is the port number the container will access the database internally. The number on the right is the port number the Stirling PDF app will use to connect to the database externally. Ensure this matches the port number in the connection url for your database otherwise the app will not be able to access it. * `POSTGRES_DB`: An environment variable for the database container. Specify the name of the custom database here * `POSTGRES_USER`: An environment variable for the database container. Specify the username for the database * `POSTGRES_PASSWORD`: An environment variable for the database container. Specify the password for the database You will also need to update the Docker configuration in your app in order to connect to the database: services: stirling-pdf: depends_on: - db environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration * `depends_on`: This specifies any services that your app will need in order to run. Ensure the name matches the container name for your database * `DISABLE_ADDITIONAL_FEATURES`: Set this to `false` to enable security features * `SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE`: An environment variable to connect to the database container. Set this to `true` to enable use of the external database * `SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** * `SYSTEM_DATASOURCE_USERNAME`: An environment variable to connect to the database container. Set the username for the database. Ensure this matches the corresponding property in your database container * `SYSTEM_DATASOURCE_PASSWORD`: An environment variable to connect to the database container. Set the password for the database. Ensure this matches the corresponding property in your database container Below is an example of what your configuration should look like after configuring the custom database: services: stirling-pdf: depends_on: - db environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration db: image: 'postgres:17.2-alpine' container_name: db ports: - "5432:5432" environment: POSTGRES_DB: "stirling_pdf" POSTGRES_USER: "admin" POSTGRES_PASSWORD: "stirling" _Example configuration can be found in [exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml](https://github.com/Stirling-Tools/Stirling-PDF/blob/428b4238e3a7280d71697d994a66174a250387a7/exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml) _ * [Setting Up External Database Configuration](https://docs.stirlingpdf.com/Configuration/External%20Database/#setting-up-external-database-configuration) --- # OCR (Optical Character Recognition) | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/OCR/#__docusaurus_skipToContent_fallback) On this page This document provides instructions on how to add additional language packs for the OCR tab in Stirling PDF, both inside and outside of Docker. How does the OCR Work[​](https://docs.stirlingpdf.com/Configuration/OCR/#how-does-the-ocr-work "Direct link to How does the OCR Work") --------------------------------------------------------------------------------------------------------------------------------------- Stirling PDF uses Tesseract for its text recognition. All credit goes to them for this awesome work! Language Packs[​](https://docs.stirlingpdf.com/Configuration/OCR/#language-packs "Direct link to Language Packs") ------------------------------------------------------------------------------------------------------------------ Tesseract OCR supports a variety of languages. You can find additional language packs in the Tesseract GitHub repositories: * [tessdata\_fast](https://github.com/tesseract-ocr/tessdata_fast) : These language packs are smaller and faster to load but may provide lower recognition accuracy. * [tessdata](https://github.com/tesseract-ocr/tessdata) : These language packs are larger and provide better recognition accuracy, but may take longer to load. Depending on your requirements, you can choose the appropriate language pack for your use case. By default, Stirling PDF uses `tessdata_fast` for English, but this can be replaced. ### Installing Language Packs manually[​](https://docs.stirlingpdf.com/Configuration/OCR/#installing-language-packs-manually "Direct link to Installing Language Packs manually") 1. Download the desired language pack(s) by selecting the `.traineddata` file(s) for the language(s) you need. 2. Place the `.traineddata` files in the Tesseract tessdata directory: `/usr/share/tessdata` (or equivalent) **DO NOT REMOVE EXISTING `eng.traineddata`, IT'S REQUIRED.** ### Docker Setup[​](https://docs.stirlingpdf.com/Configuration/OCR/#docker-setup "Direct link to Docker Setup") If you are using Docker, you need to expose the Tesseract tessdata directory as a volume in order to use the additional language packs. * Docker Compose * Docker Run Modify your `docker-compose.yml` file to include the following volume configuration: services: your_service_name: image: your_docker_image_name volumes: - /location/of/trainingData:/usr/share/tessdata Add the following to your existing Docker run command: -v /location/of/trainingData:/usr/share/tessdata ### Non-Docker Setup[​](https://docs.stirlingpdf.com/Configuration/OCR/#non-docker-setup "Direct link to Non-Docker Setup") * Debian-based Systems * Fedora * Windows For Debian-based systems, use the following commands to manage Tesseract languages: sudo apt update &&\# All languages# sudo apt install -y 'tesseract-ocr-*'# Find available languages:apt search tesseract-ocr-# View installed languages:dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g' For Fedora systems, use the following commands: # All languages# sudo dnf install -y tesseract-langpack-*# Find available languages:dnf search -C tesseract-langpack-# View installed languages:rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g' Follow these steps to set up Tesseract languages on Windows: 1. Download desired `.traineddata` files from [tessdata](https://github.com/tesseract-ocr/tessdata) or [tessdata\_fast](https://github.com/tesseract-ocr/tessdata_fast) 2. Place them in the tessdata folder within your Tesseract installation directory: C:\Program Files\Tesseract-OCR\tessdata 3. Verify the installation by running: tesseract --list-langs 4. Edit your `/configs/settings.yml` and update the `system.tessdataDir`: system: tessdataDir: C:/Program Files/Tesseract-OCR/tessdata # path to Tessdata files * [How does the OCR Work](https://docs.stirlingpdf.com/Configuration/OCR/#how-does-the-ocr-work) * [Language Packs](https://docs.stirlingpdf.com/Configuration/OCR/#language-packs) * [Installing Language Packs manually](https://docs.stirlingpdf.com/Configuration/OCR/#installing-language-packs-manually) * [Docker Setup](https://docs.stirlingpdf.com/Configuration/OCR/#docker-setup) * [Non-Docker Setup](https://docs.stirlingpdf.com/Configuration/OCR/#non-docker-setup) --- # Endpoints Customisation | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#__docusaurus_skipToContent_fallback) On this page You can selectively disable and remove endpoints and functionalities from Stirling PDF as per your requirements. There are many use-cases for this such as * Avoid confusion for users for functionality you/your business don't use. * Running a reduced version of Stirling PDF that doesn't have the necessary server power to support the more advanced features. * Cleanup interface for features you don't use You have two ways to disable endpoints: 1. **Environment Variables** (`ENDPOINTS_TOREMOVE` and `ENDPOINTS_GROUPSTOREMOVE`): * Example: `ENDPOINTS_TOREMOVE=merge-pdfs,remove-pages` disables merge and remove page tools * Example: `ENDPOINTS_GROUPSTOREMOVE=LibreOffice` disables all LibreOffice-dependent tools 2. **Settings File** (`settings.yml` under `endpoints.toRemove` and `endpoints.groupsToRemove`): * Example: `toRemove: [merge-pdfs, remove-pages]` * Example: `groupsToRemove: [LibreOffice]` Available Endpoint Groups[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#available-endpoint-groups "Direct link to Available Endpoint Groups") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can disable entire groups of related endpoints using `ENDPOINTS_GROUPSTOREMOVE`: | Group Name | What It Disables | Example | | --- | --- | --- | | `LibreOffice` | All office document conversions (DOCX, XLSX, PPTX to/from PDF) | `ENDPOINTS_GROUPSTOREMOVE=LibreOffice` | | `Python` | Python-based image processing features | `ENDPOINTS_GROUPSTOREMOVE=Python` | | `OpenCV` | Advanced image processing operations | `ENDPOINTS_GROUPSTOREMOVE=OpenCV` | | `OCRmyPDF` | OCR (Optical Character Recognition) features | `ENDPOINTS_GROUPSTOREMOVE=OCRmyPDF` | | `Weasyprint` | HTML to PDF conversion | `ENDPOINTS_GROUPSTOREMOVE=Weasyprint` | | `Calibre` | E-book format conversions | `ENDPOINTS_GROUPSTOREMOVE=Calibre` | | `QPDF` | Various PDF operations powered by QPDF | `ENDPOINTS_GROUPSTOREMOVE=QPDF` | | `Ghostscript` | PDF/A conversion and compression operations | `ENDPOINTS_GROUPSTOREMOVE=Ghostscript` | **Example - Disable multiple groups:** ENDPOINTS_GROUPSTOREMOVE=LibreOffice,Calibre,Weasyprint Usage Examples[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#usage-examples "Direct link to Usage Examples") ------------------------------------------------------------------------------------------------------------------------------------------------------ ### Environment Variables[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#environment-variables "Direct link to Environment Variables") **Disable specific tools:** # Docker Rundocker run -e ENDPOINTS_TOREMOVE=sign,add-watermark,add-stamp stirlingtools/stirling-pdf:latest# Docker Composeenvironment: - ENDPOINTS_TOREMOVE=sign,add-watermark,add-stamp **Disable entire groups:** # Disable all office conversions and OCRENDPOINTS_GROUPSTOREMOVE=LibreOffice,OCRmyPDF **Combine both methods:** # Disable groups AND specific toolsENDPOINTS_GROUPSTOREMOVE=LibreOffice,CalibreENDPOINTS_TOREMOVE=sign,compare,multi-tool ### Settings File (settings.yml)[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#settings-file-settingsyml "Direct link to Settings File (settings.yml)") If you're editing `settings.yml` directly, use the kebab-case endpoint IDs: **Disable specific tools:** endpoints: toRemove: - sign - add-watermark - add-stamp - compare - merge-pdfs **Disable entire groups:** endpoints: groupsToRemove: - LibreOffice - OCRmyPDF **Combine both methods:** endpoints: toRemove: - sign - compare - multi-tool - merge-pdfs groupsToRemove: - LibreOffice - Calibre Complete Endpoint Reference for settings.yml[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#complete-endpoint-reference-for-settingsyml "Direct link to Complete Endpoint Reference for settings.yml") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use these exact kebab-case IDs with `endpoints.toRemove` in settings.yml. ### Page Operations[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#page-operations "Direct link to Page Operations") * `merge-pdfs` - Merge PDFs * `split-pages` - Split PDFs * `extract-pages` - Extract Pages * `remove-pages` - Remove Pages * `rearrange-pages` - Rearrange Pages * `rotate-pdf` - Rotate PDFs * `crop` - Crop Pages * `scale-pages` - Scale Pages * `add-page-numbers` - Add Page Numbers * `pdf-to-single-page` - PDF to Single Page * `multi-page-layout` - Multi-Page Layout * `booklet-imposition` - Booklet Imposition * `overlay-pdf` - Overlay PDFs * `split-pdf-by-sections` - Split by Sections * `split-pdf-by-chapters` - Split by Chapters * `auto-split-pdf` - Auto Split PDF * `split-by-size-or-count` - Split by Size/Count * `add-attachments` - Add Attachments ### Conversion[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#conversion "Direct link to Conversion") * `pdf-to-img` - PDF to Image * `img-to-pdf` - Image to PDF * `file-to-pdf` - File to PDF * `pdf-to-word` - PDF to Word * `pdf-to-presentation` - PDF to Presentation * `pdf-to-text` - PDF to Text * `pdf-to-html` - PDF to HTML * `pdf-to-xml` - PDF to XML * `pdf-to-markdown` - PDF to Markdown * `pdf-to-csv` - PDF to CSV * `pdf-to-epub` - PDF to EPUB * `pdf-to-vector` - PDF to Vector * `pdf-to-video` - PDF to Video * `pdf-to-json` - PDF to JSON * `pdf-to-rtf` - PDF to RTF * `pdf-to-cbz` - PDF to CBZ * `pdf-to-cbr` - PDF to CBR * `pdf-to-pdfa` - PDF to PDF/A * `html-to-pdf` - HTML to PDF * `url-to-pdf` - URL to PDF * `markdown-to-pdf` - Markdown to PDF * `eml-to-pdf` - Email to PDF * `cbz-to-pdf` - CBZ to PDF * `json-to-pdf` - JSON to PDF * `vector-to-pdf` - Vector to PDF ### Security & Signing[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#security--signing "Direct link to Security & Signing") * `add-password` - Add Password Protection * `remove-password` - Remove Password * `change-permissions` - Change Permissions * `add-watermark` - Add Watermark * `add-stamp` - Add Stamp * `sanitize-pdf` - Sanitize PDF * `flatten` - Flatten Form Fields * `unlock-pdf-forms` - Unlock PDF Forms * `cert-sign` - Certificate Sign * `sign` - Draw/Text/Image Signature * `remove-cert-sign` - Remove Certificate Signature * `validate-signature` - Validate Signature * `verify-pdf` - Verify PDF * `redact` - Redact Information * `auto-redact` - Auto Redact ### Content Extraction & Removal[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#content-extraction--removal "Direct link to Content Extraction & Removal") * `extract-images` - Extract Images * `extract-image-scans` - Extract Image Scans * `remove-image-pdf` - Remove Images * `remove-annotations` - Remove Annotations * `remove-blanks` - Remove Blank Pages * `ocr-pdf` - OCR ### Document Editing & Analysis[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#document-editing--analysis "Direct link to Document Editing & Analysis") * `text-editor-pdf` - Text Editor * `edit-table-of-contents` - Edit Table of Contents * `update-metadata` - Change Metadata * `get-info-on-pdf` - Get PDF Info * `compare` - Compare PDFs * `adjust-contrast` - Adjust Contrast * `replace-invert-pdf` - Replace/Invert Colors * `scanner-effect` - Scanner Effect * `repair` - Repair PDF * `add-image` - Add Image to PDF ### Form Fields[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#form-fields "Direct link to Form Fields") * `fields` - Form Fields * `fill` - Fill Form Fields * `modify-fields` - Modify Form Fields * `delete-fields` - Delete Form Fields ### Multi-Tool & Automation[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#multi-tool--automation "Direct link to Multi-Tool & Automation") * `multi-tool` - Multi-Tool Workbench * `compare` - Compare PDFs * `compress-pdf` - Compress PDFs * `automate` - Automation/Pipeline * `pipeline` - Pipeline * `auto-rename` - Auto Rename ### Viewing & Display[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#viewing--display "Direct link to Viewing & Display") * `view-pdf` - PDF Viewer * `show-javascript` - Show JavaScript in PDF ### Developer Tools[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#developer-tools "Direct link to Developer Tools") * `dev-api-docs` - API Documentation * `dev-folder-scanning-docs` - Folder Scanning Guide * `dev-sso-guide-docs` - SSO Guide * `dev-airgapped-docs` - Air-gapped Setup Guide ### Internal[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#internal "Direct link to Internal") * `handleData` - Handle Data Notes[​](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#notes "Direct link to Notes") --------------------------------------------------------------------------------------------------------------------------- * Tool IDs are case-sensitive (use exact names from the reference above) * Disabling a tool removes it completely from the UI and API * Some tools may depend on others - test your configuration * Changes require container restart to take effect * [Available Endpoint Groups](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#available-endpoint-groups) * [Usage Examples](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#usage-examples) * [Environment Variables](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#environment-variables) * [Settings File (settings.yml)](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#settings-file-settingsyml) * [Complete Endpoint Reference for settings.yml](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#complete-endpoint-reference-for-settingsyml) * [Page Operations](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#page-operations) * [Conversion](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#conversion) * [Security & Signing](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#security--signing) * [Content Extraction & Removal](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#content-extraction--removal) * [Document Editing & Analysis](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#document-editing--analysis) * [Form Fields](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#form-fields) * [Multi-Tool & Automation](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#multi-tool--automation) * [Viewing & Display](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#viewing--display) * [Developer Tools](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#developer-tools) * [Internal](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#internal) * [Notes](https://docs.stirlingpdf.com/Configuration/Endpoint%20or%20Feature%20Customisation/#notes) --- # Folder Scanning | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#__docusaurus_skipToContent_fallback) On this page User Guide for Local Directory Scanning and File Processing[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#user-guide-for-local-directory-scanning-and-file-processing "Direct link to User Guide for Local Directory Scanning and File Processing") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Folder scanning uses settings configured from our pipeline tool, it is advised you first read the [Pipeline Guide](https://docs.stirlingpdf.com/Configuration/Pipeline) ### Setting Up Watched Folders[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#setting-up-watched-folders "Direct link to Setting Up Watched Folders") * Create a folder where you want your files to be monitored. This is your 'watched folder'. * The default directory for this is `./pipeline/watchedFolders/`. * Place any directories you want to be scanned into this folder. This folder should contain multiple folders, each for their own tasks and pipelines. ### Configuring Processing with JSON Files[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#configuring-processing-with-json-files "Direct link to Configuring Processing with JSON Files") * In each directory you want processed (e.g., `./pipeline/watchedFolders/officePrinter`), include a JSON configuration file. * This JSON file should specify how you want the files in the directory to be handled (e.g., what operations to perform on them). This can be made, configured, and downloaded from the Stirling PDF Pipeline interface. For JSON creation guide please see [Pipeline setup](https://docs.stirlingpdf.com/Configuration/Pipeline) ### Automatic Scanning and Processing[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#automatic-scanning-and-processing "Direct link to Automatic Scanning and Processing") * The system automatically checks the watched folder every minute for new directories and files to process. * When a directory with a valid JSON configuration file is found, it begins processing the files inside according to the configuration. ### Processing Steps[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#processing-steps "Direct link to Processing Steps") * Files in each directory are processed according to the instructions in the JSON file. * This might involve file conversions, data filtering, renaming files, etc. If the output of a step is a zip, this zip will be automatically unzipped as it passes to the next process. ### Results and Output[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#results-and-output "Direct link to Results and Output") * After processing, the results are saved in a specified output location. This could be a different folder or location as defined in the JSON file or the default location `./pipeline/finishedFolders/`. * Each processed file is named and organized according to the rules set in the JSON configuration. ### Completion and Cleanup[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#completion-and-cleanup "Direct link to Completion and Cleanup") * Once processing is complete, the original files in the watched folder's directory are removed. * You can find the processed files in the designated output location. ### Error Handling[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#error-handling "Direct link to Error Handling") * If there's an error during processing, the system will not delete the original files, allowing you to check and retry if necessary. ### User Interaction[​](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#user-interaction "Direct link to User Interaction") * As a user, your main tasks are to set up the watched folders, place directories with files for processing, and create the corresponding JSON configuration files. * The system handles the rest, including scanning, processing, and outputting results. * [User Guide for Local Directory Scanning and File Processing](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#user-guide-for-local-directory-scanning-and-file-processing) * [Setting Up Watched Folders](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#setting-up-watched-folders) * [Configuring Processing with JSON Files](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#configuring-processing-with-json-files) * [Automatic Scanning and Processing](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#automatic-scanning-and-processing) * [Processing Steps](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#processing-steps) * [Results and Output](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#results-and-output) * [Completion and Cleanup](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#completion-and-cleanup) * [Error Handling](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#error-handling) * [User Interaction](https://docs.stirlingpdf.com/Configuration/Folder%20Scanning/#user-interaction) --- # SSRF Protection | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#__docusaurus_skipToContent_fallback) On this page What is SSRF and why does it matter?[​](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#what-is-ssrf-and-why-does-it-matter "Direct link to What is SSRF and why does it matter?") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- SSRF (Server-Side Request Forgery) is when someone tricks your server into making HTTP requests on their behalf - to your internal network, cloud metadata endpoints, or other places they shouldn't be able to reach. In Stirling PDF, the risk is tools like **URL to PDF**: a user could supply `http://192.168.1.1/admin` or `http://169.254.169.254/` and your server would fetch it. For self-hosted deployments on a private network, that's a real concern. SSRF protection is **enabled by default** at `MEDIUM` level. For most deployments, you don't need to touch it. warning The URL to PDF feature is **disabled by default** (`system.enableUrlToPDF: false`) due to the SSRF risks described above. It is intended for internal use only and should not be exposed externally. If you enable it, make sure SSRF protection is properly configured. * * * Settings[​](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#settings "Direct link to Settings") ------------------------------------------------------------------------------------------------------------ All settings are under `system.html.urlSecurity` in `settings.yml`. | Setting | Default | Description | | --- | --- | --- | | `enabled` | `true` | Master on/off switch | | `level` | `MEDIUM` | `OFF`, `MEDIUM`, or `MAX` - see below | | `allowedDomains` | `[]` | Domains to always allow | | `blockedDomains` | `[]` | Domains to always block | | `internalTlds` | `.local`, `.internal`, `.corp`, `.home` | TLD suffixes treated as internal | | `blockPrivateNetworks` | `true` | Block RFC1918 private IP ranges | | `blockLocalhost` | `true` | Block 127.x / ::1 | | `blockLinkLocal` | `true` | Block 169.254.x.x / fe80:: | | `blockCloudMetadata` | `true` | Block AWS/GCP/Azure/Oracle/IBM metadata IPs | ### Protection levels[​](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#protection-levels "Direct link to Protection levels") **`MEDIUM`** (default) - Blocks private IPs, localhost, cloud metadata, and internal TLDs. Public internet URLs are allowed by default. **`MAX`** - Only URLs explicitly listed in `allowedDomains` are allowed. Everything else is blocked. Unlike MEDIUM, subdomain matching is not supported in MAX mode - each domain and subdomain must be listed individually. Use this if you know exactly which external domains your users need. **`OFF`** - No SSRF checking at all. Only appropriate if you have network-level controls elsewhere. ### Domain allow and block lists[​](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#domain-allow-and-block-lists "Direct link to Domain allow and block lists") The `allowedDomains` and `blockedDomains` settings work alongside whichever protection level you choose. * **`allowedDomains`** - When set at MEDIUM level, only these domains (and their subdomains) are permitted in addition to the default public-internet access. At MAX level, this is the exclusive list of permitted domains (no subdomain matching). * **`blockedDomains`** - Domains to always deny, regardless of level. Uses exact matching - blocking `example.com` will not block `sub.example.com`. * [What is SSRF and why does it matter?](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#what-is-ssrf-and-why-does-it-matter) * [Settings](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#settings) * [Protection levels](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#protection-levels) * [Domain allow and block lists](https://docs.stirlingpdf.com/Configuration/SSRF-Protection/#domain-allow-and-block-lists) --- # Visual Sign with Custom File Storage | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#__docusaurus_skipToContent_fallback) On this page Stirling PDF provides functionality to store and reuse files across sessions, particularly useful for features like signatures and commonly used assets. This guide explains how to set up and use custom file storage. Overview[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#overview "Direct link to Overview") ------------------------------------------------------------------------------------------------------------------------- The custom file storage system allows you to: * Store files persistently across sessions * Share files between all users or restrict them to specific users * Access stored files through the web UI * Organize files in a structured way Storage Location[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#storage-location "Direct link to Storage Location") ------------------------------------------------------------------------------------------------------------------------------------------------- All custom files should be stored in the `/customFiles/` directory. For features like signatures, the specific path is: /customFiles/signatures/ Access Levels[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#access-levels "Direct link to Access Levels") ---------------------------------------------------------------------------------------------------------------------------------------- The system supports two types of access levels for stored files: ### 1\. All Users Access[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#1-all-users-access "Direct link to 1. All Users Access") Files that should be accessible to all users should be placed in: /customFiles/signatures/ALL_USERS/ This is useful for: * Organization-wide templates * Shared assets * Default signatures or watermarks * Environments where authentication isn't used ### 2\. User-Specific Access[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#2-user-specific-access "Direct link to 2. User-Specific Access") Files that should only be accessible to specific users should be placed in user-specific directories: /customFiles/signatures/{username}/ For example: /customFiles/signatures/john_doe/ These files will only be accessible to the specified user when logged in. Usage in Docker[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#usage-in-docker "Direct link to Usage in Docker") ---------------------------------------------------------------------------------------------------------------------------------------------- When using Docker, make sure to mount the customFiles directory as a volume to persist the files: volumes: - ./customFiles:/customFiles/ Best Practices[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#best-practices "Direct link to Best Practices") ------------------------------------------------------------------------------------------------------------------------------------------- 1. File Organization: * Keep files organized in appropriate subdirectories * Use clear, descriptive filenames * Consider using date-based or category-based organization for large numbers of files 2. Security: * Only place files in ALL\_USERS if they truly need to be accessible to everyone * Regularly review and clean up unused files * Monitor storage usage to prevent excessive accumulation of files 3. Supported File Types: * For signatures: common image formats (PNG, JPG, SVG) * Ensure files are of appropriate size and format for their intended use Example Structure[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#example-structure "Direct link to Example Structure") ---------------------------------------------------------------------------------------------------------------------------------------------------- Here's an example of how your custom files directory might look: /customFiles/├── signatures/│ ├── ALL_USERS/│ │ ├── company-logo.png│ │ └── default-signature.png│ ├── john_doe/│ │ ├── personal-signature.png│ │ └── department-stamp.png│ └── jane_smith/│ └── signature-2024.png Accessing Files[​](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#accessing-files "Direct link to Accessing Files") ---------------------------------------------------------------------------------------------------------------------------------------------- Files stored in these locations will automatically be available in the relevant features of the Stirling PDF web interface. For example, saved signatures will appear in the signature selection interface when using the Sign feature. * [Overview](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#overview) * [Storage Location](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#storage-location) * [Access Levels](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#access-levels) * [1\. All Users Access](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#1-all-users-access) * [2\. User-Specific Access](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#2-user-specific-access) * [Usage in Docker](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#usage-in-docker) * [Best Practices](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#best-practices) * [Example Structure](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#example-structure) * [Accessing Files](https://docs.stirlingpdf.com/Configuration/Sign%20with%20custom%20files/#accessing-files) --- # Keyboard Shortcuts | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#__docusaurus_skipToContent_fallback) On this page Stirling PDF supports keyboard shortcuts for quick tool access and PDF viewer navigation. Custom shortcuts are saved in your browser's local storage, with plans to bind to your account in the future. Tool Shortcuts[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#tool-shortcuts "Direct link to Tool Shortcuts") --------------------------------------------------------------------------------------------------------------------------------- ### Default shortcuts[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#default-shortcuts "Direct link to Default shortcuts") Tools in the Quick Access bar (the "Recommended Tools" category) automatically receive shortcuts: | Windows / Linux | Mac | Action | | --- | --- | --- | | `Ctrl + Alt + 1` | `⌘ + ⌥ + 1` | First Quick Access tool | | `Ctrl + Alt + 2` | `⌘ + ⌥ + 2` | Second Quick Access tool | | `Ctrl + Alt + 3` | `⌘ + ⌥ + 3` | Third Quick Access tool | | … up to `9` | | | All other tools have no default shortcut but can be assigned one. ### Customising shortcuts[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#customising-shortcuts "Direct link to Customising shortcuts") 1. Open **Settings** (gear icon, top right) 2. Go to **Keyboard Shortcuts** 3. Find the tool you want 4. Click **Change shortcut**, then press your key combination 5. Press **Esc** to cancel Your shortcut must include at least one modifier key (`Ctrl`, `Alt`, or `Cmd`). `Shift` alone does not count as a modifier. If the combination is already taken by another tool, you'll see a conflict warning. ### Resetting a shortcut[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#resetting-a-shortcut "Direct link to Resetting a shortcut") Click **Reset** next to any tool to restore its default. If a tool has no default, Reset clears the custom binding. PDF Viewer Shortcuts[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#pdf-viewer-shortcuts "Direct link to PDF Viewer Shortcuts") --------------------------------------------------------------------------------------------------------------------------------------------------- These shortcuts work when the PDF viewer is active (hovered), except for Print which works whenever the viewer is mounted. ### Modifier shortcuts (Ctrl / Cmd + key)[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#modifier-shortcuts-ctrl--cmd--key "Direct link to Modifier shortcuts (Ctrl / Cmd + key)") | Windows / Linux | Mac | Action | | --- | --- | --- | | `Ctrl + P` | `⌘ + P` | Print (works globally when viewer is mounted) | | `Ctrl + F` | `⌘ + F` | Open / focus search | | `Ctrl + S` | `⌘ + S` | Save / apply changes | | `Ctrl + Z` | `⌘ + Z` | Undo | | `Ctrl + Shift + Z` | `⌘ + ⇧ + Z` | Redo | | `Ctrl + Y` | `⌘ + Y` | Redo (alternative) | | `Ctrl + =` / `Ctrl + +` | `⌘ + =` / `⌘ + +` | Zoom in | | `Ctrl + -` | `⌘ + -` | Zoom out | | `Ctrl + 0` | `⌘ + 0` | Reset zoom (fit width) | ### Navigation shortcuts (no modifier needed)[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#navigation-shortcuts-no-modifier-needed "Direct link to Navigation shortcuts (no modifier needed)") | Key | Action | | --- | --- | | `Home` | Jump to first page | | `End` | Jump to last page | | `Page Up` | Previous page | | `Page Down` | Next page | | `Escape` | Close search | ### Rotate tool[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#rotate-tool "Direct link to Rotate tool") When the Rotate tool is active: | Key | Action | | --- | --- | | `←` (Left Arrow) | Rotate left | | `→` (Right Arrow) | Rotate right | Desktop App[​](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#desktop-app "Direct link to Desktop App") ------------------------------------------------------------------------------------------------------------------------ The desktop app adds one extra shortcut: | Windows / Linux | Mac | Action | | --- | --- | --- | | `Ctrl + S` | `⌘ + S` | Save selected files to disk | * [Tool Shortcuts](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#tool-shortcuts) * [Default shortcuts](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#default-shortcuts) * [Customising shortcuts](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#customising-shortcuts) * [Resetting a shortcut](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#resetting-a-shortcut) * [PDF Viewer Shortcuts](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#pdf-viewer-shortcuts) * [Modifier shortcuts (Ctrl / Cmd + key)](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#modifier-shortcuts-ctrl--cmd--key) * [Navigation shortcuts (no modifier needed)](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#navigation-shortcuts-no-modifier-needed) * [Rotate tool](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#rotate-tool) * [Desktop App](https://docs.stirlingpdf.com/Configuration/Keyboard-Shortcuts/#desktop-app) --- # Fail2Ban Integration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/fail2ban/#__docusaurus_skipToContent_fallback) On this page This document provides instructions on how to set up Fail2Ban with Stirling PDF to protect against unauthorized login attempts. (Note Stirling PDF blocks IPs after a set retry count regardless of Fail2Ban, This configuration is only useful for users specifically wanting Fail2Ban configuration) How does Fail2Ban Work with Stirling PDF[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#how-does-fail2ban-work-with-stirling-pdf "Direct link to How does Fail2Ban Work with Stirling PDF") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Stirling PDF logs failed authentication attempts to a log file which Fail2Ban monitors. When it detects multiple failed login attempts from the same IP address, Fail2Ban automatically blocks that IP address for a configured period of time. Prerequisites[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------------- * Fail2Ban installed on your system * Access to Stirling PDF log directory * Security settings configured: * Settings File * Environment Variable * Docker Compose security: enableLogin: true # Login must be enabled for Fail2Ban integration loginAttemptCount: -1 # Set to -1 when using Fail2Ban recommended but not required SECURITY_ENABLELOGIN=trueSECURITY_LOGINATTEMPTCOUNT=-1 services: stirling-pdf: environment: SECURITY_ENABLELOGIN: true SECURITY_LOGINATTEMPTCOUNT: -1 ### Important Configuration Notes[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#important-configuration-notes "Direct link to Important Configuration Notes") * The `enableLogin` setting must be set to `true` as Fail2Ban integration requires authentication to be active * When using Fail2Ban, set `loginAttemptCount` to `-1` to disable the built-in account locking mechanism and let Fail2Ban handle login attempt management * For more details on security configuration options, refer to the [System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) documentation Configuration[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#configuration "Direct link to Configuration") -------------------------------------------------------------------------------------------------------------------- ### Log File Location[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#log-file-location "Direct link to Log File Location") The log file location containing the failed authentication messages depends on your installation type: * **Default/Docker Installation**: `./logs/invalid-auths.log` * **Windows Desktop**: `%APPDATA%\Stirling-PDF\logs\invalid-auths.log` * **MacOS Desktop**: `~/Library/Application Support/Stirling-PDF/logs/invalid-auths.log` * **Linux Desktop**: `~/.config/Stirling-PDF/logs/invalid-auths.log` ### Example Fail2Ban Filter[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#example-fail2ban-filter "Direct link to Example Fail2Ban Filter") `/etc/fail2ban/filter.d/stirling-pdf.conf` [Definition]failregex = Failed login attempt from IP: ### Example Jail Configuration[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#example-jail-configuration "Direct link to Example Jail Configuration") `/etc/fail2ban/jail.local` [stirling-pdf]enabled = truefilter = stirling-pdflogpath = /logs/invalid-auths.logmaxretry = 5findtime = 300bantime = 3600 Configuration parameters: * `maxretry`: Number of failed attempts before ban (default: 5) * `findtime`: Time window for failed attempts in seconds (default: 300 seconds / 5 minutes) * `bantime`: Duration of the ban in seconds (default: 3600 seconds / 1 hour) ### Ensure access to Logs path[​](https://docs.stirlingpdf.com/Configuration/fail2ban/#ensure-access-to-logs-path "Direct link to Ensure access to Logs path") * Docker Compose * Docker Run Modify your `docker-compose.yml` to expose the log directory: services: stirling-pdf: volumes: - ./logs:/logs Add the volume mount to your Docker run command: -v ./logs:/logs * [How does Fail2Ban Work with Stirling PDF](https://docs.stirlingpdf.com/Configuration/fail2ban/#how-does-fail2ban-work-with-stirling-pdf) * [Prerequisites](https://docs.stirlingpdf.com/Configuration/fail2ban/#prerequisites) * [Important Configuration Notes](https://docs.stirlingpdf.com/Configuration/fail2ban/#important-configuration-notes) * [Configuration](https://docs.stirlingpdf.com/Configuration/fail2ban/#configuration) * [Log File Location](https://docs.stirlingpdf.com/Configuration/fail2ban/#log-file-location) * [Example Fail2Ban Filter](https://docs.stirlingpdf.com/Configuration/fail2ban/#example-fail2ban-filter) * [Example Jail Configuration](https://docs.stirlingpdf.com/Configuration/fail2ban/#example-jail-configuration) * [Ensure access to Logs path](https://docs.stirlingpdf.com/Configuration/fail2ban/#ensure-access-to-logs-path) --- # OAuth 2.0 Single Sign-On Configuration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Server Stirling PDF supports Single Sign-On (SSO) using OAuth 2.0 OpenID Connect (OIDC). This allows users to log in using accounts from external providers such as Google, GitHub, Keycloak, Authentik, and others. > **Looking for SAML 2.0 SSO?** See [SAML SSO Configuration](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) > (Enterprise tier). Prerequisites[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------------------------------- Before configuring OAuth 2.0 SSO, ensure you have: * [ ] Stirling PDF with login enabled (`security.enableLogin: true`) * [ ] Valid license for Professional tier or higher * [ ] An OAuth 2.0 provider account (Google, GitHub, Keycloak, etc.) * [ ] Registered OAuth application with your provider * [ ] OAuth Client ID and Client Secret from your provider * [ ] Public HTTPS URL configured with `system.backendUrl` set to your public backend API URL (often same as frontend, verify `https://your-domain.com/api/v1/info/status` is accessible) * [ ] Callback URL added to provider: `https://your-domain.com/login/oauth2/code/` > **Tip**: Start with `loginMethod: all` during initial setup to allow both username/password and OAuth login. This ensures you can always access the admin account if SSO configuration needs adjustment. Setup Guide[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#setup-guide "Direct link to Setup Guide") --------------------------------------------------------------------------------------------------------------------------------- ### Step 1: Configure Login Settings[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-1-configure-login-settings "Direct link to Step 1: Configure Login Settings") Enable login and set the login method to allow both standard and OAuth authentication during initial setup. * settings.yml * Environment Variables security: enableLogin: true loginMethod: all # Allows both username/password and OAuth login SECURITY_ENABLELOGIN=trueSECURITY_LOGINMETHOD=all **Login Method Options:** * `all`: Enables all login methods (username/password + OAuth 2) * `normal`: Username/password only * `oauth2`: OAuth 2 SSO only (disables username/password login) * `saml2`: SAML 2 SSO only (Enterprise tier) ### Step 2: Create Initial Admin Account[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-2-create-initial-admin-account "Direct link to Step 2: Create Initial Admin Account") Before enabling OAuth, create an initial admin account using one of these methods: **Option A: Use initialLogin credentials** (recommended for first setup) * settings.yml * Environment Variables security: initialLogin: username: 'admin' password: 'yourSecurePassword123' SECURITY_INITIALLOGIN_USERNAME=adminSECURITY_INITIALLOGIN_PASSWORD=yourSecurePassword123 **Option B: Create admin manually** 1. Access Stirling PDF with OAuth disabled 2. Create an admin user through the UI 3. Then enable OAuth ### Step 3: Configure OAuth Provider[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-3-configure-oauth-provider "Direct link to Step 3: Configure OAuth Provider") Set `security.oauth2.enabled` to `true` and configure your chosen provider. * Google * GitHub * Keycloak * Authentik * Generic OIDC * settings.yml * Environment Variables security: oauth2: enabled: true client: google: clientId: clientSecret: scopes: email, profile useAsUsername: email provider: google autoCreateUser: true blockRegistration: false SECURITY_OAUTH2_ENABLED=trueSECURITY_OAUTH2_CLIENT_GOOGLE_CLIENTID=SECURITY_OAUTH2_CLIENT_GOOGLE_CLIENTSECRET=SECURITY_OAUTH2_CLIENT_GOOGLE_SCOPES=email, profileSECURITY_OAUTH2_CLIENT_GOOGLE_USEASUSERNAME=emailSECURITY_OAUTH2_PROVIDER=googleSECURITY_OAUTH2_AUTOCREATEUSER=trueSECURITY_OAUTH2_BLOCKREGISTRATION=false **Provider Setup:** 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select existing 3. Enable Google+ API 4. Create OAuth 2.0 credentials (Web application) 5. Add authorized redirect URI: `https://your-domain.com/login/oauth2/code/google` 6. Copy Client ID and Client Secret * settings.yml * Environment Variables security: oauth2: enabled: true client: github: clientId: clientSecret: scopes: read:user useAsUsername: login provider: github autoCreateUser: true blockRegistration: false SECURITY_OAUTH2_ENABLED=trueSECURITY_OAUTH2_CLIENT_GITHUB_CLIENTID=SECURITY_OAUTH2_CLIENT_GITHUB_CLIENTSECRET=SECURITY_OAUTH2_CLIENT_GITHUB_SCOPES=read:userSECURITY_OAUTH2_CLIENT_GITHUB_USEASUSERNAME=loginSECURITY_OAUTH2_PROVIDER=githubSECURITY_OAUTH2_AUTOCREATEUSER=trueSECURITY_OAUTH2_BLOCKREGISTRATION=false **Provider Setup:** 1. Go to [GitHub Developer Settings](https://github.com/settings/developers) 2. Create new OAuth App 3. Set Authorization callback URL: `https://your-domain.com/login/oauth2/code/github` 4. Copy Client ID and generate Client Secret * settings.yml * Environment Variables security: oauth2: enabled: true issuer: https://your-keycloak.com/realms/your-realm clientId: clientSecret: scopes: openid, profile, email useAsUsername: preferred_username provider: keycloak autoCreateUser: true blockRegistration: false SECURITY_OAUTH2_ENABLED=trueSECURITY_OAUTH2_ISSUER=https://your-keycloak.com/realms/your-realmSECURITY_OAUTH2_CLIENTID=SECURITY_OAUTH2_CLIENTSECRET=SECURITY_OAUTH2_SCOPES=openid, profile, emailSECURITY_OAUTH2_USEASUSERNAME=preferred_usernameSECURITY_OAUTH2_PROVIDER=keycloakSECURITY_OAUTH2_AUTOCREATEUSER=trueSECURITY_OAUTH2_BLOCKREGISTRATION=false **Provider Setup:** 1. Access your Keycloak admin console 2. Select your realm 3. Create new client (OpenID Connect) 4. Set Valid Redirect URIs: `https://your-domain.com/login/oauth2/code/keycloak` 5. Enable "Client authentication" for confidential access 6. Copy Client ID and Client Secret from Credentials tab * settings.yml * Environment Variables security: oauth2: enabled: true issuer: https://your-authentik.com/application/o/stirling-pdf/ clientId: clientSecret: scopes: openid, profile, email useAsUsername: preferred_username provider: authentik autoCreateUser: true blockRegistration: false SECURITY_OAUTH2_ENABLED=trueSECURITY_OAUTH2_ISSUER=https://your-authentik.com/application/o/stirling-pdf/SECURITY_OAUTH2_CLIENTID=SECURITY_OAUTH2_CLIENTSECRET=SECURITY_OAUTH2_SCOPES=openid, profile, emailSECURITY_OAUTH2_USEASUSERNAME=preferred_usernameSECURITY_OAUTH2_PROVIDER=authentikSECURITY_OAUTH2_AUTOCREATEUSER=trueSECURITY_OAUTH2_BLOCKREGISTRATION=false **Provider Setup:** 1. Create new Provider (OAuth2/OpenID) 2. Create new Application 3. Set Redirect URIs: `https://your-domain.com/login/oauth2/code/authentik` 4. Copy Client ID and Client Secret * settings.yml * Environment Variables security: oauth2: enabled: true issuer: clientId: clientSecret: scopes: openid, profile, email useAsUsername: email provider: autoCreateUser: true blockRegistration: false SECURITY_OAUTH2_ENABLED=trueSECURITY_OAUTH2_ISSUER=SECURITY_OAUTH2_CLIENTID=SECURITY_OAUTH2_CLIENTSECRET=SECURITY_OAUTH2_SCOPES=openid, profile, emailSECURITY_OAUTH2_USEASUSERNAME=emailSECURITY_OAUTH2_PROVIDER=SECURITY_OAUTH2_AUTOCREATEUSER=trueSECURITY_OAUTH2_BLOCKREGISTRATION=false **Requirements:** * Provider must support OpenID Connect Discovery * Must expose `/.well-known/openid-configuration` endpoint ### Step 4: Configure Callback URL[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-4-configure-callback-url "Direct link to Step 4: Configure Callback URL") When registering your application with the OAuth provider, use this callback URL format: https:///login/oauth2/code/ **Understanding the Provider Slug:** The `` portion of the callback URL must exactly match your `security.oauth2.provider` configuration value: security: oauth2: provider: authentik # This becomes part of the callback URL With the above configuration, your callback URL becomes: https://your-domain.com/login/oauth2/code/authentik **Examples:** * Google: `https://stirling.example.com/login/oauth2/code/google` * GitHub: `https://stirling.example.com/login/oauth2/code/github` * Keycloak: `https://stirling.example.com/login/oauth2/code/keycloak` * Custom provider: `https://stirling.example.com/login/oauth2/code/mycompany` > **Important**: If the provider slug in the callback URL doesn't match your `security.oauth2.provider` value, OAuth login will fail with redirect errors. > **Tip**: For generic OIDC providers (not Google/GitHub/Keycloak), you can set `provider` to any lowercase alphanumeric value that makes sense for your organization. ### Step 5: Test OAuth Login and Promote User[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-5-test-oauth-login-and-promote-user "Direct link to Step 5: Test OAuth Login and Promote User") 1. Restart Stirling PDF 2. Test OAuth login in an incognito/private browser window 3. Verify you can log in with your OAuth provider 4. Log in with your initial admin account (username/password) 5. Go to **Settings** → **User Management** 6. Find the OAuth user account (created during test login) 7. Change role to **Admin** ### Step 6: (Optional) Switch to SSO-Only Mode[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-6-optional-switch-to-sso-only-mode "Direct link to Step 6: (Optional) Switch to SSO-Only Mode") Once you've verified OAuth works and promoted an OAuth user to admin, you can disable username/password login: * settings.yml * Environment Variables security: loginMethod: oauth2 # Disables username/password login SECURITY_LOGINMETHOD=oauth2 > **Important**: If you set `loginMethod: oauth2` before creating an OAuth admin user, you will only be able to log in via OAuth, and all new OAuth users will have regular user permissions. Keep `loginMethod: all` until you have at least one OAuth user with admin privileges. Configuration Reference[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#configuration-reference "Direct link to Configuration Reference") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Required Properties[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#required-properties "Direct link to Required Properties") | Property | Description | Example | | --- | --- | --- | | `security.oauth2.enabled` | Enable OAuth 2 login | `true` | | `security.oauth2.clientId` | Client ID from your OAuth provider | `stirling-pdf-client` | | `security.oauth2.clientSecret` | Client Secret from your OAuth provider | `your-secret-key` | | `security.oauth2.provider` | Provider name | `google`, `github`, `keycloak`, `authentik` | ### Optional Properties[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#optional-properties "Direct link to Optional Properties") | Property | Description | Default | Example | | --- | --- | --- | --- | | `security.oauth2.issuer` | OIDC issuer URL (required for generic providers, must support `/.well-known/openid-configuration`) | \- | `https://keycloak.example.com/realms/myrealm` | | `security.oauth2.autoCreateUser` | Auto-create users on first login | `false` | `true` | | `security.oauth2.blockRegistration` | Block new user registration, only allow pre-registered users | `false` | `true` | | `security.oauth2.scopes` | Space or comma-separated list of OAuth scopes | Provider-specific | `openid, profile, email` | | `security.oauth2.useAsUsername` | Claim to use as username (options depend on provider) | Provider-specific | `email`, `preferred_username`, `login` | ### Provider-Specific Configuration[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#provider-specific-configuration "Direct link to Provider-Specific Configuration") **Named providers** (Google, GitHub, Keycloak): oauth2: client: google: # or github, keycloak clientId: ... clientSecret: ... **Generic providers** (Authentik, custom OIDC): oauth2: issuer: # Must support OIDC discovery clientId: ... clientSecret: ... ### Username Claim Options[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#username-claim-options "Direct link to Username Claim Options") **Google:** * `email`, `name`, `given_name`, `family_name` * See [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) **GitHub:** * `login`, `email`, `name` * See [GitHub OAuth Scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) **Keycloak/Generic OIDC:** * `email`, `preferred_username`, `nickname`, `name` Advanced Configuration[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#advanced-configuration "Direct link to Advanced Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### Backend URL Configuration[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#backend-url-configuration "Direct link to Backend URL Configuration") If your Stirling PDF backend is accessible at a different URL than the frontend, configure the backend URL: * settings.yml * Environment Variables system: backendUrl: https://stirling-api.example.com SYSTEM_BACKENDURL=https://stirling-api.example.com Verify the backend URL is correct by checking that `https://your-domain.com/api/v1/info/status` is accessible. ### Auto-Login Feature[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#auto-login-feature "Direct link to Auto-Login Feature") > **Tier**: Enterprise Automatically redirect users to OAuth login page, bypassing the Stirling PDF login screen. * settings.yml * Environment Variables premium: proFeatures: SSOAutoLogin: true PREMIUM_PROFEATURES_SSOAUTOLOGIN=true **Auto-login Activation Requirements:** Auto-login only triggers when **ALL** of the following conditions are met: 1. `ssoAutoLogin` is enabled (as configured above) 2. `loginMethod` is NOT `'all'` and NOT `'normal'` (i.e., SSO-only mode required) 3. Exactly one OAuth provider is configured **Behavior:** * When all conditions are met: Users are automatically redirected to OAuth provider login * When conditions are not met: Standard login page is displayed * After 5 failed login attempts (configurable via `security.loginAttemptCount`), auto-redirect is disabled * Users can still access manual login by navigating directly to `/login` ### User Interface[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#user-interface "Direct link to User Interface") Once OAuth is configured, users will see the SSO login button: | ![login-page.png](https://docs.stirlingpdf.com/assets/images/login-page-3e2a1af13b9328365cf7f08bfb162636.png) | ![sso-login-option.png]() | | --- | --- | Troubleshooting[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#troubleshooting "Direct link to Troubleshooting") --------------------------------------------------------------------------------------------------------------------------------------------- ### Common Issues[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#common-issues "Direct link to Common Issues") **"OAuth2 authentication error"** * Verify callback URL matches exactly (including provider slug) * Check client ID and secret are correct * Ensure provider allows the configured redirect URI * Confirm `security.oauth2.provider` matches the provider slug in callback URL **"Invalid issuer"** * Confirm issuer URL is correct * Test `https://your-issuer/.well-known/openid-configuration` returns valid JSON * Check network connectivity from Stirling PDF container to provider **"User not created"** * Set `autoCreateUser: true` * Check `blockRegistration` is `false` or user is pre-registered * Verify license allows user count **Users redirected to wrong URL** * Verify `system.backendUrl` is configured correctly * Test that `https://your-domain.com/api/v1/info/status` is accessible * Check provider's registered redirect URIs match your domain ### Debug Logging[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#debug-logging "Direct link to Debug Logging") Enable OAuth debug logging to troubleshoot authentication issues. * custom\_settings.yml * Environment Variables logging: level: org.springframework.security.oauth2: DEBUG LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_OAUTH2=DEBUG Known Limitations[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#known-limitations "Direct link to Known Limitations") --------------------------------------------------------------------------------------------------------------------------------------------------- * OAuth users must be manually promoted to admin role after first login * Provider discovery requires `/.well-known/openid-configuration` endpoint support * Auto-login feature requires Enterprise tier See Also[​](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#see-also "Direct link to See Also") ------------------------------------------------------------------------------------------------------------------------ * [SAML SSO Configuration](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) - Enterprise SAML 2.0 setup * [System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) - Additional security settings * [External Database](https://docs.stirlingpdf.com/Configuration/External%20Database) - User storage configuration * [Prerequisites](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#prerequisites) * [Setup Guide](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#setup-guide) * [Step 1: Configure Login Settings](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-1-configure-login-settings) * [Step 2: Create Initial Admin Account](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-2-create-initial-admin-account) * [Step 3: Configure OAuth Provider](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-3-configure-oauth-provider) * [Step 4: Configure Callback URL](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-4-configure-callback-url) * [Step 5: Test OAuth Login and Promote User](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-5-test-oauth-login-and-promote-user) * [Step 6: (Optional) Switch to SSO-Only Mode](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#step-6-optional-switch-to-sso-only-mode) * [Configuration Reference](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#configuration-reference) * [Required Properties](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#required-properties) * [Optional Properties](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#optional-properties) * [Provider-Specific Configuration](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#provider-specific-configuration) * [Username Claim Options](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#username-claim-options) * [Advanced Configuration](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#advanced-configuration) * [Backend URL Configuration](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#backend-url-configuration) * [Auto-Login Feature](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#auto-login-feature) * [User Interface](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#user-interface) * [Troubleshooting](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#troubleshooting) * [Common Issues](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#common-issues) * [Debug Logging](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#debug-logging) * [Known Limitations](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#known-limitations) * [See Also](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration/#see-also) --- # Single Sign-On (SSO) Overview | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration/#__docusaurus_skipToContent_fallback) On this page Stirling PDF supports Single Sign-On (SSO) authentication through two protocols: OAuth 2.0 / OpenID Connect (OIDC)[​](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration/#oauth-20--openid-connect-oidc "Direct link to OAuth 2.0 / OpenID Connect (OIDC)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Tier**: Server OAuth 2.0 SSO allows login via popular identity providers like: * Google * GitHub * Keycloak * Authentik * Any OIDC-compliant provider **[→ Configure OAuth 2.0 SSO](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) ** **Key Features:** * Easy setup with major providers * Auto-discovery via `.well-known/openid-configuration` * Social login support * Suitable for small to medium organizations * * * SAML 2.0[​](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration/#saml-20 "Direct link to SAML 2.0") ---------------------------------------------------------------------------------------------------------------------------- > **Tier**: Enterprise SAML 2.0 SSO provides enterprise-grade authentication with: * Okta * Azure AD (Entra ID) * Google Workspace * OneLogin * Any SAML 2.0-compliant IdP **[→ Configure SAML 2.0 SSO](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) ** **Key Features:** * Enterprise identity provider integration * Advanced security controls * Single Logout (SLO) support * Suitable for large organizations * [OAuth 2.0 / OpenID Connect (OIDC)](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration/#oauth-20--openid-connect-oidc) * [SAML 2.0](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration/#saml-20) --- # Process Limits | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Process-Limits/#__docusaurus_skipToContent_fallback) On this page Stirling PDF sometimes runs external tools to handle tools such as conversions or advanced operations Tools like LibreOffice, Tesseract, Ghostscript, and others. All these tools are optional to Stirling PDFs general operation. > Some tools listed here may not be actively used in the current version of Stirling PDF. Their configuration is kept in place for potential re-introduction in future updates. Two types of limits are customised for every external tool: * **Session limits** - how many of a given process can run at the same time * **Timeouts** - how long a single process can run before it's killed Both sit under `processExecutor` in `settings.yml`. A value of `0` means "use the default." * * * Session limits[​](https://docs.stirlingpdf.com/Configuration/Process-Limits/#session-limits "Direct link to Session limits") ----------------------------------------------------------------------------------------------------------------------------- Controls how many concurrent instances of each process are allowed. Extra requests queue up and wait. | Setting | Default | What it controls | | --- | --- | --- | | `sessionLimit.libreOfficeSessionLimit` | `1` | Word/Excel/PowerPoint/HTML → PDF | | `sessionLimit.tesseractSessionLimit` | `1` | OCR (Tesseract is single-threaded) | | `sessionLimit.pdfToHtmlSessionLimit` | `1` | PDF → HTML | | `sessionLimit.ghostscriptSessionLimit` | `8` | PDF compression, repair, manipulation | | `sessionLimit.pythonOpenCvSessionLimit` | `8` | Image processing | | `sessionLimit.imageMagickSessionLimit` | `4` | Image conversion | | `sessionLimit.qpdfSessionLimit` | `2` | Split, merge, encrypt PDFs | | `sessionLimit.ocrMyPdfSessionLimit` | `2` | Add OCR overlay to existing PDFs | | `sessionLimit.weasyPrintSessionLimit` | `16` | HTML/CSS → PDF (WeasyPrint) | | `sessionLimit.calibreSessionLimit` | `1` | E-book conversions | | `sessionLimit.ffmpegSessionLimit` | `2` | Video/audio processing | | `sessionLimit.installAppSessionLimit` | `1` | Internal install tasks | **Increase** limits on a beefy server with concurrent users. **Decrease** them on low-RAM servers - LibreOffice in particular is memory-hungry. info Be mindful of memory and CPU usage when raising session limits. Each concurrent process consumes resources, and setting limits too high can starve the host or cause out-of-memory issues possibly killing the instance. Start with the defaults and increase gradually while monitoring your server. * * * Timeouts[​](https://docs.stirlingpdf.com/Configuration/Process-Limits/#timeouts "Direct link to Timeouts") ----------------------------------------------------------------------------------------------------------- How long (in minutes) a process can run before it's forcibly killed and an error is returned. | Setting | Default | | --- | --- | | `timeoutMinutes.libreOfficeTimeoutMinutes` | `30` | | `timeoutMinutes.tesseractTimeoutMinutes` | `30` | | `timeoutMinutes.ghostscriptTimeoutMinutes` | `30` | | `timeoutMinutes.pythonOpenCvTimeoutMinutes` | `30` | | `timeoutMinutes.imageMagickTimeoutMinutes` | `30` | | `timeoutMinutes.qpdfTimeoutMinutes` | `30` | | `timeoutMinutes.ocrMyPdfTimeoutMinutes` | `30` | | `timeoutMinutes.weasyPrintTimeoutMinutes` | `30` | | `timeoutMinutes.calibreTimeoutMinutes` | `30` | | `timeoutMinutes.ffmpegTimeoutMinutes` | `30` | | `timeoutMinutes.pdfToHtmlTimeoutMinutes` | `20` | | `timeoutMinutes.installAppTimeoutMinutes` | `60` | **Increase** timeouts if users process very large files that legitimately take longer. **Decrease** them if you want faster failure and tighter resource control. * * * Examples[​](https://docs.stirlingpdf.com/Configuration/Process-Limits/#examples "Direct link to Examples") ----------------------------------------------------------------------------------------------------------- ### Conservative - low-resource server[​](https://docs.stirlingpdf.com/Configuration/Process-Limits/#conservative---low-resource-server "Direct link to Conservative - low-resource server") * Settings File * Environment Variable * Docker Compose processExecutor: sessionLimit: libreOfficeSessionLimit: 1 tesseractSessionLimit: 1 ghostscriptSessionLimit: 2 imageMagickSessionLimit: 2 pythonOpenCvSessionLimit: 2 weasyPrintSessionLimit: 4 qpdfSessionLimit: 1 ocrMyPdfSessionLimit: 1 timeoutMinutes: libreOfficeTimeoutMinutes: 10 tesseractTimeoutMinutes: 15 PROCESSEXECUTOR_SESSIONLIMIT_LIBREOFFICESSESSIONLIMIT=1PROCESSEXECUTOR_SESSIONLIMIT_TESSERACTSESSIONLIMIT=1PROCESSEXECUTOR_SESSIONLIMIT_GHOSTSCRIPTSESSIONLIMIT=2PROCESSEXECUTOR_TIMEOUTMINUTES_LIBREOFFICETIMEOUTMINUTES=10PROCESSEXECUTOR_TIMEOUTMINUTES_TESSERACTTIMEOUTMINUTES=15 services: stirling-pdf: image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest environment: PROCESSEXECUTOR_SESSIONLIMIT_LIBREOFFICESSESSIONLIMIT: 1 PROCESSEXECUTOR_SESSIONLIMIT_TESSERACTSESSIONLIMIT: 1 PROCESSEXECUTOR_TIMEOUTMINUTES_LIBREOFFICETIMEOUTMINUTES: 10 ### High-throughput - powerful server[​](https://docs.stirlingpdf.com/Configuration/Process-Limits/#high-throughput---powerful-server "Direct link to High-throughput - powerful server") * Settings File * Environment Variable processExecutor: sessionLimit: libreOfficeSessionLimit: 4 tesseractSessionLimit: 4 ghostscriptSessionLimit: 16 imageMagickSessionLimit: 8 pythonOpenCvSessionLimit: 16 qpdfSessionLimit: 8 ocrMyPdfSessionLimit: 4 timeoutMinutes: libreOfficeTimeoutMinutes: 60 tesseractTimeoutMinutes: 60 ocrMyPdfTimeoutMinutes: 60 PROCESSEXECUTOR_SESSIONLIMIT_LIBREOFFICESSESSIONLIMIT=4PROCESSEXECUTOR_SESSIONLIMIT_TESSERACTSESSIONLIMIT=4PROCESSEXECUTOR_TIMEOUTMINUTES_LIBREOFFICETIMEOUTMINUTES=60 * [Session limits](https://docs.stirlingpdf.com/Configuration/Process-Limits/#session-limits) * [Timeouts](https://docs.stirlingpdf.com/Configuration/Process-Limits/#timeouts) * [Examples](https://docs.stirlingpdf.com/Configuration/Process-Limits/#examples) * [Conservative - low-resource server](https://docs.stirlingpdf.com/Configuration/Process-Limits/#conservative---low-resource-server) * [High-throughput - powerful server](https://docs.stirlingpdf.com/Configuration/Process-Limits/#high-throughput---powerful-server) --- # Google Drive File Picker | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Server Stirling PDF allows users to select Files for processing through tools via google drive. Google Api Access[​](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#google-api-access "Direct link to Google Api Access") ------------------------------------------------------------------------------------------------------------------------------------------------------ To enable this features for your users, you must first set up your Google environment. This includes creating a Google Cloud project. Follow the **Setting up your environment** section of [this guide](https://developers.google.com/workspace/drive/picker/guides/overview#setup) to do so. Stirling PDF configuration[​](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#stirling-pdf-configuration "Direct link to Stirling PDF configuration") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- premium: ... enabled: true # Enable license key checks for pro/enterprise features proFeatures: ... googleDrive: enabled: true clientId: apiKey: appId: * `premium.enabled`: Set to `true` to enable premium features. * `googleDrive.enabled`: Set to `true` to enable google drive file picker features. * `googleDrive.clientId`: Your Google web app's client ID. [Go to Credentials](https://console.cloud.google.com/apis/credentials) and Click **Create credentials > OAuth client ID**. * `googleDrive.apiKey`: API key for google api access. [Go to Credentials](https://console.cloud.google.com/apis/credentials) and Click **Create credentials > API key**. * `googleDrive.appId`: Google drive app ID also known as your Project Number Found in your [IAM&Admin Project Settings](https://console.cloud.google.com/iam-admin/settings) > #### ⚠️ Note[​](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _You must set the Authorized Javascript origins for your OAuth client ID to include your Stirling PDF host domain or IP address._ Configurations Examples[​](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#configurations-examples "Direct link to Configurations Examples") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Below are examples of the full configuration for enabling the google Drive Picker: * Settings File * Local Environment * Docker Run * Docker Compose premium: enabled: true # Enable license key checks for pro/enterprise features proFeatures: googleDrive: enabled: true clientId: apiKey: appId: export PREMIUM_ENABLED=trueexport PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED=trueexport PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID=""export PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY=""export PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID="" -e PREMIUM_ENABLED=true \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED=true \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID="" \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY="" \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID="" \ environment: PREMIUM_ENABLED: true PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED: true PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID: PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY: PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID: * [Google Api Access](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#google-api-access) * [Stirling PDF configuration](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#stirling-pdf-configuration) * [Configurations Examples](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker/#configurations-examples) --- # Other Customisations | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#__docusaurus_skipToContent_fallback) On this page Stirling PDF offers various other customisation options, such as: Static File Overrides[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#static-file-overrides "Direct link to Static File Overrides") ---------------------------------------------------------------------------------------------------------------------------------------------------------- You can override static files (logos, images, favicons, etc.) by placing custom versions in the `customFiles/static/` directory. ### How It Works[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#how-it-works "Direct link to How It Works") Stirling PDF checks for files in this order: 1. **First:** `customFiles/static/` (your custom files) 2. **Fallback:** Built-in static files embedded in the application This means you can replace any static resource by placing a file with the matching path in `customFiles/static/`. ### Finding File Paths to Override[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#finding-file-paths-to-override "Direct link to Finding File Paths to Override") Static files in the application come from the `frontend/public/` folder in the source code. The mapping is direct: **Frontend source → Your override path:** * `frontend/public/favicon.svg` → `customFiles/static/favicon.svg` * `frontend/public/modern-logo/logo.svg` → `customFiles/static/modern-logo/logo.svg` * `frontend/public/classic-logo/logo.svg` → `customFiles/static/classic-logo/logo.svg` **To see what files you can override:** 1. Browse the [frontend/public folder on GitHub](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/frontend/public) 2. Match the directory structure in your `customFiles/static/` folder Common files you might want to override: **Favicons & Icons:** * `favicon.svg`, `favicon.ico` - Browser favicons * `apple-touch-icon.png` - iOS home screen icon * `android-chrome-192x192.png` - Android icon (192x192) * `android-chrome-512x512.png` - Android icon (512x512) **Logo Variants (Both classic-logo/ and modern-logo/):** Both logo directories contain the same file structure - just replace `classic-logo/` or `modern-logo/` with whichever style you're using: * `{style}/StirlingPDFLogoBlackText.svg` - Logo with black text (light mode) * `{style}/StirlingPDFLogoWhiteText.svg` - Logo with white text (dark mode) * `{style}/StirlingPDFLogoGreyText.svg` - Logo with grey text * `{style}/StirlingPDFLogoNoTextDark.svg` - Logo without text (dark variant) * `{style}/StirlingPDFLogoNoTextLight.svg` - Logo without text (light variant) * `{style}/logo-tooltip.svg` - Small logo for tooltips * `{style}/favicon.ico` - Style-specific favicon * `{style}/logo192.png`, `{style}/logo512.png` - PNG versions at different sizes * `{style}/Firstpage.png` - First page preview image Where `{style}` is either `classic-logo` or `modern-logo` depending on your logo style setting: **Settings file (configs/settings.yml):** ui: logoStyle: classic # Options: 'classic' or 'modern' **Environment variable (Docker):** UI_LOGOSTYLE=classic **In-app configuration:** Settings → UI → Logo Style (requires login enabled) **Other Assets:** * `moon.svg` - Dark mode toggle icon * `robots.txt` - Search engine directives * `manifest.json`, `manifest-classic.json` - Web app manifests * Images, fonts, and locales ### Example: Custom Favicon[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-custom-favicon "Direct link to Example: Custom Favicon") # Your directory structurecustomFiles/ └── static/ ├── favicon.svg └── favicon.ico Docker compose: volumes: - ./customFiles:/customFiles:rw Restart the container - your custom favicons will be used! ### Example: Custom Logo (Simple)[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-custom-logo-simple "Direct link to Example: Custom Logo (Simple)") customFiles/ └── static/ └── classic-logo/ └── StirlingPDFLogoBlackText.svg This overrides the classic logo with black text (used in light mode). **Important:** Make sure your logo style is set to `classic` in your configuration: ui: logoStyle: classic # Must match the directory you're overriding! Or via environment variable: UI_LOGOSTYLE=classic If you have `logoStyle: modern` set, override files in `modern-logo/` instead! ### Example: Complete Branding Customization[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-complete-branding-customization "Direct link to Example: Complete Branding Customization") To fully rebrand Stirling PDF with your company logo, override multiple variants: customFiles/ └── static/ ├── favicon.svg # Main favicon ├── favicon.ico # Legacy favicon └── classic-logo/ # Or modern-logo/ if using modern style ├── StirlingPDFLogoBlackText.svg # Light mode with text ├── StirlingPDFLogoWhiteText.svg # Dark mode with text ├── StirlingPDFLogoNoTextLight.svg # Light mode icon only ├── StirlingPDFLogoNoTextDark.svg # Dark mode icon only ├── logo-tooltip.svg # Small icon ├── favicon.ico # Style-specific favicon └── Firstpage.png # Homepage preview **Important:** Set your logo style to match the directory: ui: logoStyle: classic # Use 'classic' if overriding classic-logo/, 'modern' if overriding modern-logo/ Or via environment variable: `UI_LOGOSTYLE=classic` **Tips:** * For consistent branding across light/dark modes, provide both: * `StirlingPDFLogoBlackText.svg` (shows on light backgrounds) * `StirlingPDFLogoWhiteText.svg` (shows on dark backgrounds) * You can also configure this in-app: Settings → UI → Logo Style (if you have login enabled) ### Advanced: Overriding Built Files (HTML, JS, CSS)[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#advanced-overriding-built-files-html-js-css "Direct link to Advanced: Overriding Built Files (HTML, JS, CSS)") **⚠️ For developers only!** Files like `index.html`, JavaScript bundles, and CSS are **generated** by the build process from `frontend/src/`. To override these: 1. Clone the Stirling PDF repository 2. Make your changes to the React source code in `frontend/src/` 3. Build the frontend: `npm run build` (from the `frontend/` directory) 4. The built files appear in `frontend/dist/` 5. Copy the specific files you want to override to `customFiles/static/` matching the path structure **Example:** To override `index.html`: # After building the frontendcp frontend/dist/index.html customFiles/static/index.html **Warning:** Built files may include hashed filenames (e.g., `assets/index-abc123.js`) that change with each build. Overriding these requires matching the exact filename from your build and is not recommended for most users. * * * Defaulting Language[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#defaulting-language "Direct link to Defaulting Language") ---------------------------------------------------------------------------------------------------------------------------------------------------- Default language selection via the `SYSTEM_DEFAULTLOCALE` environment variable. Accepted values include `de-DE`, `fr-FR`, `ar-AR` and all other languages codes that are within Stirling PDFs current list. Google Search Visibility (robots.txt)[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#google-search-visibility-robotstxt "Direct link to Google Search Visibility (robots.txt)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Enable or disable search engine visibility with the `ALLOW_GOOGLE_VISIBILITY` variable. Custom Root path[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#custom-root-path "Direct link to Custom Root path") ------------------------------------------------------------------------------------------------------------------------------------------- Redirect the root path of the application using `APP_ROOT_PATH`. This is for changing websites like stirlingtools.com to instead host the interface at stirlingtools.com/`APP_ROOT_PATH` like stirlingtools.com/demo Enable/Disable Analytics[​](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#enabledisable-analytics "Direct link to Enable/Disable Analytics") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Analytics can be enabled/disabled with `SYSTEM_ENABLEANALYTICS` or system: enableAnalytics: 'true' In configs/Settings.yml * [Static File Overrides](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#static-file-overrides) * [How It Works](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#how-it-works) * [Finding File Paths to Override](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#finding-file-paths-to-override) * [Example: Custom Favicon](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-custom-favicon) * [Example: Custom Logo (Simple)](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-custom-logo-simple) * [Example: Complete Branding Customization](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#example-complete-branding-customization) * [Advanced: Overriding Built Files (HTML, JS, CSS)](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#advanced-overriding-built-files-html-js-css) * [Defaulting Language](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#defaulting-language) * [Google Search Visibility (robots.txt)](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#google-search-visibility-robotstxt) * [Custom Root path](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#custom-root-path) * [Enable/Disable Analytics](https://docs.stirlingpdf.com/Configuration/Other%20Customisations/#enabledisable-analytics) --- # Usage Monitoring | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Enterprise Stirling PDF provides robust usage monitoring capabilities through its API, allowing you to track application usage patterns and performance metrics. Non-Persistent Usage Monitoring API[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#non-persistent-usage-monitoring-api "Direct link to Non-Persistent Usage Monitoring API") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The following API endpoints are available to all users to monitor usage statistics. These endpoints provide non-persistent usage data that can be queried on demand. | Endpoint | Description | | --- | --- | | `GET /api/v1/info/status` | Application status and version information | | `GET /api/v1/info/requests` | Total count of POST requests for a specific endpoint (optional query parameter: `endpoint`) | | `GET /api/v1/info/requests/unique` | Count of unique users for POST requests for a specific endpoint | | `GET /api/v1/info/requests/all` | POST requests count for all endpoints | | `GET /api/v1/info/requests/all/unique` | Unique users count for POST requests for all endpoints | | `GET /api/v1/info/load` | Total count of GET requests for a specific endpoint (optional query parameter: `endpoint`) | | `GET /api/v1/info/load/unique` | Count of unique users for GET requests for a specific endpoint | | `GET /api/v1/info/load/all` | GET requests count for all endpoints | | `GET /api/v1/info/load/all/unique` | Unique users count for GET requests for all endpoints | All endpoints return a JSON response with the requested statistics. Prometheus Monitoring Configuration[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#prometheus-monitoring-configuration "Direct link to Prometheus Monitoring Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Stirling PDF supports application metrics monitoring using Prometheus. This feature allows you to track application performance, usage patterns, and health metrics. ### Prerequisites[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#prerequisites "Direct link to Prerequisites") 1. A valid Stirling PDF enterprise license 2. Enterprise mode enabled in your configuration 3. Running with additional features enabled (DISABLE\_ADDITIONAL\_FEATURES=false) ### Configuration[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#configuration "Direct link to Configuration") Configure Prometheus monitoring using your preferred method: * Settings File * Environment Variable * Docker Run * Docker Compose Configure in your `/configs/custom_settings.yml` file: management: endpoints: web: exposure: include: prometheus,health,info endpoint: health: show-details: always metrics: export: prometheus: enabled: trueenterprisemanagement: metrics: enabled: true Set the `JAVA_CUSTOM_OPTS` environment variable: JAVA_CUSTOM_OPTS="-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true" docker run -d \ -p 8080:8080 \ -e JAVA_CUSTOM_OPTS="-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true" \ stirlingtools/stirling-pdf:latest services: stirling-pdf: image: stirlingtools/stirling-pdf:latest environment: JAVA_CUSTOM_OPTS: "-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true" **What this configures:** * Prometheus metrics endpoint exposure * Health and info endpoints for basic monitoring * Detailed health information * Prometheus metrics export * Enterprise metrics collection ### Accessing Metrics[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#accessing-metrics "Direct link to Accessing Metrics") Once configured, Prometheus metrics are available at the following endpoint: https://your-stirling-pdf-instance/actuator/prometheus This endpoint provides metrics in a format that can be scraped by a Prometheus server. ### Configuring Prometheus Server[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#configuring-prometheus-server "Direct link to Configuring Prometheus Server") Add the following job configuration to your Prometheus server's configuration file (`prometheus.yml`): scrape_configs: - job_name: 'stirling-pdf' metrics_path: '/actuator/prometheus' scrape_interval: 15s static_configs: - targets: ['your-stirling-pdf-host:port'] ### Available Metrics[​](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#available-metrics "Direct link to Available Metrics") With Prometheus integration enabled, Stirling PDF exposes the following types of metrics: * **JVM metrics**: Memory usage, garbage collection, thread utilization * **System metrics**: CPU usage, file descriptors * **Application metrics**: Request rates, processing times * **PDF processing metrics**: Document operations, conversion statistics * [Non-Persistent Usage Monitoring API](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#non-persistent-usage-monitoring-api) * [Prometheus Monitoring Configuration](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#prometheus-monitoring-configuration) * [Prerequisites](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#prerequisites) * [Configuration](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#configuration) * [Accessing Metrics](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#accessing-metrics) * [Configuring Prometheus Server](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#configuring-prometheus-server) * [Available Metrics](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring/#available-metrics) --- # Database Backups | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/DATABASE/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Server Functionality Overview[​](https://docs.stirlingpdf.com/Configuration/DATABASE/#functionality-overview "Direct link to Functionality Overview") ----------------------------------------------------------------------------------------------------------------------------------------------- The newly introduced feature enhances the application with robust database backup and import capabilities. This feature is designed to ensure data integrity and provide a straightforward way to manage database backups. Here's how it works: 1. Automatic Backup Creation * The system automatically creates a database backup every day at midnight. This ensures that there is always a recent backup available, minimizing the risk of data loss. 2. Manual Backup Export * Admin actions that modify the user database trigger a manual export of the database. This keeps the backup up-to-date with the latest changes and provides an extra layer of data security. 3. Importing Database Backups * Admin users can import a database backup either via the web interface or API endpoints. This allows for easy restoration of the database to a previous state in case of data corruption or other issues. * The import process ensures that the database structure and data are correctly restored, maintaining the integrity of the application. 4. Managing Backup Files * Admins can view a list of all existing backup files, along with their creation dates and sizes. This helps in managing storage and identifying the most recent or relevant backups. * Backup files can be downloaded for offline storage or transferred to other environments, providing flexibility in database management. * Unnecessary backup files can be deleted through the interface to free up storage space and maintain an organized backup directory. User Interface[​](https://docs.stirlingpdf.com/Configuration/DATABASE/#user-interface "Direct link to User Interface") ----------------------------------------------------------------------------------------------------------------------- ### Web Interface[​](https://docs.stirlingpdf.com/Configuration/DATABASE/#web-interface "Direct link to Web Interface") 1. Upload SQL files to import database backups. 2. View details of existing backups, such as file names, creation dates, and sizes. 3. Download backup files for offline storage. 4. Delete outdated or unnecessary backup files. ### API Endpoints[​](https://docs.stirlingpdf.com/Configuration/DATABASE/#api-endpoints "Direct link to API Endpoints") 1. Import database backups by uploading SQL files. 2. Download backup files. 3. Delete backup files. This new functionality streamlines database management, ensuring that backups are always available and easy to manage, thus improving the reliability and resilience of the application. * [Functionality Overview](https://docs.stirlingpdf.com/Configuration/DATABASE/#functionality-overview) * [User Interface](https://docs.stirlingpdf.com/Configuration/DATABASE/#user-interface) * [Web Interface](https://docs.stirlingpdf.com/Configuration/DATABASE/#web-interface) * [API Endpoints](https://docs.stirlingpdf.com/Configuration/DATABASE/#api-endpoints) --- # Audit Logging | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/Audit%20Logging/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Enterprise Logs every operation, who ran it, what tool, which files, when. All data is stored in the database. We recommend external database setup when using this feature due to the potential volume. Please note the data stored is customisable based on you and your organisations needs and legal requirements. Settings are under `premium.enterpriseFeatures.audit`. | Setting | Default | Description | | --- | --- | --- | | `enabled` | `true` | Turn audit logging on or off | | `level` | `2` | Verbosity: `0` = off, `1` = basic, `2` = standard, `3` = verbose | | `retentionDays` | `90` | Days to keep audit records before purging (`0` = infinite retention) | | `captureFileHash` | `false` | Store a SHA-256 hash of each processed file | | `capturePdfAuthor` | `false` | Extract and store PDF author metadata | | `captureOperationResults` | `false` | Store operation return values - high volume, use sparingly | Audit levels[​](https://docs.stirlingpdf.com/Configuration/Audit%20Logging/#audit-levels "Direct link to Audit levels") ------------------------------------------------------------------------------------------------------------------------ | Level | What's recorded | | --- | --- | | `0` - OFF | Nothing | | `1` - BASIC | File modifications only - PDF operations (compress, split, merge, etc.) and settings changes | | `2` - STANDARD | BASIC + user actions (login/logout, account changes, general GET requests) | | `3` - VERBOSE | STANDARD + continuous polling calls and all GET requests | Example[​](https://docs.stirlingpdf.com/Configuration/Audit%20Logging/#example "Direct link to Example") --------------------------------------------------------------------------------------------------------- * Settings File * Environment Variable * Docker Compose premium: enabled: true key: your-enterprise-license-key enterpriseFeatures: audit: enabled: true level: 2 retentionDays: 365 captureFileHash: true capturePdfAuthor: false captureOperationResults: false PREMIUM_ENABLED=truePREMIUM_KEY=your-enterprise-license-keyPREMIUM_ENTERPRISEFEATURES_AUDIT_ENABLED=truePREMIUM_ENTERPRISEFEATURES_AUDIT_LEVEL=2PREMIUM_ENTERPRISEFEATURES_AUDIT_RETENTIONDAYS=365PREMIUM_ENTERPRISEFEATURES_AUDIT_CAPTUREFILEHASH=truePREMIUM_ENTERPRISEFEATURES_AUDIT_CAPTUREPDFAUTHOR=falsePREMIUM_ENTERPRISEFEATURES_AUDIT_CAPTUREOPERATIONRESULTS=false services: stirling-pdf: image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest environment: PREMIUM_ENABLED: true PREMIUM_KEY: your-enterprise-license-key PREMIUM_ENTERPRISEFEATURES_AUDIT_ENABLED: true PREMIUM_ENTERPRISEFEATURES_AUDIT_LEVEL: 2 PREMIUM_ENTERPRISEFEATURES_AUDIT_RETENTIONDAYS: 365 PREMIUM_ENTERPRISEFEATURES_AUDIT_CAPTUREFILEHASH: true > **Note on performance:** `captureFileHash` adds a SHA-256 calculation for every file processed - noticeable overhead at high volume. `captureOperationResults` stores full operation output in the database and can grow very large; only enable it when specifically needed. * [Audit levels](https://docs.stirlingpdf.com/Configuration/Audit%20Logging/#audit-levels) * [Example](https://docs.stirlingpdf.com/Configuration/Audit%20Logging/#example) --- # File Sharing and Storage | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#__docusaurus_skipToContent_fallback) On this page Alpha Feature File Sharing and Storage is currently in **alpha**. Functionality may change, and some features are incomplete. Use in production at your own risk. Stirling PDF can store files on the server and let users share them with each other. Files can be shared directly with specific users or via shareable links. Admins can set storage quotas to control disk usage. This is a **Pro/Enterprise** feature that requires authentication to be enabled. * * * What You Can Do[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#what-you-can-do "Direct link to What You Can Do") -------------------------------------------------------------------------------------------------------------------------------------- * **Store files server-side** -- upload PDFs and other files that persist across sessions * **Share with specific users** -- grant other registered users access to your files with configurable permissions * **Share via link** -- generate a shareable link that any logged-in user with the link can access * **Control access levels** -- assign Editor, Commenter, or Viewer roles to shared users * **Set storage quotas** -- limit storage per user, per file, or system-wide * **Audit access** -- see who accessed your shared links and when * **Automatic cleanup** -- expired share links and orphaned files are cleaned up daily * * * Prerequisites[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------------------------- * **Authentication must be enabled** (`security.enableLogin: true`) * For share links: `system.frontendUrl` must be set to your instance URL * For email notifications when sharing: `mail.enabled: true` with valid SMTP configuration * * * Enabling File Storage[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#enabling-file-storage "Direct link to Enabling File Storage") -------------------------------------------------------------------------------------------------------------------------------------------------------- * Settings File * Environment Variables storage: enabled: true provider: local # 'local' or 'database' local: basePath: './storage' # Filesystem path (local provider only) STORAGE_ENABLED=trueSTORAGE_PROVIDER=localSTORAGE_LOCAL_BASEPATH=./storage ### Storage Providers[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-providers "Direct link to Storage Providers") | Provider | Config Value | Description | Best For | | --- | --- | --- | --- | | **Local Filesystem** | `local` | Files stored on disk under `basePath` | Most deployments, large files | | **Database** | `database` | Files stored as BLOBs in the database | Simple setups where you want everything in one place | tip The **local** provider is recommended for most deployments. It handles large files well and keeps database size manageable. The **database** provider is convenient but uses more memory with large files. ### Docker Volume Mount[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#docker-volume-mount "Direct link to Docker Volume Mount") When using the local provider with Docker, mount the storage directory so files persist across container restarts: volumes: - ./stirling-storage:/storage * * * Enabling File Sharing[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#enabling-file-sharing "Direct link to Enabling File Sharing") -------------------------------------------------------------------------------------------------------------------------------------------------------- * Settings File * Environment Variables storage: enabled: true sharing: enabled: true # Master switch for all sharing linkEnabled: true # Enable shareable links emailEnabled: true # Send email notifications when sharing linkExpirationDays: 3 # Days until share links expire STORAGE_SHARING_ENABLED=trueSTORAGE_SHARING_LINKENABLED=trueSTORAGE_SHARING_EMAILENABLED=trueSTORAGE_SHARING_LINKEXPIRATIONDAYS=3 ### Feature Dependencies[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#feature-dependencies "Direct link to Feature Dependencies") | Feature | What It Needs | | --- | --- | | File Storage | `security.enableLogin: true` | | File Sharing | Storage enabled | | Shareable Links | Sharing enabled + `system.frontendUrl` set | | Email Notifications | Sharing enabled + `mail.enabled: true` | | Shared Signing | Storage enabled + `storage.signing.enabled: true` | * * * Storage Quotas[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-quotas "Direct link to Storage Quotas") ----------------------------------------------------------------------------------------------------------------------------------- Control how much storage space is available. * Settings File * Environment Variables storage: quotas: maxStorageMbPerUser: -1 # Per-user cap in MB (-1 = unlimited) maxStorageMbTotal: -1 # Total system cap in MB (-1 = unlimited) maxFileMb: -1 # Max size per upload in MB (-1 = unlimited) STORAGE_QUOTAS_MAXSTORAGEMBPERUSER=500STORAGE_QUOTAS_MAXSTORAGEMBTOTAL=10000STORAGE_QUOTAS_MAXFILEMB=100 Quotas are checked before a file is stored. When replacing an existing file, only the size difference counts against the quota. * * * Access Roles[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#access-roles "Direct link to Access Roles") ----------------------------------------------------------------------------------------------------------------------------- When sharing a file, you choose what level of access to grant: | Role | Can View/Download | Can Replace File | In Signing Workflows | | --- | --- | --- | --- | | **Editor** | Yes | Yes | Can sign | | **Commenter** | Yes | No | Can sign | | **Viewer** | Yes | No | Read-only | The file **owner** always has full access. The default role is **Editor**. The difference between Commenter and Viewer only matters in [Shared Signing](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing) workflows -- both are read-only for regular file sharing. * * * Sharing Files[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#sharing-files "Direct link to Sharing Files") -------------------------------------------------------------------------------------------------------------------------------- ### Share with a Specific User[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-with-a-specific-user "Direct link to Share with a Specific User") From the file manager, select a file and share it with another user by their username or email address. You can choose the access role when sharing. If you enter an email address for someone who doesn't have an account, the system will create a share link and email it to them (if email notifications are enabled). ### Share via Link[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-via-link "Direct link to Share via Link") Generate a shareable link for any file you own. Anyone who is logged in and has the link can access the file. Links expire automatically based on your `linkExpirationDays` setting (default: 3 days). You can revoke a share link at any time, which immediately removes access and deletes all access records for that link. The share link URL follows the format: https://your-stirling-instance.com/share/{token} info Share links require the recipient to be logged in. There is no anonymous or public access -- the link is an additional credential on top of authentication. ### Access History[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#access-history "Direct link to Access History") For any share link you've created, you can view who accessed it, whether they viewed or downloaded the file, and when. * * * Security[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#security "Direct link to Security") ----------------------------------------------------------------------------------------------------------------- * **All endpoints require authentication** -- there is no anonymous file access * **Owner-only controls** -- only the file owner can update, delete, or manage sharing * **Random tokens** -- share link tokens are cryptographically random UUIDs * **Automatic expiration** -- expired links return an error and are cleaned up daily * **Revocation** -- owners can revoke any share link immediately * **Access auditing** -- every share link access is recorded with user, action type, and timestamp * * * Known Limitations[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#known-limitations "Direct link to Known Limitations") -------------------------------------------------------------------------------------------------------------------------------------------- * Share links require `system.frontendUrl` to be configured * Share links require the user to be logged in -- there is no public/anonymous access * The database storage provider uses more memory with large files (use the local provider for large deployments) * * * Troubleshooting[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#troubleshooting "Direct link to Troubleshooting") -------------------------------------------------------------------------------------------------------------------------------------- ### "Storage is disabled"[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-is-disabled "Direct link to "Storage is disabled"") * Verify `storage.enabled: true` in your settings * Verify `security.enableLogin: true` ### "Share links are disabled"[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-links-are-disabled "Direct link to "Share links are disabled"") * Verify `storage.sharing.linkEnabled: true` * Verify `system.frontendUrl` is set to your instance URL ### "Email sharing is disabled"[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#email-sharing-is-disabled "Direct link to "Email sharing is disabled"") * Verify `storage.sharing.emailEnabled: true` * Verify `mail.enabled: true` with valid SMTP settings ### Share link returns 410 Gone[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-link-returns-410-gone "Direct link to Share link returns 410 Gone") * The link has expired. The file owner needs to create a new one. ### Quota exceeded (HTTP 403)[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#quota-exceeded-http-403 "Direct link to Quota exceeded (HTTP 403)") * Increase `maxStorageMbPerUser` or `maxStorageMbTotal`, or delete unused files to free up space * * * API Reference[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#api-reference "Direct link to API Reference") -------------------------------------------------------------------------------------------------------------------------------- For users who want to integrate programmatically, the full API endpoints are listed below. See [API Documentation](https://docs.stirlingpdf.com/API) for details. | Method | Endpoint | Description | | --- | --- | --- | | POST | `/api/v1/storage/files` | Upload file | | PUT | `/api/v1/storage/files/{id}` | Update file (owner only) | | GET | `/api/v1/storage/files` | List accessible files | | GET | `/api/v1/storage/files/{id}` | Get file metadata | | GET | `/api/v1/storage/files/{id}/download` | Download file | | DELETE | `/api/v1/storage/files/{id}` | Delete file (owner only) | | POST | `/api/v1/storage/files/{id}/shares/users` | Share with user | | DELETE | `/api/v1/storage/files/{id}/shares/users/{username}` | Revoke user share | | DELETE | `/api/v1/storage/files/{id}/shares/self` | Leave shared file | | POST | `/api/v1/storage/files/{id}/shares/links` | Create share link | | DELETE | `/api/v1/storage/files/{id}/shares/links/{token}` | Revoke share link | | GET | `/api/v1/storage/share-links/{token}` | Access via share link | | GET | `/api/v1/storage/share-links/{token}/metadata` | Get share link info | | GET | `/api/v1/storage/share-links/accessed` | List your accessed links | | GET | `/api/v1/storage/files/{id}/shares/links/{token}/accesses` | Access history (owner only) | * * * Related[​](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#related "Direct link to Related") -------------------------------------------------------------------------------------------------------------- * [Shared Signing](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing) -- Collaborative multi-participant document signing * [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) -- Individual certificate signing * [System and Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) -- JWT, sessions, server certificates * [What You Can Do](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#what-you-can-do) * [Prerequisites](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#prerequisites) * [Enabling File Storage](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#enabling-file-storage) * [Storage Providers](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-providers) * [Docker Volume Mount](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#docker-volume-mount) * [Enabling File Sharing](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#enabling-file-sharing) * [Feature Dependencies](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#feature-dependencies) * [Storage Quotas](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-quotas) * [Access Roles](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#access-roles) * [Sharing Files](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#sharing-files) * [Share with a Specific User](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-with-a-specific-user) * [Share via Link](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-via-link) * [Access History](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#access-history) * [Security](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#security) * [Known Limitations](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#known-limitations) * [Troubleshooting](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#troubleshooting) * ["Storage is disabled"](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#storage-is-disabled) * ["Share links are disabled"](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-links-are-disabled) * ["Email sharing is disabled"](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#email-sharing-is-disabled) * [Share link returns 410 Gone](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#share-link-returns-410-gone) * [Quota exceeded (HTTP 403)](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#quota-exceeded-http-403) * [API Reference](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#api-reference) * [Related](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage/#related) --- # UI Customisation | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#__docusaurus_skipToContent_fallback) On this page Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. Application Name Settings[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#application-name-settings "Direct link to Application Name Settings") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ These settings control the visible application name: * `appName` - Defines the visible application name shown in the window name and navbar if navbar is not defined separately * `homeDescription` - The description displayed on the homepage under the navbar that first greets the user * `appNameNavbar` - The app name shown within the navbar for all pages Show update notifications[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#show-update-notifications "Direct link to Show update notifications") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ These settings (in Settings.yml) control system behavior and customization capabilities: * `showUpdate` - Controls whether update notifications are displayed * `showUpdateOnlyAdmin` - When true, restricts update notifications to admin users only (requires `showUpdate: true`) UI Customization Options[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#ui-customization-options "Direct link to UI Customization Options") --------------------------------------------------------------------------------------------------------------------------------------------------------------- ### In-App Settings Management (Recommended)[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#in-app-settings-management-recommended "Direct link to In-App Settings Management (Recommended)") If you have login enabled and are logged in as an admin, you can configure all settings directly in the application through the **Settings** menu. No need to edit `settings.yml` manually! **How to access:** 1. Enable login: `SECURITY_ENABLELOGIN=true` 2. Log in as an admin user 3. Navigate to **Settings** in the application 4. Configure all options through the UI 5. Changes apply immediately **Available customizations:** * Application name and branding * Update notification settings * Language settings * Theme preferences * Logo style (classic/modern) * Custom logo upload ### Static File Overrides (Advanced)[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#static-file-overrides-advanced "Direct link to Static File Overrides (Advanced)") For customization beyond the built-in settings, you can override static files like logos, favicons, and images: services: stirling-pdf: image: stirlingtools/stirling-pdf:latest ports: - '8080:8080' volumes: - ./customFiles:/customFiles:rw Then place your custom files in `customFiles/static/` matching the path structure. Common examples: * `customFiles/static/favicon.svg` - Custom favicon * `customFiles/static/classic-logo/logo.svg` - Custom logo * `customFiles/static/modern-logo/logo.svg` - Custom modern logo **Learn more:** [Other Customisations - Static File Overrides](https://docs.stirlingpdf.com/Configuration/Other%20Customisations#static-file-overrides) ### Fork the Frontend (Developers)[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#fork-the-frontend-developers "Direct link to Fork the Frontend (Developers)") For complete UI customization: 1. Clone the Stirling PDF repository 2. Modify the React components in `frontend/src/` 3. Build the frontend: `cd frontend && npm install && npm run build` 4. Use static file overrides or build your own Docker image This approach requires maintaining your fork and manually merging updates. Configuration Examples[​](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#configuration-examples "Direct link to Configuration Examples") --------------------------------------------------------------------------------------------------------------------------------------------------------- * Settings File * Local Environment * Docker Run * Docker Compose ui: appName: exampleAppName # Application's visible name homeDescription: I am a description # Short description or tagline shown on homepage appNameNavbar: navbarName # Name displayed on the navigation barsystem: showUpdate: false # Control update notification visibility showUpdateOnlyAdmin: false # Restrict update notifications to admins You can configure the UI and system settings in two ways when running locally: **Option 1: Using Java Properties** java -jar Stirling-PDF.jar \ -DAPP_HOME_NAME="New Application Name" \ -DSHOW_UPDATE=false \ -DSHOW_UPDATE_ONLY_ADMIN=false **Option 2: Using Environment Variables** export UI_APPNAME="Stirling PDF"export UI_HOMEDESCRIPTION="Your locally hosted one-stop-shop for all your PDF needs."export UI_APPNAVBARNAME="Stirling PDF"export SYSTEM_SHOWUPDATE=falseexport SYSTEM_SHOWUPDATEONLYADMIN=false -e UI_APPNAME=Stirling PDF \-e UI_HOMEDESCRIPTION=Your locally hosted one-stop-shop for all your PDF needs. \-e UI_APPNAVBARNAME=Stirling PDF \-e SYSTEM_SHOWUPDATE=false \-e SYSTEM_SHOWUPDATEONLYADMIN=false environment: UI_APPNAME: Stirling PDF UI_HOMEDESCRIPTION: Your locally hosted one-stop-shop for all your PDF needs. UI_APPNAVBARNAME: Stirling PDF SYSTEM_SHOWUPDATE: "false" SYSTEM_SHOWUPDATEONLYADMIN: "false" * [Application Name Settings](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#application-name-settings) * [Show update notifications](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#show-update-notifications) * [UI Customization Options](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#ui-customization-options) * [In-App Settings Management (Recommended)](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#in-app-settings-management-recommended) * [Static File Overrides (Advanced)](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#static-file-overrides-advanced) * [Fork the Frontend (Developers)](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#fork-the-frontend-developers) * [Configuration Examples](https://docs.stirlingpdf.com/Configuration/UI%20Customisation/#configuration-examples) --- # SAML 2.0 Single Sign-On Configuration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#__docusaurus_skipToContent_fallback) On this page > **Tier**: Enterprise Stirling PDF supports SAML 2.0 Single Sign-On for enterprise deployments. This allows integration with Identity Providers (IdP) like Okta, Azure AD, Google Workspace, OneLogin, Authentik, and others. > **Looking for OAuth 2.0 SSO?** See [OAuth SSO Configuration](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) > (Server tier). Prerequisites[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------------------------------- Before starting, ensure you have: * [ ] **Enterprise license active** - SAML requires Enterprise tier * [ ] **Configs directory mounted** - Docker volume mounted (e.g., `./configs:/configs:ro`) * [ ] **Public backend URL configured** - Set `system.backendUrl` to your public backend API URL (often same as frontend, verify `https://your-domain.com/api/v1/info/status` is accessible) * [ ] **Reverse proxy configured** - Nginx/Traefik/Caddy with X-Forwarded-\* headers forwarding * [ ] **Login enabled** - `security.enableLogin: true` in settings * [ ] **Admin account ready** - Either existing admin or plan to use `security.initialLogin` credentials * [ ] **IdP admin access** - Access to your SAML Identity Provider (Okta, Azure AD, etc.) > ⚠️ **License Requirement**: SAML 2.0 authentication requires an **ENTERPRISE** license. Existing users created before SAML was license-gated are grandfathered and can continue using SAML with any license tier. > 💡 **Tip**: Start with `loginMethod: all` during initial setup to allow both username/password and SAML login. This ensures you can always access the admin account if SAML configuration needs adjustment. Setup Guide[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#setup-guide "Direct link to Setup Guide") -------------------------------------------------------------------------------------------------------------------------------- Follow these steps in order to configure SAML SSO: ### Step 1: Setup Certificates[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-1-setup-certificates "Direct link to Step 1: Setup Certificates") SAML requires 3 certificate files for mutual trust: | Certificate | Purpose | Action | | --- | --- | --- | | **SP Private Key** | Sign SAML requests to IdP | Generate with OpenSSL | | **SP Certificate** | Prove identity to IdP | Generate with OpenSSL, upload to IdP | | **IdP Certificate** | Verify SAML responses from IdP | Download from your IdP | #### 1a. Generate Service Provider (SP) Keypair[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#1a-generate-service-provider-sp-keypair "Direct link to 1a. Generate Service Provider (SP) Keypair") Stirling PDF needs a keypair to sign SAML requests and verify responses. > ℹ️ **If you don't have a keypair**, generate one using OpenSSL: > > openssl req -newkey rsa:2048 -nodes \ -keyout private_key.key \ -x509 -days 365 \ -out certificate.crt \ -subj "/C=US/ST=State/L=City/O=Stirling-PDF/CN=your-domain.com" > > **Command explanation:** > > * `rsa:2048`: Generates 2048-bit RSA key (secure standard) > * `-nodes`: No passphrase (required for automated systems) > * `-days 365`: Certificate valid for 1 year > * Creates two files: `private_key.key` (private) and `certificate.crt` (public) If you already have a keypair, ensure you have both the private key and certificate files ready. #### 1b. Download IdP Certificate[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#1b-download-idp-certificate "Direct link to 1b. Download IdP Certificate") 1. Go to your IdP admin panel 2. Find SAML app/provider settings 3. Download signing certificate (PEM format) 4. Save as `idp-certificate.pem` #### 1c. Place Certificates in Mounted Directory[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#1c-place-certificates-in-mounted-directory "Direct link to 1c. Place Certificates in Mounted Directory") Place all 3 certificates inside your mounted configs directory: ./configs/ ├── private_key.key ← SP private key (keep secure!) ├── certificate.crt ← SP certificate (will upload to IdP) └── idp-certificate.pem ← IdP certificate (downloaded) > ⚠️ **Critical**: Use absolute paths in configuration: `/configs/filename.pem` (no `file:` or `classpath:` prefix for Docker) ### Step 2: Configure Stirling PDF[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-2-configure-stirling-pdf "Direct link to Step 2: Configure Stirling PDF") Configure SAML authentication by providing: * **IdP URLs and certificate** - Get these from your Identity Provider (obtained from IdP admin panel) * **SP certificates** - Point to the certificate files created in Step 1 * **Backend URL** - Your public backend API URL for SAML callbacks (often same as frontend, e.g., `https://stirling.example.com`) * **Login settings** - Enable login and set method to `all` (allows both username/password and SAML during setup) **Key configuration options:** * `autoCreateUser: true` - Automatically create user accounts on first SAML login * `blockRegistration: false` - Allow new SAML users (set to `true` to require admin pre-approval) * `registrationId: stirling` - Identifier used in SAML URLs (must match across all URLs) * settings.yml * Environment Variables Edit `/configs/settings.yml`: security: enableLogin: true loginMethod: all # Keep 'all' during initial setup saml2: enabled: true autoCreateUser: true blockRegistration: false registrationId: stirling # Identity Provider (IdP) URLs (get from your IdP) idpSingleLoginUrl: https://idp.example.com/saml/login idpSingleLogoutUrl: https://idp.example.com/saml/logout idpIssuer: https://idp.example.com/entityid idpCert: /configs/idp-certificate.pem # Service Provider (SP) Certificates privateKey: /configs/private_key.key spCert: /configs/certificate.crt# Required for SAML callback URLssystem: backendUrl: https://stirling.example.com Add to your `docker-compose.yml` or Docker run command: environment: SYSTEM_BACKENDURL: https://stirling.example.com SECURITY_ENABLELOGIN: true SECURITY_LOGINMETHOD: all SECURITY_SAML2_ENABLED: true SECURITY_SAML2_AUTOCREATEUSER: true SECURITY_SAML2_BLOCKREGISTRATION: false SECURITY_SAML2_REGISTRATIONID: stirling SECURITY_SAML2_IDPSINGLELOGINURL: https://idp.example.com/saml/login SECURITY_SAML2_IDPSINGLELOGOUTURL: https://idp.example.com/saml/logout SECURITY_SAML2_IDPISSUER: https://idp.example.com/entityid SECURITY_SAML2_IDPCERT: /configs/idp-certificate.pem SECURITY_SAML2_PRIVATEKEY: /configs/private_key.key SECURITY_SAML2_SPCERT: /configs/certificate.crt > 💡 **Tip**: Replace the example URLs (`idp.example.com`) with actual values from your Identity Provider. #### Additional Configuration: baseUrl for SAML SLO[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#additional-configuration-baseurl-for-saml-slo "Direct link to Additional Configuration: baseUrl for SAML SLO") For Single Logout (SLO) to work correctly in production, you must also set the `baseUrl` property: * custom\_settings.yml * Environment Variables Add to `/configs/custom_settings.yml`: baseUrl: "https://your-domain.com" Add to your Docker Compose environment variables: environment: baseUrl: "https://your-domain.com" > ⚠️ **Important**: Both `system.backendUrl` and `baseUrl` should be set to your public-facing URL for SAML to work correctly in production. ### Step 3: Configure Your Identity Provider[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-3-configure-your-identity-provider "Direct link to Step 3: Configure Your Identity Provider") Provide your IdP with these Service Provider details: **Entity ID / SP Metadata URL:** https://your-domain.com/saml2/service-provider-metadata/stirling **Assertion Consumer Service (ACS) URL:** https://your-domain.com/login/saml2/sso/stirling **Single Logout (SLO) URL:** https://your-domain.com/logout > 📌 **Important**: Replace `stirling` with your `registrationId` value if you changed it. The registration ID must match in all URLs. **Upload SP Certificate to IdP** (Critical Step): 1. Open `certificate.crt` (your SP public certificate) 2. In your IdP's SAML app configuration, find "Verification Certificate" or "SP Certificate" field 3. Upload or paste `certificate.crt` contents 4. Save IdP configuration > Without uploading the SP certificate, your IdP cannot verify requests from Stirling PDF. **Configure NameID and Attributes:** * NameID format: `email` or `unspecified` * Ensure at least one username attribute is sent: `username`, `emailaddress`, `name`, `upn`, or `uid` ### Step 4: Test SAML Login[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-4-test-saml-login "Direct link to Step 4: Test SAML Login") 1. Open an incognito/private browser window 2. Navigate to `https://your-domain.com` 3. Click "Login via Single Sign-On" button 4. You'll be redirected to your IdP login page 5. Enter your IdP credentials 6. You'll be redirected back to Stirling PDF 7. A new user account is automatically created (if `autoCreateUser: true`) > ⚠️ **If login fails**, check application logs for SAML errors. See [Troubleshooting](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#troubleshooting) > section. ### Step 5: Promote SAML User to Admin[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-5-promote-saml-user-to-admin "Direct link to Step 5: Promote SAML User to Admin") 1. Log in with your initial admin account (username/password) 2. Go to **Settings** → **User Management** 3. Find the SAML user account (created during test login) 4. Change **Role** to **Admin** 5. **Save** > ⚠️ **Important**: Keep at least one SAML user with admin privileges before switching to SSO-only mode. ### Step 6 (Optional): Switch to SSO-Only Mode[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-6-optional-switch-to-sso-only-mode "Direct link to Step 6 (Optional): Switch to SSO-Only Mode") Once you've verified SAML works and have a SAML admin user: security: loginMethod: saml2 # Disables username/password login Restart Stirling PDF. Configuration Reference[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#configuration-reference "Direct link to Configuration Reference") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Required Properties[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#required-properties "Direct link to Required Properties") | Property | Description | Example | | --- | --- | --- | | `security.saml2.enabled` | Enable SAML 2 authentication | `true` | | `security.saml2.idpSingleLoginUrl` | IdP's Single Sign-On URL | `https://idp.example.com/sso` | | `security.saml2.idpSingleLogoutUrl` | IdP's Single Logout URL | `https://idp.example.com/slo` | | `security.saml2.idpIssuer` | IdP's Entity ID / Issuer | `https://idp.example.com` | | `security.saml2.idpCert` | IdP's signing certificate (PEM format) | `/configs/idp-cert.pem` | | `security.saml2.privateKey` | Your SP private key | `/configs/private_key.key` | | `security.saml2.spCert` | Your SP certificate | `/configs/certificate.crt` | | `system.backendUrl` | Public HTTPS URL for callbacks | `https://stirling.example.com` | ### Optional Properties[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#optional-properties "Direct link to Optional Properties") | Property | Default | Description | | --- | --- | --- | | `security.saml2.autoCreateUser` | `false` | Auto-create users on first SAML login | | `security.saml2.blockRegistration` | `false` | Block new users (only allow pre-registered) | | `security.saml2.registrationId` | `stirling` | Registration ID (must match ACS URL path) | | `security.saml2.provider` | `null` | Optional provider name for logging | | `security.loginMethod` | `all` | Login method: `all`, `normal`, `oauth2`, `saml2` | Advanced Configuration[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#advanced-configuration "Direct link to Advanced Configuration") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### SAML Attribute Mapping[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#saml-attribute-mapping "Direct link to SAML Attribute Mapping") Stirling PDF attempts to determine the username in the following priority order: 1. **`username`** attribute 2. **`emailaddress`** attribute (or full URI: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`) 3. **`name`** attribute (or full URI: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`) 4. **`upn`** attribute (User Principal Name - often used in Active Directory) 5. **`uid`** attribute (Unix user ID) 6. **NameID** from SAML Subject (fallback if no attributes provided) **Minimum requirement:** NameID in the SAML Subject (used as fallback identifier) **Recommended:** At least one username attribute from the priority list above #### Attribute Debugging[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#attribute-debugging "Direct link to Attribute Debugging") Enable debug logging to see what attributes your IdP is sending: * custom\_settings.yml * Environment Variables Add to `/configs/custom_settings.yml`: logging: level: stirling.software.proprietary.security.saml2: DEBUG LOGGING_LEVEL_STIRLING_SOFTWARE_PROPRIETARY_SECURITY_SAML2=DEBUG Check logs for: Extracted SAML Attributes: {username=[john.doe], emailaddress=[[email protected]], ...} > 💡 **Note**: Currently, Stirling PDF only uses attributes for username identification. Other attributes (first name, last name, groups, roles) are extracted but not used. ### Understanding Registration ID[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#understanding-registration-id "Direct link to Understanding Registration ID") The `registrationId` is a critical configuration value that becomes part of your SAML URLs: security: saml2: registrationId: stirling # Default value With `registrationId: stirling`, your URLs are: * Metadata: `https://your-domain.com/saml2/service-provider-metadata/stirling` * ACS: `https://your-domain.com/login/saml2/sso/stirling` **If you change the registration ID:** security: saml2: registrationId: mycompany # Custom value Your URLs become: * Metadata: `https://your-domain.com/saml2/service-provider-metadata/mycompany` * ACS: `https://your-domain.com/login/saml2/sso/mycompany` > ⚠️ **Critical**: If you change `registrationId` after configuring your IdP, you must update ALL URLs in your IdP configuration. The registration ID must match exactly in all places, or SAML login will fail. > 💡 **Recommendation**: Keep the default `stirling` value unless you have a specific reason to change it (e.g., running multiple Stirling PDF instances with the same IdP). ### Auto-Login Feature[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#auto-login-feature "Direct link to Auto-Login Feature") > **Tier**: Enterprise Automatically redirect users to SAML login, bypassing the Stirling PDF login screen: premium: proFeatures: SSOAutoLogin: true **Auto-login Activation Requirements:** Auto-login only triggers when **ALL** of the following conditions are met: 1. `ssoAutoLogin` is enabled (as configured above) 2. `loginMethod` is NOT `'all'` and NOT `'normal'` (i.e., SSO-only mode required) 3. Exactly one SAML provider is configured **Behavior:** * When all conditions are met: Users are automatically redirected to IdP * When conditions are not met: Standard login page is displayed * After 5 failed login attempts (configurable via `security.loginAttemptCount`), auto-redirect is disabled * Users can still manually access `/login` for form login if `loginMethod: all` Troubleshooting[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#troubleshooting "Direct link to Troubleshooting") -------------------------------------------------------------------------------------------------------------------------------------------- ### "SAML requires Enterprise license"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#saml-requires-enterprise-license "Direct link to "SAML requires Enterprise license"") **Cause**: SAML authentication requires Enterprise tier license. **Solution**: * Verify valid Enterprise license is configured * Check `premium.enabled=true` in settings * Existing users created before license enforcement are grandfathered ### "Invalid SAML response signature"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#invalid-saml-response-signature "Direct link to "Invalid SAML response signature"") **Cause**: IdP certificate mismatch or incorrect format. **Solution**: * Verify `idpCert` file matches certificate from IdP * Ensure certificate is in PEM format (starts with `-----BEGIN CERTIFICATE-----`) * Re-download certificate from IdP * Check certificate hasn't expired ### "ACS URL mismatch"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#acs-url-mismatch "Direct link to "ACS URL mismatch"") **Cause**: Redirect URL doesn't match IdP configuration. **Solution**: * Verify `SYSTEM_BACKENDURL` is set to public HTTPS URL * Check reverse proxy sends X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port headers * Ensure `registrationId` matches in both URL and configuration * Update ACS URL in IdP to match: `https://your-domain.com/login/saml2/sso/stirling` ### "File not found: idp-certificate.pem"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#file-not-found-idp-certificatepem "Direct link to "File not found: idp-certificate.pem"") **Cause**: Certificate file path is incorrect. **Solution**: * Verify file exists at specified path * For Docker: ensure volume is mounted correctly * Use absolute paths like `/configs/filename.pem` (no `file:` prefix) * Check file permissions (must be readable by application) ### "Cannot auto-create user"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#cannot-auto-create-user "Direct link to "Cannot auto-create user"") **Cause**: User doesn't exist and auto-creation is disabled. **Solution**: * Set `autoCreateUser: true` to allow new users * Or pre-create user accounts as admin * Check license allows additional users ### "Redirect loop after SAML login"[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#redirect-loop-after-saml-login "Direct link to "Redirect loop after SAML login"") **Cause**: Session or cookie issues. **Solution**: * Clear browser cookies * Check `SYSTEM_BACKENDURL` matches actual access URL * Verify cookies are allowed for domain * Ensure SameSite cookie settings are compatible ### "Invalid username" error[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#invalid-username-error "Direct link to "Invalid username" error") **Cause**: No valid username found in assertion. **Solution**: 1. Enable debug logging to see what attributes are received 2. Ensure IdP sends at least one of: `username`, `emailaddress`, `name`, `upn`, `uid` 3. Verify NameID is present in SAML Subject as fallback 4. Check attribute name format (short name vs full URI) ### Debug Logging[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#debug-logging "Direct link to Debug Logging") Enable SAML debug logging to see detailed authentication flow: * custom\_settings.yml * Environment Variables Add to `/configs/custom_settings.yml`: logging: level: org.springframework.security.saml2: DEBUG org.opensaml: DEBUG stirling.software.proprietary.security: DEBUG LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_SAML2=DEBUGLOGGING_LEVEL_ORG_OPENSAML=DEBUGLOGGING_LEVEL_STIRLING_SOFTWARE_PROPRIETARY_SECURITY=DEBUG Check logs for SAML attribute information: Extracted SAML Attributes: {username=[john.doe], emailaddress=[[email protected]], ...} ### Inspect SAML Assertions[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#inspect-saml-assertions "Direct link to Inspect SAML Assertions") Use browser developer tools: 1. Open Network tab 2. Clear network log 3. Attempt SAML login 4. Look for POST to `/login/saml2/sso/stirling` 5. Decode SAMLResponse parameter (Base64 + inflate) **Tools:** * [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) (Firefox/Chrome extension) * [SAML Decoder](https://www.samltool.com/decode.php) (online tool) Known Limitations[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#known-limitations "Direct link to Known Limitations") -------------------------------------------------------------------------------------------------------------------------------------------------- ### idpMetadataUri Not Auto-Populating[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#idpmetadatauri-not-auto-populating "Direct link to idpMetadataUri Not Auto-Populating") The `idpMetadataUri` configuration field exists but is **not currently used** to auto-populate IdP settings. You must manually configure: * `idpSingleLoginUrl` * `idpSingleLogoutUrl` * `idpIssuer` * `idpCert` **Workaround**: Manually extract values from IdP metadata XML. > 💡 **Note**: Auto-populating IdP settings from metadata URI is a planned enhancement coming soon. See Also[​](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#see-also "Direct link to See Also") ----------------------------------------------------------------------------------------------------------------------- * [OAuth SSO Configuration](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) - OAuth 2.0 / OIDC setup * [System and Security](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) - Additional security settings * [External Database](https://docs.stirlingpdf.com/Configuration/External%20Database) - User storage configuration * [Paid Offerings](https://docs.stirlingpdf.com/Paid-Offerings) - Enterprise tier and licensing information * [Prerequisites](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#prerequisites) * [Setup Guide](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#setup-guide) * [Step 1: Setup Certificates](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-1-setup-certificates) * [Step 2: Configure Stirling PDF](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-2-configure-stirling-pdf) * [Step 3: Configure Your Identity Provider](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-3-configure-your-identity-provider) * [Step 4: Test SAML Login](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-4-test-saml-login) * [Step 5: Promote SAML User to Admin](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-5-promote-saml-user-to-admin) * [Step 6 (Optional): Switch to SSO-Only Mode](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#step-6-optional-switch-to-sso-only-mode) * [Configuration Reference](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#configuration-reference) * [Required Properties](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#required-properties) * [Optional Properties](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#optional-properties) * [Advanced Configuration](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#advanced-configuration) * [SAML Attribute Mapping](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#saml-attribute-mapping) * [Understanding Registration ID](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#understanding-registration-id) * [Auto-Login Feature](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#auto-login-feature) * [Troubleshooting](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#troubleshooting) * ["SAML requires Enterprise license"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#saml-requires-enterprise-license) * ["Invalid SAML response signature"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#invalid-saml-response-signature) * ["ACS URL mismatch"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#acs-url-mismatch) * ["File not found: idp-certificate.pem"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#file-not-found-idp-certificatepem) * ["Cannot auto-create user"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#cannot-auto-create-user) * ["Redirect loop after SAML login"](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#redirect-loop-after-saml-login) * ["Invalid username" error](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#invalid-username-error) * [Debug Logging](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#debug-logging) * [Inspect SAML Assertions](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#inspect-saml-assertions) * [Known Limitations](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#known-limitations) * [idpMetadataUri Not Auto-Populating](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#idpmetadatauri-not-auto-populating) * [See Also](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/#see-also) --- # Other Customisations | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#__docusaurus_skipToContent_fallback) On this page Stirling PDF offers various other customisation options, such as: ### Defaulting Language[​](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#defaulting-language "Direct link to Defaulting Language") Default language selection via the `SYSTEM_DEFAULTLOCALE` environment variable. Accepted values include `de-DE`, `fr-FR`, `ar-AR` and all other languages codes that are within Stirling PDFs current list. ### Google Search Visibility (robots.txt)[​](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#google-search-visibility-robotstxt "Direct link to Google Search Visibility (robots.txt)") Enable or disable search engine visibility with the `ALLOW_GOOGLE_VISIBILITY` variable. ### Custom Root path[​](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#custom-root-path "Direct link to Custom Root path") Redirect the root path of the application using `APP_ROOT_PATH`. This is for changing websites like stirlingtools.com to instead host the interface at stirlingtools.com/`APP_ROOT_PATH` like stirlingtools.com/demo ### Enable/Disable Analytics[​](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#enabledisable-analytics "Direct link to Enable/Disable Analytics") Analytics can be enabled/disabled with `SYSTEM_ENABLEANALYTICS` or system: enableAnalytics: 'true' In configs/Settings.yml ### Using an outgoing HTTP(S) proxy[​](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#using-an-outgoing-https-proxy "Direct link to Using an outgoing HTTP(S) proxy") To make Stirling PDF use an outgoing proxy server (e.g. for checking the license validity): * Environment Variable * Docker Run * Docker Compose JAVA_CUSTOM_OPTS="-Dhttp.proxyHost=proxyserver -Dhttp.proxyPort=8888 -Dhttp.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local' -Dhttps.proxyHost=proxyserver -Dhttps.proxyPort=8888 -Dhttps.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local'" docker run -d \ -p 8080:8080 \ -e JAVA_CUSTOM_OPTS="-Dhttp.proxyHost=proxyserver -Dhttp.proxyPort=8888 -Dhttp.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local' -Dhttps.proxyHost=proxyserver -Dhttps.proxyPort=8888 -Dhttps.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local'" \ stirlingtools/stirling-pdf:latest services: stirling-pdf: image: stirlingtools/stirling-pdf:latest environment: JAVA_CUSTOM_OPTS: "-Dhttp.proxyHost=proxyserver -Dhttp.proxyPort=8888 -Dhttp.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local' -Dhttps.proxyHost=proxyserver -Dhttps.proxyPort=8888 -Dhttps.nonProxyHosts='localhost|127.0.0.1|127.0.1.1|127.0.0.0/8|::1|10.0.0.0/8|.svc|.cluster.local'" * [Defaulting Language](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#defaulting-language) * [Google Search Visibility (robots.txt)](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#google-search-visibility-robotstxt) * [Custom Root path](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#custom-root-path) * [Enable/Disable Analytics](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#enabledisable-analytics) * [Using an outgoing HTTP(S) proxy](https://docs.stirlingpdf.com/Advanced%20Configuration/Other%20Customisations/#using-an-outgoing-https-proxy) --- # Windows Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF provides Windows compatibility through a downloadable installer depending on your use case! For personal users we recommend the latest [Stirling-PDF-windows-x86\_64.msi](https://files.stirlingpdf.com/win-installer.exe) For Server use (wanting to host Stirling-PDF as a server to share with multiple users) We recommend downloading the server package from [files.stirlingpdf.com](https://files.stirlingpdf.com/Stirling-PDF.jar) (e.g., the latest `Stirling-PDF.jar`) This version also requires you to install the latest [java jdk21](https://www.oracle.com/uk/java/technologies/downloads/#jdk21-windows) you can get the installer [here](https://download.oracle.com/java/21/latest/jdk-21_windows-x64_bin.exe) ### Optional Dependencies[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#optional-dependencies "Direct link to Optional Dependencies") These dependencies enable additional features in Stirling PDF. Install only the ones you need: #### Python and Related Tools[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#python-and-related-tools "Direct link to Python and Related Tools") Python and its related tools enable various features in Stirling PDF: * OpenCV: Enables image scan extraction features * Unoserver: Enables file to PDF conversion features * Python: Required base for OpenCV and other Python-based features 1. Python Installation: * Download Python from [Python's official site](https://www.python.org/downloads/) * During installation, **IMPORTANT**: Check "Add Python to PATH" * Verify installation by opening Command Prompt and running: python --version 2. OpenCV Installation: * After Python is installed, open Command Prompt as administrator * Install OpenCV by running: pip install opencv-python * Verify installation: python -c "import cv2" * Enables Extract Image Scans operation 3. Unoserver Installation: * First install LibreOffice (see LibreOffice section below) * Open Command Prompt as administrator * Install unoserver: pip install unoserver * Verify installation: unoserver --version * Enables File To PDF operation Note: Unoserver requires both Python and LibreOffice to function properly #### QPDF[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#qpdf "Direct link to QPDF") * Download from [QPDF's official site](https://qpdf.sourceforge.io/) * Enables PDF compression and other operations #### LibreOffice[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#libreoffice "Direct link to LibreOffice") * Download and install from [LibreOffice's official site](https://www.libreoffice.org/download/download-libreoffice/) * Enables PDF to DOCX conversion and other document format conversions #### Tesseract OCR[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#tesseract-ocr "Direct link to Tesseract OCR") 1. Download the installer from [UB Mannheim's GitHub](https://github.com/UB-Mannheim/tesseract/wiki) 2. During installation, check additional languages you need 3. Add to settings.yml in your Stirling PDF installation directory: system: tessdataDir: C:\\Program Files\\Tesseract-OCR\\tessdata * Enables OCR functionality for PDFs #### Weasyprint[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#weasyprint "Direct link to Weasyprint") 1. Download from [Weasyprint's releases](https://github.com/Kozea/WeasyPrint/releases) 2. Create a directory (e.g., `c:\weasyprint\`) and place weasyprint.exe there * Enables URL to PDF conversion * Note: Some antivirus software may flag weasyprint.exe - you may need to whitelist it #### PDFtoHTML[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#pdftohtml "Direct link to PDFtoHTML") 1. Download from [SourceForge](https://sourceforge.net/projects/pdftohtml/) 2. Create a directory (e.g., `c:\pdftohtml\`) and place pdftohtml.exe there * Enables PDF to HTML conversion Adding Directories to System PATH[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#adding-directories-to-system-path "Direct link to Adding Directories to System PATH") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- After installing dependencies, you'll need to add their directories to your system's PATH. Here's how: 1. Open Windows Search (Windows key + S) 2. Type "Environment Variables" and click "Edit the system environment variables" 3. Click "Environment Variables" button at the bottom 4. Under "System variables", find and select "Path" 5. Click "Edit" 6. Click "New" to add each required path: * For Python: Should be added automatically during installation if "Add Python to PATH" was checked * For LibreOffice: `C:\Program Files\LibreOffice\program` * For Tesseract: `C:\Program Files\Tesseract-OCR` * For Weasyprint: `C:\weasyprint` (or your chosen directory) * For PDFtoHTML: `C:\pdftohtml` (or your chosen directory) * For QPDF: The installation directory (usually `C:\Program Files\qpdf\bin`) 7. Click "OK" on all windows to save changes Server Installation Steps[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#server-installation-steps "Direct link to Server Installation Steps") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Download the latest Stirling PDF-server.exe or jar from the [releases page](https://github.com/Stirling-Tools/Stirling-PDF/releases/latest) 2. Install any desired optional dependencies following the instructions above 3. Launch the Stirling PDF executable 4. Access the web interface through your browser (the application will provide the URL) in the console logs normally [http://localhost:8080](http://localhost:8080/) Notes[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#notes "Direct link to Notes") ------------------------------------------------------------------------------------------------------------- * The application hosts a web server that is accessible to anyone on your network * If you install multiple Python-based dependencies, ensure they're using the same Python installation to avoid conflicts * Make sure to restart Stirling PDF after installing new dependencies or modifying PATH variables * Some features will be unavailable until their required dependencies are installed Troubleshooting[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------------------------------- 1. Verifying PATH Settings: * Open Command Prompt (cmd) * Type `echo %PATH%` to see all directories in your PATH * For each dependency, try running its command to verify it's accessible: python --versionunoserver --versionpython -c "import cv2"tesseract --version 2. Common Issues: * If changes to PATH don't take effect, try: * Logging out and back in * Restarting your computer * Opening a new Command Prompt window * If a dependency isn't found, double-check the exact path in File Explorer * For Tesseract issues, verify the tessdata directory contains language files * For LibreOffice conversions, ensure no LibreOffice windows are open when converting * For Python/OpenCV issues: * Make sure pip is up to date: `python -m pip install --upgrade pip` * Try installing with administrator privileges * Check if Python is properly added to PATH * For unoserver issues: * Verify both Python and LibreOffice are properly installed * Make sure LibreOffice is in PATH * Try running LibreOffice once before using unoserver Starting unoserver alongside Stirling PDF[​](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#starting-unoserver-alongside-stirling-pdf "Direct link to Starting unoserver alongside Stirling PDF") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command: unoserver --port 2003 --interface 0.0.0.0 You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF. Need help? Visit the [Stirling PDF GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) page. * [Optional Dependencies](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#optional-dependencies) * [Adding Directories to System PATH](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#adding-directories-to-system-path) * [Server Installation Steps](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#server-installation-steps) * [Notes](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#notes) * [Troubleshooting](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#troubleshooting) * [Starting unoserver alongside Stirling PDF](https://docs.stirlingpdf.com/1.5/Installation/Windows%20Installation/#starting-unoserver-alongside-stirling-pdf) --- # Mac Installation Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF can be run on MacOS either by using the `.dmg` installer or directly from the `.jar` file. ### Prerequisites:[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#prerequisites "Direct link to Prerequisites:") * Java 17 or 21 (_21 preferred_) * Install via Homebrew: `brew install openjdk@21` Running via the installer[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#running-via-the-installer "Direct link to Running via the installer") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | [Apple Silicon chips](https://files.stirlingpdf.com/mac-installer.dmg) | [Intel chips](https://files.stirlingpdf.com/mac-x86_64-installer.dmg) | | --- | --- | Download the `.dmg` file and follow the instructions to install the app. A window should pop up allowing you to copy the app to your Applications folder. ![mac-installer.png](https://docs.stirlingpdf.com/assets/images/mac-installer-ccc8bc3bb1c7ee7bbddea1af99aec658.png) The app should now be located in Applications. Head to your Applications folder to open the app. When you open the app for the first time, it will be blocked by MacOS because it has not been officially verified by Apple yet. ![mac-app-blocked.png](https://docs.stirlingpdf.com/assets/images/mac-app-blocked-55a8f08bac7011f4127128c619fcfc15.png) This is only temporary but in the meantime, open System Settings and go to Privacy & Security and then scroll down to the Security section. You should see the same message indicating the app being blocked. Click 'Open Anyway', you may be prompted to enter your password to allow the app. Once you have done this, head back to Applications and open the app again. It should open with no issue this time. ![mac-security-allow.png](https://docs.stirlingpdf.com/assets/images/mac-security-allow-c77bdbbb4ab77f0df5ac46e9c784f659.png) Running via the `.jar` file[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#running-via-the-jar-file "Direct link to running-via-the-jar-file") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Download the `.jar` file [here](https://files.stirlingpdf.com/Stirling-PDF.jar) . 1. Open Terminal 2. Navigate to the folder containing the JAR: cd /path/to/folder/containing/jar 3. Run the JAR file: java -jar Stirling-PDF.jar _For convenience, you can create a simple script:_ 1. Create a file named run-stirling.sh and add the following contents: #!/bin/bash cd /path/to/folder/containing/jarjava -jar Stirling-PDF.jar 2. Make it executable: chmod +x run-stirling.sh 3. Run it with: ./run-stirling.sh ### Optional Dependencies[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#optional-dependencies "Direct link to Optional Dependencies") Install these via [Homebrew](https://brew.sh/) to enable additional features like advanced document conversion or PDF compression: # Install Homebrew if needed/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# Install dependencies as neededbrew install openjdk@21 # Requiredbrew install qpdf # PDF compressionbrew install --cask libreoffice # Document conversionbrew install tesseract # OCR functionalitybrew install tesseract-lang # Additional OCR languagesbrew install poppler # PDF to HTML conversionpip3 install weasyprint # URL to PDF conversionpip3 install unoserver # File to PDF conversion For Tesseract OCR, add to `config/settings.yml` (generated once you first run the jar): system: tessdataDir: /usr/local/share/tessdata Quick Troubleshooting[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#quick-troubleshooting "Direct link to Quick Troubleshooting") --------------------------------------------------------------------------------------------------------------------------------------------------------- * Java not found? Add to `~/.zshrc`: export PATH="/usr/local/opt/openjdk@21/bin:$PATH" * Verify installations with: `[command] --version` (e.g., `java --version`) * LibreOffice issues? Ensure no LibreOffice processes are running * Need help? Visit [GitHub Issues](https://github.com/Stirling-Tools/Stirling-PDF/issues) ### Starting unoserver alongside Stirling PDF[​](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#starting-unoserver-alongside-stirling-pdf "Direct link to Starting unoserver alongside Stirling PDF") To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command: unoserver --port 2003 --interface 0.0.0.0 You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF. * [Prerequisites:](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#prerequisites) * [Running via the installer](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#running-via-the-installer) * [Running via the `.jar` file](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#running-via-the-jar-file) * [Optional Dependencies](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#optional-dependencies) * [Quick Troubleshooting](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#quick-troubleshooting) * [Starting unoserver alongside Stirling PDF](https://docs.stirlingpdf.com/1.5/Installation/Mac%20Installation/#starting-unoserver-alongside-stirling-pdf) --- # Docker Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page The docker image for Stirling-PDF is available on Docker Hub at [stirlingtools/stirling-pdf](https://hub.docker.com/r/stirlingtools/stirling-pdf) or on Github at [stirling-pdf](https://github.com/Stirling-Tools/Stirling-PDF/pkgs/container/stirling-pdf) . Please note that Stirling PDF offers three distinct versions tailored for various hardware configurations. Users seeking optimal performance on lower-end hardware can choose from the specific versions provided. For those who prefer the most recent features and updates, it is recommended to continue using the latest tag. | Version | Latest Tag | | --- | --- | | Fat | `latest-fat` | | Standard | `latest` | | Ultra Lite | `latest-ultra-lite` | ### Run docker container with `docker run`[​](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#run-docker-container-with-docker-run "Direct link to run-docker-container-with-docker-run") docker run -d \ --name stirling-pdf \ -p 8080:8080 \ -v "./StirlingPDF/trainingData:/usr/share/tessdata" \ -v "./StirlingPDF/extraConfigs:/configs" \ -v "./StirlingPDF/customFiles:/customFiles/" \ -v "./StirlingPDF/logs:/logs/" \ -v "./StirlingPDF/pipeline:/pipeline/" \ -e DISABLE_ADDITIONAL_FEATURES=true \ -e LANGS=en_GB \ docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest ### Run docker container with `docker compose`[​](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#run-docker-container-with-docker-compose "Direct link to run-docker-container-with-docker-compose") * `docker-compose.yml` services: stirling-pdf: image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest ports: - '8080:8080' volumes: - ./StirlingPDF/trainingData:/usr/share/tessdata # Required for extra OCR languages - ./StirlingPDF/extraConfigs:/configs - ./StirlingPDF/customFiles:/customFiles/ - ./StirlingPDF/logs:/logs/ - ./StirlingPDF/pipeline:/pipeline/ environment: - DISABLE_ADDITIONAL_FEATURES=false - LANGS=en_GB ### Extras[​](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#extras "Direct link to Extras") For extra parameters and customization please check the [advanced configuration](https://docs.stirlingpdf.com/Advanced%20Configuration/How%20to%20add%20configurations) page! * [Run docker container with `docker run`](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#run-docker-container-with-docker-run) * [Run docker container with `docker compose`](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#run-docker-container-with-docker-compose) * [Extras](https://docs.stirlingpdf.com/1.5/Installation/Docker%20Install/#extras) --- # Unix Installation Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page To run the application without Docker/Podman, you will need to manually install all dependencies and build the necessary components. Note that some dependencies might not be available in the standard repositories of all Linux distributions, and may require additional steps to install. The following guide assumes you have a basic understanding of using a command line interface in your operating system. It should work on most Linux distributions and MacOS. For Windows, you might need to use Windows Subsystem for Linux (WSL) for certain steps. The amount of dependencies is to actually reduce overall size, ie installing LibreOffice sub components rather than full LibreOffice package. You could theoretically use a Distrobox/Toolbox, if your Distribution has old or not all Packages. But you might just as well use the Docker Container then. ### Step 1: Prerequisites[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-1-prerequisites "Direct link to Step 1: Prerequisites") Install the following software, if not already installed: * Java 17 or later (21 recommended) * Gradle 7.0 or later (included within repo so not needed on server) * Git * Python 3.8 (with pip) * Make * GCC/G++ * Automake * Autoconf * libtool * pkg-config * zlib1g-dev * libleptonica-dev * Debian-based Systems * Fedora-based Systems * Nix Package Manager sudo apt-get updatesudo apt-get install -y git automake autoconf libtool \ libleptonica-dev pkg-config zlib1g-dev make g++ \ openjdk-21-jdk python3 python3-pip sudo dnf install -y git automake autoconf libtool \ leptonica-devel pkg-config zlib-devel make gcc-c++ \ java-21-openjdk python3 python3-pip nix-channel --updatenix-env -iA nixpkgs.jdk21 nixpkgs.git nixpkgs.python38 \ nixpkgs.gnumake nixpkgs.libgcc nixpkgs.automake \ nixpkgs.autoconf nixpkgs.libtool nixpkgs.pkg-config \ nixpkgs.zlib nixpkgs.leptonica ### Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-2-clone-and-build-jbig2enc-only-required-for-certain-ocr-functionality "Direct link to Step 2: Clone and Build jbig2enc (Only required for certain OCR functionality)") * Debian * Fedora * Nix Package Manager mkdir ~/.gitcd ~/.git &&\git clone https://github.com/agl/jbig2enc.git &&\cd jbig2enc &&\./autogen.sh &&\./configure &&\make &&\sudo make install mkdir ~/.gitcd ~/.git &&\git clone https://github.com/agl/jbig2enc.git &&\cd jbig2enc &&\./autogen.sh &&\./configure &&\make &&\sudo make install nix-env -iA nixpkgs.jbig2enc ### Step 3: Install Additional Software[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-3-install-additional-software "Direct link to Step 3: Install Additional Software") Next we need to install LibreOffice for conversions, tesseract for OCR, and opencv for pattern recognition functionality. Install the following software: * libreoffice (libreoffice-core libreoffice-common libreoffice-writer libreoffice-calc libreoffice-impress) * python3-uno * unoserver * pngquant * tesseract * opencv-python-headless * Debian-based Systems * Fedora-based Systems * Nix Package Manager sudo apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseractpip3 install uno opencv-python-headless unoserver pngquant WeasyPrint --break-system-packages sudo dnf install -y libreoffice-writer libreoffice-calc libreoffice-impress tesseractpip3 install uno opencv-python-headless unoserver pngquant WeasyPrint nix-env -iA nixpkgs.libreoffice nixpkgs.tesseract nixpkgs.poppler_utilspip3 install uno opencv-python-headless unoserver pngquant WeasyPrint ### Step 4: Grab latest Stirling-PDF Jar[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-4-grab-latest-stirling-pdf-jar "Direct link to Step 4: Grab latest Stirling-PDF Jar") The JAR can be downloaded in two versions, [normal](https://files.stirlingpdf.com/Stirling-PDF.jar) and [security](https://files.stirlingpdf.com/Stirling-PDF-with-login.jar) ### Step 5: Move jar to desired location[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-5-move-jar-to-desired-location "Direct link to Step 5: Move jar to desired location") You can move this file to a desired location, for example, `/opt/Stirling-PDF/`. You must also move the Script folder within the Stirling-PDF repo that you have downloaded to this directory. This folder is required for the python scripts using OpenCV. * Debian (Root) * Fedora (Root) * Nix (Non-root) sudo mkdir /opt/Stirling-PDF &&\sudo mv ./build/libs/Stirling-PDF-*.jar /opt/Stirling-PDF/ &&\sudo mv scripts /opt/Stirling-PDF/ &&\echo "Scripts installed." sudo mkdir /opt/Stirling-PDF &&\sudo mv ./build/libs/Stirling-PDF-*.jar /opt/Stirling-PDF/ &&\sudo mv scripts /opt/Stirling-PDF/ &&\echo "Scripts installed." mv ./build/libs/Stirling-PDF-*.jar ./Stirling-PDF-*.jar ### Step 6: OCR Language Support[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-6-ocr-language-support "Direct link to Step 6: OCR Language Support") If you plan to use the OCR (Optical Character Recognition) functionality, you might need to install language packs for Tesseract if running non-english scanning. * Debian-based Systems * Fedora-based Systems * Nix Package Manager * Manual Installation 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' # 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' nix-env -iA nixpkgs.tesseract Note: Nix Package Manager pre-installs almost all the language packs when tesseract is installed. 1. Download the desired language pack(s) by selecting the `.traineddata` file(s) for the language(s) you need. 2. Place the `.traineddata` files in the Tesseract tessdata directory: `/usr/share/tessdata` 3. Please view [tesseract install guide](https://tesseract.readthedocs.io/en/latest/installation.html) for more info. **IMPORTANT:** DO NOT REMOVE EXISTING `eng.traineddata`, IT'S REQUIRED. ### Step 7: Run Stirling-PDF[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-7-run-stirling-pdf "Direct link to Step 7: Run Stirling-PDF") * Debian-based Systems * Fedora-based Systems * Nix Package Manager java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar java -jar /opt/Stirling-PDF/Stirling-PDF-*.jar Since libreoffice, soffice, and conversion tools have their dbus\_tmp\_dir set as `dbus_tmp_dir="/run/user/$(id -u)/libreoffice-dbus"`, you get the following error: `[Thread-7] INFO s.s.SPDF.utils.ProcessExecutor - mkdir: cannot create directory '/run/user/1501': Permission denied` To resolve this, use: `bash mkdir temp export DBUS_SESSION_BUS_ADDRESS="unix:path=./temp"` ### Step 8: Adding a Desktop Icon[​](https://docs.stirlingpdf.com/1.5/Installation/Unix%20Installation/#step-8-adding-a-desktop-icon "Direct link to Step 8: Adding a Desktop Icon") This will add a modified Appstarter to your Appmenu. location=$(pwd)/gradlewimage=$(pwd)/docs/stirling-transparent.svgcat > ~/.local/share/applications/Stirling-PDF.desktop < `sign` * `validate-signature`: Verify digital signatures and certificates in PDF documents, checking against custom certificate files * `remove-cert-sign`: Removes digital signatures from any inputted PDF * `sanitize-pdf`: This allows the user to remove various things within the PDF which may cause security concern such as javascript, files, links, fonts and metadata. * `auto-redact`: This features lets the user input text (or regex) to be redacted/blacked out from the pdf document. * `get-info-on-pdf`: This grabs all info on a PDF such as version, font types, width height and any and all information it can find and puts it within a formatted JSON doc (or visual tables within UI) --- # Versions | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Versions/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF is available in several formats, each catering to different needs and use cases: Docker Versions[​](https://docs.stirlingpdf.com/1.5/Installation/Versions/#docker-versions "Direct link to Docker Versions") ----------------------------------------------------------------------------------------------------------------------------- For server deployments, we offer three pre-configured Docker images: * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest-fat?label=Stirling-PDF%20Fat) * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest?label=Stirling-PDF%20Full) * ![Docker Image Size (tag)](https://img.shields.io/docker/image-size/stirlingtools/stirling-pdf/latest-ultra-lite?label=Stirling-PDF%20Ultra-Lite) * **Fat**: Includes all Full features plus additional fonts and pre-bundled jar security version * **Full**: All features pre-configured and ready to use * **Ultra-Lite**: Minimal installation with core features only Desktop Versions (Windows & Unix)[​](https://docs.stirlingpdf.com/1.5/Installation/Versions/#desktop-versions-windows--unix "Direct link to Desktop Versions (Windows & Unix)") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The desktop versions of Stirling PDF use a dynamic feature system. They start with Ultra-Lite features as the base and automatically enable additional functionality based on installed dependencies: Base Features (Ultra-Lite): * Core PDF operations (merge, split, rotate, etc.) * Basic conversions * Password protection * All features marked with ✔️ in the Ultra-Lite column below Additional features become available automatically when you install: * LibreOffice: Enables document format conversions (PDF to Word, Excel, etc.) * Tesseract: Enables OCR functionality * QPDF: Enables compression and repair features * Other dependencies: Enable their respective features Feature Comparison[​](https://docs.stirlingpdf.com/1.5/Installation/Versions/#feature-comparison "Direct link to Feature Comparison") -------------------------------------------------------------------------------------------------------------------------------------- Here are the different technologies each version uses: | Technology | Ultra-Lite | Full | | --- | --- | --- | | Java | ✔️ | ✔️ | | JavaScript | ✔️ | ✔️ | | Libre | | ✔️ | | Python | | ✔️ | | OpenCV | | ✔️ | | Tesseract | | ✔️ | And here you see what functions are offered as part of each. | Operation | Ultra-Lite | Full | | --- | --- | --- | | add-page-numbers | ✔️ | ✔️ | | add-password | ✔️ | ✔️ | | add-image | ✔️ | ✔️ | | add-watermark | ✔️ | ✔️ | | adjust-contrast | ✔️ | ✔️ | | auto-split-pdf | ✔️ | ✔️ | | auto-redact | ✔️ | ✔️ | | auto-rename | ✔️ | ✔️ | | cert-sign | ✔️ | ✔️ | | crop | ✔️ | ✔️ | | change-metadata | ✔️ | ✔️ | | change-permissions | ✔️ | ✔️ | | compare | ✔️ | ✔️ | | extract-page | ✔️ | ✔️ | | extract-images | ✔️ | ✔️ | | flatten | ✔️ | ✔️ | | get-info-on-pdf | ✔️ | ✔️ | | img-to-pdf | ✔️ | ✔️ | | markdown-to-pdf | ✔️ | ✔️ | | merge-pdfs | ✔️ | ✔️ | | multi-page-layout | ✔️ | ✔️ | | overlay-pdf | ✔️ | ✔️ | | pdf-organizer | ✔️ | ✔️ | | pdf-to-csv | ✔️ | ✔️ | | pdf-to-img | ✔️ | ✔️ | | pdf-to-single-page | ✔️ | ✔️ | | remove-blanks | ✔️ | ✔️ | | remove-pages | ✔️ | ✔️ | | remove-password | ✔️ | ✔️ | | rotate-pdf | ✔️ | ✔️ | | sanitize-pdf | ✔️ | ✔️ | | scale-pages | ✔️ | ✔️ | | sign | ✔️ | ✔️ | | show-javascript | ✔️ | ✔️ | | split-by-size-or-count | ✔️ | ✔️ | | split-pdf-by-sections | ✔️ | ✔️ | | split-pdfs | ✔️ | ✔️ | | compress-pdf | | ✔️ | | extract-image-scans | | ✔️ | | ocr-pdf | | ✔️ | | pdf-to-pdfa | | ✔️ | | pdf-to-text | ✔️ | ✔️ | | pdf-to-html | | ✔️ | | pdf-to-word | | ✔️ | | pdf-to-presentation | | ✔️ | | pdf-to-xml | | ✔️ | | remove-annotations | ✔️ | ✔️ | | remove-cert-sign | ✔️ | ✔️ | | remove-image-pdf | ✔️ | ✔️ | | file-to-pdf | | ✔️ | | xlsx-to-pdf | | ✔️ | | html-to-pdf | | ✔️ | | url-to-pdf | | ✔️ | | repair | | ✔️ | * [Docker Versions](https://docs.stirlingpdf.com/1.5/Installation/Versions/#docker-versions) * [Desktop Versions (Windows & Unix)](https://docs.stirlingpdf.com/1.5/Installation/Versions/#desktop-versions-windows--unix) * [Feature Comparison](https://docs.stirlingpdf.com/1.5/Installation/Versions/#feature-comparison) --- # One doc tagged with "API" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/api/#__docusaurus_skipToContent_fallback) [API\ ---](https://docs.stirlingpdf.com/1.5/API) Overview of API offering in S-PDF --- # One doc tagged with "Premium" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/premium/#__docusaurus_skipToContent_fallback) [Pro / Enterprise\ ----------------](https://docs.stirlingpdf.com/1.5/Pro) Enterprise/Pro edition for stirling PDF --- # 5 docs tagged with "pro" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/pro/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE) Tier: Pro, Enterprise [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker) Tier: Pro, Enterprise [Pro / Enterprise\ ----------------](https://docs.stirlingpdf.com/1.5/Pro) Enterprise/Pro edition for stirling PDF [Single Sign-On (SSO) Configuration\ ----------------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) Tier: Pro, Enterprise [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring) Tier: Pro, Enterprise --- # 6 docs tagged with "enterprise" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/enterprise/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE) Tier: Pro, Enterprise [External Database\ -----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database) Tier: Enterprise [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker) Tier: Pro, Enterprise [Pro / Enterprise\ ----------------](https://docs.stirlingpdf.com/1.5/Pro) Enterprise/Pro edition for stirling PDF [Single Sign-On (SSO) Configuration\ ----------------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) Tier: Pro, Enterprise [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring) Tier: Pro, Enterprise --- # Features - Pipeline | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page The Pipeline feature in Stirling PDF enables automated, sequential processing of PDFs through multiple operations. This powerful automation tool allows you to: * `create-pipeline`: Create custom workflows combining multiple PDF operations into a single automated process. For example, you could create a pipeline that: * Splits a PDF * Adds watermarks to each part * Compresses the results * All in one automated sequence * `save-pipeline`: Save pipeline configurations for future use, share them with others, or use them in automated folder scanning processes * `folder-scanning`: Set up automated processing of files in watched folders using your pipeline configurations. The system will automatically process any files placed in these folders according to your pipeline rules Additional Features[​](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline/#additional-features "Direct link to Additional Features") ----------------------------------------------------------------------------------------------------------------------------------------------------- * Web UI configuration interface for easy pipeline setup * JSON-based configuration for advanced users * Support for multiple pipeline configurations * Automatic unzipping of intermediate results * Error handling and validation * Ability to save and load pipeline configurations For detailed information on setting up and using pipelines, see: * [Pipeline Configuration Guide](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline) * [Folder Scanning Guide](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning) Current Limitations[​](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline/#current-limitations "Direct link to Current Limitations") ----------------------------------------------------------------------------------------------------------------------------------------------------- * Cannot have multiple instances of the same operation in a single pipeline * Web UI does not support operations requiring multiple different types of inputs * Files and operations run in serial mode * Additional file inputs during processing are not supported via UI * [Additional Features](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline/#additional-features) * [Current Limitations](https://docs.stirlingpdf.com/1.5/Functionality/Features%20Pipeline/#current-limitations) --- # Other Customisations | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF offers various other customisation options, such as: ### Defaulting Language[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#defaulting-language "Direct link to Defaulting Language") Default language selection via the `SYSTEM_DEFAULTLOCALE` environment variable. Accepted values include `de-DE`, `fr-FR`, `ar-AR` and all other languages codes that are within Stirling-PDFs current list. ### Google Search Visibility (robots.txt)[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#google-search-visibility-robotstxt "Direct link to Google Search Visibility (robots.txt)") Enable or disable search engine visibility with the `ALLOW_GOOGLE_VISIBILITY` variable. ### Custom Root path[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#custom-root-path "Direct link to Custom Root path") Redirect the root path of the application using `APP_ROOT_PATH`. This is for changing websites like stirlingtools.com to instead host the interface at stirlingtools.com/`APP_ROOT_PATH` like stirlingtools.com/demo ### Enable/Disable Analytics[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#enabledisable-analytics "Direct link to Enable/Disable Analytics") Analytics can be enabled/disabled with `SYSTEM_ENABLEANALYTICS` or system: enableAnalytics: 'true' In configs/Settings.yml * [Defaulting Language](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#defaulting-language) * [Google Search Visibility (robots.txt)](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#google-search-visibility-robotstxt) * [Custom Root path](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#custom-root-path) * [Enable/Disable Analytics](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Other%20Customisations/#enabledisable-analytics) --- # How to add Configurations | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF allows easy customization of the app. Includes things like * Custom application name * Custom slogans, icons, HTML, images CSS etc (via file overrides) There are two options for this, either using the generated settings file `settings.yml` This file is located in the `/configs` directory and follows standard YAML formatting Environment variables are also supported and would override the settings file For example in the settings.yml you have security: enableLogin: 'true' To have this via an environment variable you would have `SECURITY_ENABLELOGIN` The Current list of settings is security: enableLogin: false # set to 'true' to enable login csrfDisabled: false # set to 'true' to disable CSRF protection (not recommended for production) loginAttemptCount: 5 # lock user account after 5 tries; when using e.g. Fail2Ban you can deactivate the function with -1 loginResetTimeMinutes: 120 # lock account for 2 hours after x attempts loginMethod: all # Accepts values like 'all' and 'normal'(only Login with Username/Password), 'oauth2'(only Login with OAuth2) or 'saml2'(only Login with SAML2) initialLogin: username: '' # initial username for the first login password: '' # initial password for the first login oauth2: enabled: false # set to 'true' to enable login (Note: enableLogin must also be 'true' for this to work) client: keycloak: issuer: '' # URL of the Keycloak realm's OpenID Connect Discovery endpoint clientId: '' # client ID for Keycloak OAuth2 clientSecret: '' # client secret for Keycloak OAuth2 scopes: openid, profile, email # scopes for Keycloak OAuth2 useAsUsername: preferred_username # field to use as the username for Keycloak OAuth2. Available options are: [email | name | given_name | family_name | preferred_name] google: clientId: '' # client ID for Google OAuth2 clientSecret: '' # client secret for Google OAuth2 scopes: email, profile # scopes for Google OAuth2 useAsUsername: email # field to use as the username for Google OAuth2. Available options are: [email | name | given_name | family_name] github: clientId: '' # client ID for GitHub OAuth2 clientSecret: '' # client secret for GitHub OAuth2 scopes: read:user # scope for GitHub OAuth2 useAsUsername: login # field to use as the username for GitHub OAuth2. Available options are: [email | login | name] issuer: '' # set to any Provider that supports OpenID Connect Discovery (/.well-known/openid-configuration) endpoint clientId: '' # client ID from your Provider clientSecret: '' # client secret from your Provider autoCreateUser: true # set to 'true' to allow auto-creation of non-existing users blockRegistration: false # set to 'true' to deny login with SSO without prior registration by an admin useAsUsername: email # default is 'email'; custom fields can be used as the username scopes: openid, profile, email # specify the scopes for which the application will request permissions provider: google # set this to your OAuth Provider's name, e.g., 'google' or 'keycloak' saml2: enabled: false # Only enabled for paid enterprise clients (enterpriseEdition.enabled must be true) provider: '' # The name of your Provider autoCreateUser: true # set to 'true' to allow auto-creation of non-existing users blockRegistration: false # set to 'true' to deny login with SSO without prior registration by an admin registrationId: stirling # The name of your Service Provider (SP) app name. Should match the name in the path for your SSO & SLO URLs idpMetadataUri: https://dev-XXXXXXXX.okta.com/app/externalKey/sso/saml/metadata # The uri for your Provider's metadata idpSingleLoginUrl: https://dev-XXXXXXXX.okta.com/app/dev-XXXXXXXX_stirlingpdf_1/externalKey/sso/saml # The URL for initiating SSO. Provided by your Provider idpSingleLogoutUrl: https://dev-XXXXXXXX.okta.com/app/dev-XXXXXXXX_stirlingpdf_1/externalKey/slo/saml # The URL for initiating SLO. Provided by your Provider idpIssuer: '' # The ID of your Provider idpCert: classpath:okta.cert # The certificate your Provider will use to authenticate your app's SAML authentication requests. Provided by your Provider privateKey: classpath:saml-private-key.key # Your private key. Generated from your keypair spCert: classpath:saml-public-cert.crt # Your signing certificate. Generated from your keypairpremium: key: 00000000-0000-0000-0000-000000000000 enabled: false # Enable license key checks for pro/enterprise features proFeatures: SSOAutoLogin: false CustomMetadata: autoUpdateMetadata: false author: username creator: Stirling-PDF producer: Stirling-PDF googleDrive: enabled: false clientId: '' apiKey: '' appId: ''legal: termsAndConditions: https://www.stirlingpdf.com/terms-and-conditions # URL to the terms and conditions of your application (e.g. https://example.com/terms). Empty string to disable or filename to load from local file in static folder privacyPolicy: https://www.stirlingpdf.com/privacy-policy # URL to the privacy policy of your application (e.g. https://example.com/privacy). Empty string to disable or filename to load from local file in static folder accessibilityStatement: '' # URL to the accessibility statement of your application (e.g. https://example.com/accessibility). Empty string to disable or filename to load from local file in static folder cookiePolicy: '' # URL to the cookie policy of your application (e.g. https://example.com/cookie). Empty string to disable or filename to load from local file in static folder impressum: '' # URL to the impressum of your application (e.g. https://example.com/impressum). Empty string to disable or filename to load from local file in static foldersystem: 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 enableAlphaFunctionality: false # set to enable functionality which might need more testing before it fully goes live (this feature might make no changes) showUpdate: false # see when a new update is available showUpdateOnlyAdmin: false # only admins can see when a new update is available, depending on showUpdate it must be set to 'true' customHTMLFiles: false # enable to have files placed in /customFiles/templates override the existing template HTML files tessdataDir: /usr/share/tessdata # path to the directory containing the Tessdata files. This setting is relevant for Windows systems. For Windows users, this path should be adjusted to point to the appropriate directory where the Tessdata files are stored. enableAnalytics: null # set to 'true' to enable analytics, set to 'false' to disable analytics; for enterprise users, this is set to true enableUrlToPDF: false # Set to 'true' to enable URL to PDF, INTERNAL ONLY, known security issues, should not be used externally disableSanitize: false # set to true to disable Sanitize HTML; (can lead to injections in HTML) datasource: enableCustomDatabase: false # Enterprise users ONLY, set this property to 'true' if you would like to use your own custom database configuration customDatabaseUrl: '' # eg jdbc:postgresql://localhost:5432/postgres, set the url for your own custom database connection. If provided, the type, hostName, port and name are not necessary and will not be used username: postgres # set the database username password: postgres # set the database password type: postgresql # the type of the database to set (e.g. 'h2', 'postgresql') hostName: localhost # the host name to use for the database url. Set to 'localhost' when running the app locally. Set to match the name of the container name of your database container when running the app on a server (Docker configuration) port: 5432 # set the port number of the database. Ensure this matches the port the database is listening to name: postgres # set the name of your database. Should match the name of the database you create 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 fileUploadLimit: '' # Defaults to "". No limit when string is empty. Set a number, between 0 and 999, followed by one of the following strings to set a limit. "KB", "MB", "GB".ui: appName: '' # application's visible name homeDescription: '' # short description or tagline shown on the homepage appNameNavbar: '' # name displayed on the navigation bar languages: [] # If empty, all languages are enabled. To display only German and Polish ["de_DE", "pl_PL"]. British English is always enabled.endpoints: toRemove: [] # list endpoints to disable (e.g. ['img-to-pdf', 'remove-pages']) groupsToRemove: [] # list groups to disable (e.g. ['LibreOffice'])metrics: enabled: true # 'true' to enable Info APIs (`/api/*`) endpoints, 'false' to disableprocessExecutor: sessionLimit: # Process executor instances limits libreOfficeSessionLimit: 1 pdfToHtmlSessionLimit: 1 qpdfSessionLimit: 4 tesseractSessionLimit: 1 pythonOpenCvSessionLimit: 8 weasyPrintSessionLimit: 16 installAppSessionLimit: 1 calibreSessionLimit: 1 timeoutMinutes: # Process executor timeout in minutes libreOfficetimeoutMinutes: 30 pdfToHtmltimeoutMinutes: 20 pythonOpenCvtimeoutMinutes: 30 weasyPrinttimeoutMinutes: 30 installApptimeoutMinutes: 60 calibretimeoutMinutes: 30 tesseractTimeoutMinutes: 30 There is an additional config file `/configs/custom_settings.yml` where users familiar with java and spring application.properties can input their own settings on-top of Stirling-PDFs existing ones. For more info on any custom settings such as SSL or DEBUG mode please check [here](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings) #### Extra notes[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#extra-notes "Direct link to Extra notes") * Endpoints. Currently, the endpoints ENDPOINTS\_TOREMOVE and ENDPOINTS\_GROUPSTOREMOVE can include comma separate lists of endpoints and groups to disable as example ENDPOINTS\_TOREMOVE=img-to-pdf,remove-pages would disable both image-to-pdf and remove pages, ENDPOINTS\_GROUPSTOREMOVE=LibreOffice Would disable all things that use LibreOffice. * customStaticFilePath. Customise static files such as the app logo by placing files in the /customFiles/static/ directory. An example of customising app logo is placing a /customFiles/static/favicon.svg to override current SVG. This can be used to change any images/icons/css/fonts/js etc in Stirling-PDF ### Environment only parameters[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#environment-only-parameters "Direct link to Environment only parameters") * `SYSTEM_ROOTURIPATH` ie set to `/pdf-app` to Set the application's root URI to `localhost:8080/pdf-app` * `SYSTEM_CONNECTIONTIMEOUTMINUTES` to set custom connection timeout values * `DISABLE_ADDITIONAL_FEATURES` to tell docker to download security jar (required as false for auth login and pro features) * `DISABLE_PIXEL` `true` or `false` to disable pixel * `LANGS` to define custom font libraries to install for use for document conversions ### Local[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#local "Direct link to Local") If running Java directly outside of docker, you can set these environment variables before starting the app: * Unix * Windows (CMD) * Windows (PowerShell) export UI_APPNAME="Stirling PDF" set UI_APPNAME=Stirling PDF $env:UI_APPNAME = "Stirling PDF" Docker Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#docker-configuration "Direct link to Docker Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If using Docker, you can set environment variables via either Docker run or Docker Compose as part of your installation. Simply add these to the end of your script/file: * Docker Run * Docker Compose -e "UI_APPNAME=Stirling PDF" \-e "UI_HOMEDESCRIPTION=Your locally hosted one-stop-shop for all your PDF needs." \-e "UI_APPNAVBARNAME=Stirling PDF" \ environment: UI_APPNAME: Stirling PDF UI_HOMEDESCRIPTION: Your locally hosted one-stop-shop for all your PDF needs. UI_APPNAVBARNAME: Stirling PDF * [Environment only parameters](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#environment-only-parameters) * [Local](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#local) * [Docker Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/How%20to%20add%20configurations/#docker-configuration) --- # External Database | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > **Tier**: Enterprise It is possible to use your own external database with Stirling PDF rather than the default H2 database if you wish. PostgreSQL is currently the only supported variant, others will be added on request. ### Setting Up External Database Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database/#setting-up-external-database-configuration "Direct link to Setting Up External Database Configuration") You can configure the new `Datasource` property in your `settings.yml` to connect to your external database: > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _To use the external database feature, you will need to have a valid enterprise license and set the environment variable `DISABLE_ADDITIONAL_FEATURES` to `false`._ * Settings File * Docker Compose datasource: enableCustomDatabase: false customDatabaseUrl: jdbc:postgresql://localhost:5432/postgres username: postgres password: postgres type: postgresql hostName: localhost port: 5432 name: postgres * `enableCustomDatabase`: Set this property to `true` to enable use of the custom database **Note: An enterprise license to use this feature** * `customDatabaseUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabaseUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** * `username`: The username for the database * `password`: The password for the database If you would like more fine-grained control of the database connection, you can also use the following properties: #### Fine-grained Database Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database/#fine-grained-database-configuration "Direct link to Fine-grained Database Configuration") * `type`: The database type. Available options are `h2` and `postgresql` * `hostName`: The host name of the database connection url (e.g. 'localhost') * `port`: The port number of the database connection url (e.g. 8080) * `name`: The name of the custom database. This should match the name you have set for your database services: db: image: 'postgres:17.2-alpine' container_name: db ports: - "5432:5432" environment: POSTGRES_DB: "stirling_pdf" POSTGRES_USER: "admin" POSTGRES_PASSWORD: "stirling" * `container_name`: This is the name of your database container. This should match the name of the container under `services` as this is what Docker will use to refer to your database * `ports`: Specify the port number for your database. The number on the left is the port number the container will access the database internally. The number on the right is the port number the Stirling PDF app will use to connect to the database externally. Ensure this matches the port number in the connection url for your database otherwise the app will not be able to access it. * `POSTGRES_DB`: An environment variable for the database container. Specify the name of the custom database here * `POSTGRES_USER`: An environment variable for the database container. Specify the username for the database * `POSTGRES_PASSWORD`: An environment variable for the database container. Specify the password for the database You will also need to update the Docker configuration in your app in order to connect to the database: services: stirling-pdf: depends_on: - db environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration * `depends_on`: This specifies any services that your app will need in order to run. Ensure the name matches the container name for your database * `DISABLE_ADDITIONAL_FEATURES`: Set this to `false` to enable security features * `SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE`: An environment variable to connect to the database container. Set this to `true` to enable use of the external database * `SYSTEM_DATASOURCE_CUSTOMDATABASEURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** * `SYSTEM_DATASOURCE_USERNAME`: An environment variable to connect to the database container. Set the username for the database. Ensure this matches the corresponding property in your database container * `SYSTEM_DATASOURCE_PASSWORD`: An environment variable to connect to the database container. Set the password for the database. Ensure this matches the corresponding property in your database container Below is an example of what your configuration should look like after configuring the custom database: services: stirling-pdf: depends_on: - db environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration db: image: 'postgres:17.2-alpine' container_name: db ports: - "5432:5432" environment: POSTGRES_DB: "stirling_pdf" POSTGRES_USER: "admin" POSTGRES_PASSWORD: "stirling" _Example configuration can be found in [exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml](https://github.com/Stirling-Tools/Stirling-PDF/blob/428b4238e3a7280d71697d994a66174a250387a7/exampleYmlFiles/docker-compose-latest-fat-security-postgres.yml) _ * [Setting Up External Database Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database/#setting-up-external-database-configuration) --- # Single Sign-On (SSO) Configuration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > **Tier**: Pro, Enterprise Stirling-PDF allows login via Single Sign-On (SSO) using OAuth 2 OpenID Connect (OIDC) and SAML 2. This allows you to log in to the app using an account you may have with another Provider such as Google or GitHub. OAuth 2 Set Up[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#oauth-2-set-up "Direct link to OAuth 2 Set Up") -------------------------------------------------------------------------------------------------------------------------------------------------------------- To enable OAuth 2 in Stirling-PDF there are a number of properties you must set. Begin by setting `security.enableLogin` to `true` and `security.loginMethod` to `oauth2` in your `/configs/settings.yml`. security: enableLogin: true ... loginMethod: all | normal | oauth2 | saml2 * `enableLogin`: Set to `true` to enable login * `loginMethod`: Defines the type of login method that will be used on application start up. The available options are: * `all`: Enables all login methods (username/password, OAuth 2, SAML 2). Can be used alternatively to `oauth2` * `normal`: Enables the username/password login method * `oauth2`: Enables the OAuth 2 login method. Use this if you only want to log in via OAuth 2 * `saml2`: Enables the SAML 2 login method Next, you will need to configure the OAuth 2 properties for your chosen Provider. Start by setting `security.oauth2.enabled` to `true`. Stirling-PDF supports multiple Providers, in particular [Google](https://console.cloud.google.com/) , [GitHub](https://github.com/settings/developers) and [Keycloak](https://www.keycloak.org/) . You also have the option to use a different Provider apart from the aforementioned if you wish. > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _The `enableLogin` property must be set to `true` for SSO to work._ * Google * GitHub * Keycloak * Other oauth2: enabled: true client: google: clientId: clientSecret: scopes: email, profile useAsUsername: email | name | given_name | family_name provider: google oauth2: enabled: true client: github: clientId: clientSecret: scopes: read:user useAsUsername: email | login | name provider: github oauth2: enabled: true client: keycloak: issuer: clientId: clientSecret: scopes: openid, profile, email useAsUsername: email | preferred_name provider: keycloak _Using Authentik for example:_ oauth2: enabled: trueissuer: clientId: clientSecret: autoCreateUser: trueblockRegistration: falseuseAsUsername: email | name | given_name | nickname | preferred_namescopes: openid, profile, emailprovider: authentik * `security.oauth2.enabled` Set this to `true` to enable login * `security.oauth2.issuer` The URL for the Provider's OpenID Configuration. Set this to any Provider that supports an OpenID Connect Discovery `/.well-known/openid-configuration` endpoint * `security.oauth2.clientId` Client ID from your Provider * `security.oauth2.clientSecret` Client Secret from your Provider * `security.oauth2.autoCreateUser` Set this to `true` to allow auto-creation of non-existing users * `security.oauth2.blockRegistration`: Set to `true` to deny login with SSO without prior registration by an admin * `security.oauth2.useAsUsername`: The value from the Provider to use as the username for the application. Check with your Provider for specific options. The default is `email` * `security.oauth2.scopes`: Specifies the list of scopes for which the application will request permissions. The available scopes for Google and GitHub can be found [here](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2) and [here](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) * `security.oauth2.provider`: The name of the Provider The Callback URL (Redirect URL) for entering in your IdP is: `https:///login/oauth2/code/` eg `https:///login/oauth2/code/keycloak`. It is highly recommended to use an SSL-enabled reverse-proxy, if the application is going to be exposed to the internet. After the OAuth 2 login is enabled, a new button will show up on the login page as per the screenshot below. Clicking the 'Login via Single Sign-On' button will present you with the login for your Provider of choice. Once you have clicked the button, you will be redirected to your Provider in order to login and authorise Stirling-PDF to use your profile: | ![login-page.png](https://docs.stirlingpdf.com/assets/images/login-page-3e2a1af13b9328365cf7f08bfb162636.png) | ![sso-login-option.png]() | | --- | --- | SAML 2 Set Up[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#saml-2-set-up "Direct link to SAML 2 Set Up") ----------------------------------------------------------------------------------------------------------------------------------------------------------- > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#%EF%B8%8F-note-1 "Direct link to ⚠️ Note") > > _SAML 2 is an enterprise-only feature. To use it you must have `premium.enabled` set to `true` and have a valid license key._ Begin by setting `security.enableLogin` to `true` and `security.loginMethod` to `saml2` in your `/configs/settings.yml`. saml2: enabled: true provider: autoCreateUser: true blockRegistration: false registrationId: idpMetadataUri: idpSingleLoginUrl: idpSingleLogoutUrl: idpIssuer: idpCert: classpath: privateKey: classpath: spCert: classpath: * `security.saml2.enabled`: Set to `true` to activate SAML 2 SSO # Only enabled for paid enterprise clients (enterpriseEdition.enabled must be true) * `security.saml2.autoCreateUser`: Set this to `true` to allow auto-creation of non-existing users * `security.saml2.blockRegistration`: Set to `true` to deny login with SSO without prior registration by an admin * `security.saml2.registrationId`: The registration ID for your Provider. Should match the name in the path for your Assertion Consumer Service (ACS) URL The default is `stirling` * `security.saml2.idpMetadataUri`: The location of the metadata file from your Provider. Can be a file or URI * `security.saml2.idpSingleLoginUrl`: The URL given by your Provider to initiate the SSO flow * `security.saml2.idpSingleLogoutUrl`: The URL given by your Provider to initiate the SLO flow * `security.saml2.idpIssuer`: The name of your Provider * `security.saml2.idpCert`: The signing certificate given by your Provider in `.pem` format. Place in `stirling-pdf/src/main/resources` * `security.saml2.privateKey`: Your private key from your keypair in `.key` format. Place in `stirling-pdf/src/main/resources` * `security.saml2.spCert`: classpath:certificate.crt from your keypair in `.crt` format. Place in `stirling-pdf/src/main/resources` ### Generating a Keypair[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#generating-a-keypair "Direct link to Generating a Keypair") To generate a keypair for the app to use for signing and verification, enter this command in your terminal: openssl req -newkey rsa:2048 -nodes -keyout private_key.key -x509 -days 365 -out certificate.crt * `openssl req`: This starts the OpenSSL command to create or manage a certificate signing request (CSR) or certificate * `newkey rsa:2048`: This generates a new key pair using the RSA algorithm with a key size of 2048 bits. RSA 2048 is a common and secure key size * `nodes`: Skips encrypting the private key (no passphrase). If omitted, you would be prompted to set a password for the key, which would be required whenever using it. With -nodes, the private key is generated in plain text for easier use in automated systems * `keyout private_key.key`: Specifies the file name where the private key will be saved * `x509`: This tells OpenSSL to create a self-signed certificate instead of generating a certificate signing request (CSR) A self-signed certificate is not verified by a Certificate Authority (CA), which is why browsers may display a security warning when using it * `days 365`: Specifies the certificate's validity period (in days). In this case, the certificate is valid for 365 days * `out certificate.crt`: Specifies the output file where the self-signed certificate will be saved After generating the keypair, the `.key` and `.crt` files should be located in the directory you executed the above command in. Move the files to `stirling-pdf/src/main/resources`. Once you have added your configuration, you should see the button for your chosen Provider on the login page prompting you to log in: | ![sso-login-dark-mode.png](https://docs.stirlingpdf.com/assets/images/sso-login-dark-mode-68207dd332ad0514f39a5dc1f96f30b1.png) | ![sso-saml-login.png](https://docs.stirlingpdf.com/assets/images/sso-saml-login-a1d9741d4504481a350508c7188f1959.png) | | --- | --- | ### Auto-login[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#auto-login "Direct link to Auto-login") > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#%EF%B8%8F-note-2 "Direct link to ⚠️ Note") > > _Auto Login is an enterprise-only feature. To use it you must have `premium.enabled` set to `true` and have a valid license key._ It is also possible to automatically log in to Stirling PDF on start-up using SSO. To enable this feature, set the property `premium.proFeatures.SSOAutoLogin` to `true`. This will redirect to your SSO's URL when any user navigates to Stirling-PDF's default login screen. If a login fails 3 times this redirection is disabled Configurations Examples[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#configurations-examples "Direct link to Configurations Examples") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Below are examples of the full configuration for both OAuth 2 and SAML 2: * Settings File * Local Environment * Docker Run * Docker Compose security: enableLogin: true # set to 'true' to enable login oauth2: issuer: clientId: clientSecret: autoCreateUser: true blockRegistration: false useAsUsername: email scopes: openid, profile, email provider: saml2: enabled: true autoCreateUser: true blockRegistration: false registrationId: idpMetadataUri: idpSingleLoginUrl: idpSingleLogoutUrl: idpIssuer: idpCert: classpath: privateKey: classpath: spCert: classpath: export DISABLE_ADDITIONAL_FEATURES=falseexport SECURITY_ENABLELOGIN=trueexport SECURITY_OAUTH2_ENABLED=trueexport SECURITY_OAUTH2_AUTOCREATEUSER=falseexport SECURITY_OAUTH2_ISSUER=""export SECURITY_OAUTH2_CLIENTID=""export SECURITY_OAUTH2_CLIENTSECRET=""export SECURITY_OAUTH2_BLOCKREGISTRATION=falseexport SECURITY_OAUTH2_SCOPES="openid, profile, email"export SECURITY_OAUTH2_USEASUSERNAME=emailexport SECURITY_OAUTH2_PROVIDER=""export SECURITY_SAML2_ENABLED=trueexport SECURITY_SAML2_AUTOCREATEUSER=falseexport SECURITY_SAML2_REGISTRATIONID=""export SECURITY_SAML2_BLOCKREGISTRATION=falseexport SECURITY_SAML2_IDPISSUER=""export SECURITY_SAML2_IDPMETADATAURI=trueexport SECURITY_SAML2_IDPSINGLELOGINURL=""export SECURITY_SAML2_IDPSINGLELOGOUTURL=""export SECURITY_SAML2_IDPCERT=""export SECURITY_SAML2_PRIVATEKEY=""export SECURITY_SAML2_SPCERT="" -e DISABLE_ADDITIONAL_FEATURES=false \-e SECURITY_ENABLELOGIN=true \-e SECURITY_OAUTH2_ENABLED=true \-e SECURITY_OAUTH2_AUTOCREATEUSER=false \-e SECURITY_OAUTH2_ISSUER="" \-e SECURITY_OAUTH2_CLIENTID="" \-e SECURITY_OAUTH2_CLIENTSECRET="" \-e SECURITY_OAUTH2_BLOCKREGISTRATION=false \-e SECURITY_OAUTH2_SCOPES="openid, profile, email" \-e SECURITY_OAUTH2_USEASUSERNAME=email \-e SECURITY_OAUTH2_PROVIDER="" \-e SECURITY_SAML2_ENABLED=true \-e SECURITY_SAML2_AUTOCREATEUSER=false \-e SECURITY_SAML2_BLOCKREGISTRATION=false \-e SECURITY_SAML2_REGISTRATIONID="" \-e SECURITY_SAML2_IDPISSUER="" \-e SECURITY_SAML2_IDPMETADATAURI="" \-e SECURITY_SAML2_IDPSINGLELOGINURL="" \-e SECURITY_SAML2_IDPSINGLELOGOUTURL="" \-e SECURITY_SAML2_IDPCERT="" \-e SECURITY_SAML2_PRIVATEKEY="" \-e SECURITY_SAML2_SPCERT="" \ environment: DISABLE_ADDITIONAL_FEATURES=false SECURITY_ENABLELOGIN=true SECURITY_OAUTH2_ENABLED=true SECURITY_OAUTH2_AUTOCREATEUSER=false SECURITY_OAUTH2_ISSUER="" SECURITY_OAUTH2_CLIENTID="" SECURITY_OAUTH2_CLIENTSECRET="" SECURITY_OAUTH2_BLOCKREGISTRATION=false SECURITY_OAUTH2_SCOPES="openid, profile, email" SECURITY_OAUTH2_USEASUSERNAME=email SECURITY_OAUTH2_PROVIDER="" SECURITY_SAML2_ENABLED=true SECURITY_SAML2_AUTOCREATEUSER=false SECURITY_SAML2_REGISTRATIONID= SECURITY_SAML2_BLOCKREGISTRATION=false SECURITY_SAML2_IDPISSUER="" SECURITY_SAML2_IDPMETADATAURI=true SECURITY_SAML2_IDPSINGLELOGINURL="" SECURITY_SAML2_IDPSINGLELOGOUTURLSECURITY_SAML2_IDPSINGLELOGOUTURL="" SECURITY_SAML2_IDPCERT="" SECURITY_SAML2_PRIVATEKEY="" SECURITY_SAML2_SPCERT="" Disable Form Login ================== Once you successfully enabled Single Sign-on (with OAuth2 or SAML), you might want to disable the form login. This can be done by changing the `loginMethod` setting accordingly to your needs, like so: * Settings File * Docker Run * Docker Compose security: ... loginMethod: oauth2 # Accepts values like 'all' and 'normal'(only Login with Username/Password), 'oauth2'(only -e SECURITY_LOGINMETHOD="oauth2" # to enable oauth2 only environment: ... SECURITY_LOGINMETHOD: "oauth2" # to enable oauth2 only * [OAuth 2 Set Up](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#oauth-2-set-up) * [SAML 2 Set Up](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#saml-2-set-up) * [Generating a Keypair](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#generating-a-keypair) * [Auto-login](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#auto-login) * [Configurations Examples](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration/#configurations-examples) --- # UI Customisation | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own. Application Name Settings[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#application-name-settings "Direct link to Application Name Settings") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These settings control the visible application name: * `appName` - Defines the visible application name shown in the window name and navbar if navbar is not defined separately * `homeDescription` - The description displayed on the homepage under the navbar that first greets the user * `appNameNavbar` - The app name shown within the navbar for all pages Show update notifications[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#show-update-notifications "Direct link to Show update notifications") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These settings (in Settings.yml) control system behavior and customization capabilities: * `showUpdate` - Controls whether update notifications are displayed * `showUpdateOnlyAdmin` - When true, restricts update notifications to admin users only (requires `showUpdate: true`) System Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#system-configuration "Direct link to System Configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ `customHTMLFiles` In Settings.yml Enables custom HTML file overrides (called fragments) when set to true Custom Files[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#custom-files "Direct link to Custom Files") ------------------------------------------------------------------------------------------------------------------------------------------ When `customHTMLFiles` is enabled, you can override the default templatesby placing your custom files in specific directories. The system uses a resource override mechanism where files in these custom directories take precedence over the default files. ### Directory Structure[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#directory-structure "Direct link to Directory Structure") customFiles/├── static/ # Static assets (CSS, JS, images, etc.)└── templates/ # HTML template files ### File Locations[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#file-locations "Direct link to File Locations") The root path for custom files varies by installation type: * **Default/Docker Installation**: `./customFiles/` * **Windows Desktop**: `%APPDATA%\Stirling-PDF\customFiles\` * **MacOS Desktop**: `~/Library/Application Support/Stirling-PDF/customFiles/` * **Linux Desktop**: `~/.config/Stirling-PDF/customFiles/` ### Override Examples[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#override-examples "Direct link to Override Examples") To override existing files, maintain the same directory structure as the original. Here are some examples with links to the original files you would be overriding: To override a file: 1. Navigate to the original file in the GitHub repository 2. Copy its contents 3. Create the same file path under your `customFiles` directory following the same directory structure 4. Paste and modify the contents as needed Note: When overriding templates, first copy the existing template from the [source repository](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/app/core/src/main/resources/templates) to maintain the base structure. 1. To replace the favicon: customFiles/static/favicon.svg Original file: [Stirling-PDF/app/core/src/main/resources/static/favicon.svg](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/core/src/main/resources/static/favicon.svg) 2. To override a Bootstrap icon font: customFiles/static/css/fonts/bootstrap-icons.woff Original file: [Stirling-PDF/app/core/src/main/resources/static/css/fonts/bootstrap-icons.woff](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/core/src/main/resources/static/css/fonts/bootstrap-icons.woff) 3. To modify a template: customFiles/templates/fragments/common.html Original file: [Stirling-PDF/app/core/src/main/resources/templates/fragments/common.html](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/core/src/main/resources/templates/fragments/common.html) The original files can be found in the GitHub repository under: * Static files: [Stirling-PDF/app/core/src/main/resources/static/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/app/core/src/main/resources/static) * Templates (HTML files): [Stirling-PDF/app/core/src/main/resources/templates/](https://github.com/Stirling-Tools/Stirling-PDF/tree/main/app/core/src/main/resources/templates) Configuration Examples[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#configuration-examples "Direct link to Configuration Examples") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * Settings File * Local Environment * Docker Run * Docker Compose ui: appName: exampleAppName # Application's visible name homeDescription: I am a description # Short description or tagline shown on homepage appNameNavbar: navbarName # Name displayed on the navigation barsystem: showUpdate: false # Control update notification visibility showUpdateOnlyAdmin: false # Restrict update notifications to admins customHTMLFiles: false # Enable custom HTML/CSS overrides You can configure the UI and system settings in two ways when running locally: **Option 1: Using Java Properties** java -jar Stirling-PDF.jar \ -DAPP_HOME_NAME="New Application Name" \ -DSHOW_UPDATE=false \ -DSHOW_UPDATE_ONLY_ADMIN=false \ -DCUSTOM_HTML_FILES=true **Option 2: Using Environment Variables** export UI_APPNAME="Stirling PDF"export UI_HOMEDESCRIPTION="Your locally hosted one-stop-shop for all your PDF needs."export UI_APPNAVBARNAME="Stirling PDF"export SYSTEM_SHOWUPDATE=falseexport SYSTEM_SHOWUPDATEONLYADMIN=falseexport SYSTEM_CUSTOMHTMLFILES=true -e UI_APPNAME=Stirling PDF \-e UI_HOMEDESCRIPTION=Your locally hosted one-stop-shop for all your PDF needs. \-e UI_APPNAVBARNAME=Stirling PDF \-e SYSTEM_SHOWUPDATE=false \-e SYSTEM_SHOWUPDATEONLYADMIN=false \-e SYSTEM_CUSTOMHTMLFILES=true environment: UI_APPNAME: Stirling PDF UI_HOMEDESCRIPTION: Your locally hosted one-stop-shop for all your PDF needs. UI_APPNAVBARNAME: Stirling PDF SYSTEM_SHOWUPDATE: "false" SYSTEM_SHOWUPDATEONLYADMIN: "false" SYSTEM_CUSTOMHTMLFILES: "true"volumes: - ./customFiles:/app/customFiles # Mount custom files directory * [Application Name Settings](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#application-name-settings) * [Show update notifications](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#show-update-notifications) * [System Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#system-configuration) * [Custom Files](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#custom-files) * [Directory Structure](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#directory-structure) * [File Locations](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#file-locations) * [Override Examples](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#override-examples) * [Configuration Examples](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation/#configuration-examples) --- # Shared Signing | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#__docusaurus_skipToContent_fallback) On this page Alpha Feature Shared Signing is currently in **alpha**. Functionality may change, and some features are incomplete. Use in production at your own risk. Shared Signing lets a document owner send a PDF to multiple registered users for signing. Each participant reviews the document, applies their signature, and submits it back. The owner tracks progress and finalizes the document once all signatures are collected. This is a **Pro/Enterprise** feature. * * * What You Can Do[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#what-you-can-do "Direct link to What You Can Do") ----------------------------------------------------------------------------------------------------------------------------------------- * **Invite multiple signers** -- add registered users as participants to a signing session * **Flexible signing options** -- participants can use the server certificate, their personal certificate, or upload their own (P12, JKS, PEM) * **Handwritten signatures** -- participants can draw, type, or upload a wet signature overlay and place it on any page * **Track progress** -- see who has signed, viewed, or declined in real time * **Summary page** -- optionally append a page to the final PDF listing all signers, timestamps, and details * **Data cleanup** -- sensitive signature and certificate data is automatically cleared from the server after finalization * * * Prerequisites[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------------------------------- * Settings File * Environment Variables security: enableLogin: truestorage: enabled: true signing: enabled: truesystem: frontendUrl: https://your-stirling-instance.com serverCertificate: enabled: true SECURITY_ENABLELOGIN=trueSTORAGE_ENABLED=trueSTORAGE_SIGNING_ENABLED=trueSYSTEM_FRONTENDURL=https://your-stirling-instance.comSYSTEM_SERVERCERTIFICATE_ENABLED=true * * * How It Works[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#how-it-works "Direct link to How It Works") -------------------------------------------------------------------------------------------------------------------------------- ### Step 1: Create a Signing Session[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-1-create-a-signing-session "Direct link to Step 1: Create a Signing Session") 1. Open a PDF in the viewer 2. Click the **Sign** button in the Quick Access Bar 3. Click the **+** button next to **Signature Requests** 4. Add participants by selecting registered users 5. Optionally set a due date and configure signature display preferences 6. Review and submit **Session options:** | Option | What it does | | --- | --- | | **Signature visibility** | Choose whether the digital signature block is visible on the PDF or embedded invisibly | | **Signature page number** | Which page to place the signature block on | | **Reason** | A reason for signing (e.g., "Approved", "I agree to these terms") | | **Location** | Where the signing is taking place (e.g., "New York") | | **Show logo** | Includes the organization logo in the signature block | | **Include summary page** | Appends a page at the end listing all signers and their details | ### Step 2: Participants Review and Sign[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-2-participants-review-and-sign "Direct link to Step 2: Participants Review and Sign") Participants see pending sign requests under the **Sign** button in the Quick Access Bar after logging in. From there they can: 1. **Review** the document and session details (due date, signature preferences) 2. **Choose a certificate** to sign with: | Certificate Option | Description | Requires Upload? | | --- | --- | --- | | **Server Certificate** | Your organization's certificate | No | | **Personal Certificate** | Auto-generated for the participant | No | | **P12 / PKCS12 / PFX** | Participant's own certificate file | Yes (+ password) | | **JKS** | Java KeyStore file | Yes (+ password) | | **PEM** | PEM certificate + private key | Yes | 3. **Add wet signatures** (optional) -- draw, type, or upload a handwritten signature and position it on any page. Multiple signatures can be placed across different pages. 4. **Submit** their signature Once submitted, the participant's status changes to **Signed** and they can no longer modify their submission. Participants can also **decline** to sign, which marks their status as **Declined**. ### Step 3: Track Progress[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-3-track-progress "Direct link to Step 3: Track Progress") The session owner can monitor progress from the Quick Access Bar or the session detail view: * **Signature count** shown as "X/Y signatures" (e.g., "3/5 signatures") * **Color-coded badges**: Blue (none signed), Yellow (some signed), Green (all signed -- ready to finalize) * **Per-participant status**: Pending, Viewed, Signed, or Declined The status auto-refreshes every 15 seconds. ### Step 4: Finalize[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-4-finalize "Direct link to Step 4: Finalize") Once you've collected the signatures you need, click **Finalize** to produce the signed PDF. warning Finalization is a one-time operation. Participants who haven't signed will be skipped. Make sure you have all the signatures you need before finalizing. **What happens when you finalize:** 1. All wet signature images are applied to the PDF at the positions each participant chose 2. If enabled, a summary page is appended showing each participant's name, email, status, timestamp, reason, and certificate type 3. Each participant's digital certificate is applied to the document 4. The signed PDF is saved and available for download 5. Sensitive data (signature images, certificate files, passwords) is permanently cleared from the server ### Step 5: Download the Signed PDF[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-5-download-the-signed-pdf "Direct link to Step 5: Download the Signed PDF") After finalization, download the completed PDF from the session detail view or the **Completed Sessions** panel. The PDF contains all digital certificate signatures and wet signature overlays embedded in the document. * * * Security[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#security "Direct link to Security") -------------------------------------------------------------------------------------------------------------------- * **One-time signing** -- after signing or declining, participants are automatically downgraded to read-only access and cannot re-sign * **Certificate validation** -- uploaded certificates are validated at submission time. Trust chain validation is configurable (see [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) ) * **Audit trail** -- all participant actions are recorded (viewed, signed, declined) with timestamps * **Post-finalization cleanup** -- wet signature images, certificate files, and passwords are permanently removed from the database after finalization. Only the final signed PDF is retained * * * Configuration Reference[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#configuration-reference "Direct link to Configuration Reference") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Signing Settings[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#signing-settings "Direct link to Signing Settings") * Settings File * Environment Variables storage: enabled: true signing: enabled: true # Master switch for shared signingsystem: frontendUrl: https://your-instance.com serverCertificate: enabled: true organizationName: My Company validity: 365 # Certificate validity in days regenerateOnStartup: false STORAGE_ENABLED=trueSTORAGE_SIGNING_ENABLED=trueSYSTEM_FRONTENDURL=https://your-instance.comSYSTEM_SERVERCERTIFICATE_ENABLED=trueSYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"SYSTEM_SERVERCERTIFICATE_VALIDITY=365 ### Certificate Validation Settings[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#certificate-validation-settings "Direct link to Certificate Validation Settings") security: validation: trust: serverAsAnchor: true # Trust server-generated certificates useSystemTrust: true # Trust OS certificate store useMozillaBundle: true # Trust Mozilla CA bundle revocation: mode: none # Options: none, ocsp, crl, ocsp+crl hardFail: false # Fail if revocation check is inconclusive See [Certificate Signing - Configuration](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing#configuration-examples) for detailed trust chain configuration. * * * Known Limitations[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#known-limitations "Direct link to Known Limitations") ----------------------------------------------------------------------------------------------------------------------------------------------- * Participants must be registered users with accounts on your Stirling PDF instance * Finalization can only be done once -- a session cannot be re-opened afterwards * Each session covers a single document * Digital certificates are applied in participant order during finalization * The signature summary page is English-only * * * Troubleshooting[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#troubleshooting "Direct link to Troubleshooting") ----------------------------------------------------------------------------------------------------------------------------------------- ### Signature not appearing on the finalized PDF[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#signature-not-appearing-on-the-finalized-pdf "Direct link to Signature not appearing on the finalized PDF") * Double-check the certificate type and password were entered correctly * Check the Stirling PDF server logs for signing errors * Make sure the source PDF is not corrupted or password-protected ### Progress count not updating[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#progress-count-not-updating "Direct link to Progress count not updating") * The dashboard auto-refreshes every 15 seconds -- wait a moment and check again * Check your browser's network tab for failed API requests ### Wet signatures missing after finalization[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#wet-signatures-missing-after-finalization "Direct link to Wet signatures missing after finalization") * Make sure the page numbers used are within the document's page range (pages start at 0) ### "Storage is disabled" when creating a session[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#storage-is-disabled-when-creating-a-session "Direct link to "Storage is disabled" when creating a session") * Verify `storage.enabled: true` and `security.enableLogin: true` in your configuration * * * API Reference[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#api-reference "Direct link to API Reference") ----------------------------------------------------------------------------------------------------------------------------------- For users who want to integrate with the signing workflow programmatically, the full API endpoints are listed below. See [API Documentation](https://docs.stirlingpdf.com/API) for details. ### Owner Endpoints (Authentication Required)[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#owner-endpoints-authentication-required "Direct link to Owner Endpoints (Authentication Required)") | Method | Endpoint | Description | | --- | --- | --- | | POST | `/api/v1/security/cert-sign/sessions` | Create signing session | | GET | `/api/v1/security/cert-sign/sessions` | List your sessions | | GET | `/api/v1/security/cert-sign/sessions/{id}` | Get session details | | GET | `/api/v1/security/cert-sign/sessions/{id}/pdf` | Download original PDF | | POST | `/api/v1/security/cert-sign/sessions/{id}/finalize` | Finalize and generate signed PDF | | GET | `/api/v1/security/cert-sign/sessions/{id}/signed-pdf` | Download signed PDF | | DELETE | `/api/v1/security/cert-sign/sessions/{id}` | Delete session | | POST | `/api/v1/security/cert-sign/sessions/{id}/participants` | Add participants | | DELETE | `/api/v1/security/cert-sign/sessions/{id}/participants/{pid}` | Remove participant | ### Participant Endpoints (Authentication Required)[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#participant-endpoints-authentication-required "Direct link to Participant Endpoints (Authentication Required)") | Method | Endpoint | Description | | --- | --- | --- | | GET | `/api/v1/security/cert-sign/sign-requests` | List your sign requests | | GET | `/api/v1/security/cert-sign/sign-requests/{id}` | Get sign request details | | GET | `/api/v1/security/cert-sign/sign-requests/{id}/document` | Download document to review | | POST | `/api/v1/security/cert-sign/sign-requests/{id}/sign` | Sign the document | | POST | `/api/v1/security/cert-sign/sign-requests/{id}/decline` | Decline to sign | * * * Related[​](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#related "Direct link to Related") ----------------------------------------------------------------------------------------------------------------- * [File Sharing and Storage](https://docs.stirlingpdf.com/Configuration/File-Sharing-Storage) -- Configure storage, sharing, and quotas * [Certificate Signing](https://docs.stirlingpdf.com/Functionality/Security/Certificate-Signing) -- Individual certificate signing and validation * [Sign (Handwritten)](https://docs.stirlingpdf.com/Functionality/Security/Sign) -- Non-cryptographic visual signatures * [System and Security Settings](https://docs.stirlingpdf.com/Configuration/System%20and%20Security) -- Server certificates, JWT, sessions * [What You Can Do](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#what-you-can-do) * [Prerequisites](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#prerequisites) * [How It Works](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#how-it-works) * [Step 1: Create a Signing Session](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-1-create-a-signing-session) * [Step 2: Participants Review and Sign](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-2-participants-review-and-sign) * [Step 3: Track Progress](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-3-track-progress) * [Step 4: Finalize](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-4-finalize) * [Step 5: Download the Signed PDF](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#step-5-download-the-signed-pdf) * [Security](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#security) * [Configuration Reference](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#configuration-reference) * [Signing Settings](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#signing-settings) * [Certificate Validation Settings](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#certificate-validation-settings) * [Known Limitations](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#known-limitations) * [Troubleshooting](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#troubleshooting) * [Signature not appearing on the finalized PDF](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#signature-not-appearing-on-the-finalized-pdf) * [Progress count not updating](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#progress-count-not-updating) * [Wet signatures missing after finalization](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#wet-signatures-missing-after-finalization) * ["Storage is disabled" when creating a session](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#storage-is-disabled-when-creating-a-session) * [API Reference](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#api-reference) * [Owner Endpoints (Authentication Required)](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#owner-endpoints-authentication-required) * [Participant Endpoints (Authentication Required)](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#participant-endpoints-authentication-required) * [Related](https://docs.stirlingpdf.com/Functionality/Security/Shared-Signing/#related) --- # Manual Redaction | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Overview[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#overview "Direct link to Overview") ----------------------------------------------------------------------------------------------------------------------- The Document Redaction Tool allows you to securely redact sensitive information from documents using three different methods: text selection, area drawing, or entire page redaction. Redaction Methods[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#redaction-methods "Direct link to Redaction Methods") -------------------------------------------------------------------------------------------------------------------------------------------------- ### 1\. Text Selection Redaction[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#1-text-selection-redaction "Direct link to 1. Text Selection Redaction") Perfect for redacting specific words, sentences, or paragraphs. **How to use:** 1. Click the text selection icon in the toolbar ![image](https://github.com/user-attachments/assets/e66dbfc1-0b06-4f65-8f60-7277b8acca91) 2. Select the text you want to redact 3. Apply the redaction by either: * Pressing `Ctrl + S` * Clicking the save icon in the toolbar ![image](https://github.com/user-attachments/assets/73d4b1f0-a454-452b-ab60-028b9728004b) ### 2\. Area Drawing Redaction[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#2-area-drawing-redaction "Direct link to 2. Area Drawing Redaction") Ideal for redacting images, tables, or irregular content blocks. **How to use:** 1. Click the drawing tool icon in the toolbar ![image](https://github.com/user-attachments/assets/8597abed-0992-48d3-baf4-0e7673fb500c) 2. Click and hold at your starting point 3. Drag to create a rectangle over the area 4. Click again to confirm and apply the redaction * A red border means unsaved ![image](https://github.com/user-attachments/assets/42809be3-34e6-4725-920b-b4d51eb72e4f) * A green border means saved and active ![image](https://github.com/user-attachments/assets/0711ff11-da1a-41c3-9d57-82067ee0f8b8) ### 3\. Page Redaction[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#3-page-redaction "Direct link to 3. Page Redaction") Used when you need to redact entire pages. **How to use:** 1. Open the page redaction dialog ![image](https://github.com/user-attachments/assets/fae58a19-1f54-463e-bc81-027bd4f403bf) ![image](https://github.com/user-attachments/assets/66c1b1aa-7da1-4262-a476-0551924ed509) 2. Enter page numbers or ranges (e.g., "1,3-5,7") 3. Select your preferred color 4. Click "Apply" to save changes Customizing Redactions[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#customizing-redactions "Direct link to Customizing Redactions") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Changing Colors[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#changing-colors "Direct link to Changing Colors") **For new redactions:** 1. Click the color palette icon in the toolbar ![image](https://github.com/user-attachments/assets/788fd325-489e-4404-8377-07ec500a77dd) 2. Select your preferred color 3. Any new redactions will use this color **For existing redactions:** 1. Click the redacted area 2. Click the color palette icon that appears 3. Choose your new color ![redaction_color](https://github.com/user-attachments/assets/0bc05461-6427-4a62-8cd4-745c3104c04f) ### Removing Redactions[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#removing-redactions "Direct link to Removing Redactions") 1. Click the redacted area you want to remove 2. Either: * Click the trash icon that appears * Press the `Delete` key ![redaction_removal](https://github.com/user-attachments/assets/9bd3be2a-d2ec-4468-a229-bf81efb36bcc) ### Converting PDF to PDF-image (Used in removing text behind the box)[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#converting-pdf-to-pdf-image-used-in-removing-text-behind-the-box "Direct link to Converting PDF to PDF-image (Used in removing text behind the box)") To enable PDF to PDF-image option: 1. Click on the image icon ![image](https://github.com/user-attachments/assets/8c480923-05e1-46d3-8f59-5f78db6d87f8) To disable PDF to PDF-image option: 1. Click on the image icon ![image](https://github.com/user-attachments/assets/e2e07e31-8eb0-41ac-80ab-ffd8520f5795) * If the image icon is green, then the option is enabled, if it is red then it is disabled. Keyboard Shortcuts[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#keyboard-shortcuts "Direct link to Keyboard Shortcuts") ----------------------------------------------------------------------------------------------------------------------------------------------------- * `Ctrl + S`: Save/apply redaction * `Delete`: Remove selected redaction * `Escape`: Cancel unsaved area drawing Tips[​](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#tips "Direct link to Tips") ----------------------------------------------------------------------------------------------------------- * If you're in drawing mode and need to delete a redaction, temporarily disable drawing mode first * You can combine different redaction methods in the same document * Always review your redactions before finalizing the document * Redaction colors can be changed at any time, even after applying * [Overview](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#overview) * [Redaction Methods](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#redaction-methods) * [1\. Text Selection Redaction](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#1-text-selection-redaction) * [2\. Area Drawing Redaction](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#2-area-drawing-redaction) * [3\. Page Redaction](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#3-page-redaction) * [Customizing Redactions](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#customizing-redactions) * [Changing Colors](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#changing-colors) * [Removing Redactions](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#removing-redactions) * [Converting PDF to PDF-image (Used in removing text behind the box)](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#converting-pdf-to-pdf-image-used-in-removing-text-behind-the-box) * [Keyboard Shortcuts](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#keyboard-shortcuts) * [Tips](https://docs.stirlingpdf.com/1.5/Functionality/Page-Operations/redact/#tips) --- # Path Structure | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Server Deployment[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#server-deployment "Direct link to Server Deployment") ------------------------------------------------------------------------------------------------------------------------------------------- When running in server mode, the base path defaults to `./` (current directory) Desktop Deployment[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#desktop-deployment "Direct link to Desktop Deployment") ---------------------------------------------------------------------------------------------------------------------------------------------- When running as a desktop application (non-server deployment), the base path is set according to the operating system: * **Windows**: `%APPDATA%\Stirling-PDF\` * **macOS**: `~/Library/Application Support/Stirling-PDF/` * **Linux/Unix**: `~/.config/Stirling-PDF/` Directory Structure =================== All paths below are relative to the BASE\_PATH. The File.separator ensures cross-platform compatibility. Root Directories[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#root-directories "Direct link to Root Directories") ---------------------------------------------------------------------------------------------------------------------------------------- * `logs/` - Application logs storage * `configs/` - Configuration files * `pipeline/` - Pipeline-related operations * `customFiles/` - Custom assets and templates * `clientWebUI/` - Web interface assets Configuration Files[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#configuration-files "Direct link to Configuration Files") ------------------------------------------------------------------------------------------------------------------------------------------------- * `configs/settings.yml` - Main settings file * `configs/custom_settings.yml` - User-specific settings Pipeline Directories[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#pipeline-directories "Direct link to Pipeline Directories") ---------------------------------------------------------------------------------------------------------------------------------------------------- * `pipeline/watchedFolders/` - Monitored directories for automated processing * `pipeline/finishedFolders/` - Completed processing output location Custom Files Structure[​](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#custom-files-structure "Direct link to Custom Files Structure") ---------------------------------------------------------------------------------------------------------------------------------------------------------- * `customFiles/static/` - Static assets * `customFiles/templates/` - Template files * `customFiles/signatures/` - Digital signature files * [Server Deployment](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#server-deployment) * [Desktop Deployment](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#desktop-deployment) * [Root Directories](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#root-directories) * [Configuration Files](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#configuration-files) * [Pipeline Directories](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#pipeline-directories) * [Custom Files Structure](https://docs.stirlingpdf.com/1.5/Installation/Path%20Structure/#custom-files-structure) --- # Tags | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/#__docusaurus_skipToContent_fallback) Tags ==== A[​](https://docs.stirlingpdf.com/tags/#A "Direct link to A") -------------------------------------------------------------- * [advanced feature7](https://docs.stirlingpdf.com/tags/advanced-feature) * [API1](https://docs.stirlingpdf.com/tags/api) * * * C[​](https://docs.stirlingpdf.com/tags/#C "Direct link to C") -------------------------------------------------------------- * [customisation1](https://docs.stirlingpdf.com/tags/customisation) * * * D[​](https://docs.stirlingpdf.com/tags/#D "Direct link to D") -------------------------------------------------------------- * [database2](https://docs.stirlingpdf.com/tags/database) * * * E[​](https://docs.stirlingpdf.com/tags/#E "Direct link to E") -------------------------------------------------------------- * [enterprise6](https://docs.stirlingpdf.com/tags/enterprise) * * * F[​](https://docs.stirlingpdf.com/tags/#F "Direct link to F") -------------------------------------------------------------- * [feature7](https://docs.stirlingpdf.com/tags/feature) * * * M[​](https://docs.stirlingpdf.com/tags/#M "Direct link to M") -------------------------------------------------------------- * [management7](https://docs.stirlingpdf.com/tags/management) * * * P[​](https://docs.stirlingpdf.com/tags/#P "Direct link to P") -------------------------------------------------------------- * [Paid1](https://docs.stirlingpdf.com/tags/paid) * [Pricing1](https://docs.stirlingpdf.com/tags/pricing) * * * S[​](https://docs.stirlingpdf.com/tags/#S "Direct link to S") -------------------------------------------------------------- * [saml1](https://docs.stirlingpdf.com/tags/saml) * [server4](https://docs.stirlingpdf.com/tags/server) * * * U[​](https://docs.stirlingpdf.com/tags/#U "Direct link to U") -------------------------------------------------------------- * [UI1](https://docs.stirlingpdf.com/tags/ui) * * * --- # Kubernetes Guide | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page ### Run stirling-pdf helm chart[​](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#run-stirling-pdf-helm-chart "Direct link to Run stirling-pdf helm chart") helm repo add stirling-pdf https://stirling-tools.github.io/Stirling-PDF-charthelm repo updatehelm install stirling-pdf stirling-pdf/stirling-pdf-chart --namespace stirling-pdf --create-namespace ### Override stirling-pdf default values[​](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#override-stirling-pdf-default-values "Direct link to Override stirling-pdf default values") Create a `values.yaml` file with the values you want to override from the [documentation](https://github.com/Stirling-Tools/Stirling-PDF-chart/tree/main/charts/stirling-pdf) . Then, add `-f values.yaml` to the `helm install` command. ### Upgrade the helm chart[​](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#upgrade-the-helm-chart "Direct link to Upgrade the helm chart") helm repo updatehelm upgrade stirling-pdf stirling-pdf/stirling-pdf-chart --namespace stirling-pdf --reuse-values * [Run stirling-pdf helm chart](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#run-stirling-pdf-helm-chart) * [Override stirling-pdf default values](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#override-stirling-pdf-default-values) * [Upgrade the helm chart](https://docs.stirlingpdf.com/1.5/Installation/Kubernetes%20Install/#upgrade-the-helm-chart) --- # 2 docs tagged with "database" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/database/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/Configuration/DATABASE) Tier: Server [External Database\ -----------------](https://docs.stirlingpdf.com/Configuration/External%20Database) Tier: Server --- # One doc tagged with "saml" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/saml/#__docusaurus_skipToContent_fallback) [SAML 2.0 Single Sign-On Configuration\ -------------------------------------](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) Tier: Enterprise --- # 7 docs tagged with "management" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/management/#__docusaurus_skipToContent_fallback) [Audit Logging\ -------------](https://docs.stirlingpdf.com/Configuration/Audit%20Logging) Tier: Enterprise [Database Backups\ ----------------](https://docs.stirlingpdf.com/Configuration/DATABASE) Tier: Server [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker) Tier: Server [OAuth 2.0 Single Sign-On Configuration\ --------------------------------------](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) Tier: Server [SAML 2.0 Single Sign-On Configuration\ -------------------------------------](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) Tier: Enterprise [Single Sign-On (SSO) Overview\ -----------------------------](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) Stirling PDF supports Single Sign-On (SSO) authentication through two protocols: [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) Tier: Enterprise --- # One doc tagged with "customisation" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/customisation/#__docusaurus_skipToContent_fallback) [UI Customisation\ ----------------](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. --- # 7 docs tagged with "feature" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/feature/#__docusaurus_skipToContent_fallback) [Audit Logging\ -------------](https://docs.stirlingpdf.com/Configuration/Audit%20Logging) Tier: Enterprise [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker) Tier: Server [OAuth 2.0 Single Sign-On Configuration\ --------------------------------------](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) Tier: Server [SAML 2.0 Single Sign-On Configuration\ -------------------------------------](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) Tier: Enterprise [Single Sign-On (SSO) Overview\ -----------------------------](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) Stirling PDF supports Single Sign-On (SSO) authentication through two protocols: [UI Customisation\ ----------------](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) Tier: Enterprise --- # One doc tagged with "UI" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/ui/#__docusaurus_skipToContent_fallback) [UI Customisation\ ----------------](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. --- # 7 docs tagged with "advanced feature" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/tags/advanced-feature/#__docusaurus_skipToContent_fallback) [Audit Logging\ -------------](https://docs.stirlingpdf.com/Configuration/Audit%20Logging) Tier: Enterprise [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/Configuration/Google%20Drive%20File%20Picker) Tier: Server [OAuth 2.0 Single Sign-On Configuration\ --------------------------------------](https://docs.stirlingpdf.com/Configuration/OAuth%20SSO%20Configuration) Tier: Server [SAML 2.0 Single Sign-On Configuration\ -------------------------------------](https://docs.stirlingpdf.com/Configuration/SAML%20SSO%20Configuration/) Tier: Enterprise [Single Sign-On (SSO) Overview\ -----------------------------](https://docs.stirlingpdf.com/Configuration/Single%20Sign-On%20Configuration) Stirling PDF supports Single Sign-On (SSO) authentication through two protocols: [UI Customisation\ ----------------](https://docs.stirlingpdf.com/Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling PDF your own. [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/Configuration/Usage%20Monitoring) Tier: Enterprise --- # Enabling PDF to CBR Conversion in Stirling PDF | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#__docusaurus_skipToContent_fallback) On this page Overview[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#overview "Direct link to Overview") ----------------------------------------------------------------------------------------------------------------------------------- Stirling PDF can convert PDF files into the Comic Book RAR (`.cbr`) format. This process relies on an external command-line utility, `rar`, which is not included by default. To enable this feature, you must first install the `rar` utility on your system and then make it accessible to Stirling PDF. ### What is a CBR file?[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#what-is-a-cbr-file "Direct link to What is a CBR file?") A CBR (Comic Book RAR) file is an archive used for distributing digital comic books. It is essentially a collection of sequential image files (e.g., JPEG, PNG) compressed into a single file using RAR compression. While CBR is a popular format, it requires the proprietary `rar` utility for creation. Its more common, open-standard alternative is CBZ (Comic Book ZIP), which is supported by Stirling PDF out of the box. * * * Step 1: Install the `rar` Command-Line Utility[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-1-install-the-rar-command-line-utility "Direct link to step-1-install-the-rar-command-line-utility") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This is a mandatory prerequisite for both Docker and non-Docker setups. The `rar` executable must be installed on the host machine. ### Linux[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#linux "Direct link to Linux") The easiest method is to use your distribution's package manager. **Debian / Ubuntu:** The `rar` package is available in the `non-free` repository. sudo apt updatesudo apt install rar **Fedora / CentOS / RHEL:** The `rar` package is available in the RPM Fusion "non-free" repository. # First, enable the RPM Fusion non-free repository for your system.# See https://rpmfusion.org/Configuration for instructions.# Then, install rarsudo dnf install rar # For Fedora, RHEL 8+, CentOS Stream# orsudo yum install rar # For CentOS 7 **Manual Installation (Any Linux Distribution):** 1. Visit the official download page: [rarlab.com/download.htm](https://www.rarlab.com/download.htm) . 2. Download the "RAR for Linux x64" command-line version. 3. Extract the archive and install the binary: # The version number (e.g., 712, as of writing this guide) will change.# Use the actual filename.tar -xzf rarlinux-x64-*.tar.gz# Move the binary to a standard location in your system's PATHsudo mv rar/rar /usr/local/bin/# Ensure it has execute permissionssudo chmod +x /usr/local/bin/rar ### Windows[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#windows "Direct link to Windows") 1. Download the "WinRAR and RAR command line tools" from [rarlab.com/download.htm](https://www.rarlab.com/download.htm) . 2. Extract the downloaded archive. 3. Copy the `rar.exe` file to a folder that is included in your system's `PATH` environment variable. A common and reliable location is `C:\Windows\System32`. 4. If Stirling PDF is already running, restart it to ensure it recognizes the updated `PATH`. ### macOS[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#macos "Direct link to macOS") The recommended method is to use the [Homebrew](https://brew.sh/) package manager. brew install rar * * * Step 2: Configure Stirling PDF[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-2-configure-stirling-pdf "Direct link to Step 2: Configure Stirling PDF") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- After installing `rar` on your host system, follow the appropriate instructions for your environment. ### For Non-Docker Users[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#for-non-docker-users "Direct link to For Non-Docker Users") If you installed Stirling PDF directly on your operating system (without Docker), no further configuration is needed. As long as the `rar` command is available in your system's `PATH`, Stirling PDF will automatically (after restart) detect and use it. ### For Docker Users[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#for-docker-users "Direct link to For Docker Users") For the binary to be accessible inside the container, you have to mount the binary as a volume. Update your `docker-compose.yml` to include the volume mount. The path on the host side must match where you installed `rar`. services: stirling-pdf: image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest ports: - '8080:8080' volumes: - ./StirlingPDF/trainingData:/usr/share/tessdata - ./StirlingPDF/extraConfigs:/configs - ./StirlingPDF/customFiles:/customFiles/ - ./StirlingPDF/logs:/logs/ - ./StirlingPDF/pipeline:/pipeline/ # Add the following line to mount the rar binary - /usr/local/bin/rar:/usr/local/bin/rar:ro **Note for Windows Docker Users:** The host path must use forward slashes. For example, if you placed `rar.exe` in `C:\Program Files\RAR`, your volume mount would look like this: # Example for Windows host path- "C:/Program Files/RAR/rar.exe:/usr/local/bin/rar:ro" * * * Step 3: Verification[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-3-verification "Direct link to Step 3: Verification") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Confirm that Stirling PDF can access the `rar` command. * **For Docker Users:** Execute a command inside the running container. docker exec -it stirling-pdf rar * **For Non-Docker Users:** Check if the `rar` command is recognized in your terminal. # On Linux and macOSwhich rar# On Windowswhere rar In both cases, a successful setup will display the RAR version and usage information. An error like "command not found" means there is a problem with the installation or `PATH`. * * * Important Considerations[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#important-considerations "Direct link to Important Considerations") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### License Note[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#license-note "Direct link to License Note") RAR is shareware. While it is free to use for personal, non-commercial purposes, business or commercial use may require purchasing a license. Please review the official RAR license terms on the RARLAB website for complete details. ### Alternative: Use the CBZ Format[​](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#alternative-use-the-cbz-format "Direct link to Alternative: Use the CBZ Format") For broader compatibility and to avoid proprietary software, using the **CBZ (Comic Book ZIP)** format is highly recommended. * CBZ uses the open and universal ZIP standard. * The **PDF to CBZ** tool is enabled in Stirling PDF by default and requires no extra software. * CBZ is supported by virtually all modern comic book reader applications. * [Overview](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#overview) * [What is a CBR file?](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#what-is-a-cbr-file) * [Step 1: Install the `rar` Command-Line Utility](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-1-install-the-rar-command-line-utility) * [Linux](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#linux) * [Windows](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#windows) * [macOS](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#macos) * [Step 2: Configure Stirling PDF](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-2-configure-stirling-pdf) * [For Non-Docker Users](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#for-non-docker-users) * [For Docker Users](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#for-docker-users) * [Step 3: Verification](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#step-3-verification) * [Important Considerations](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#important-considerations) * [License Note](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#license-note) * [Alternative: Use the CBZ Format](https://docs.stirlingpdf.com/Advanced%20Configuration/PDF%20to%20CBR%20Conversion/#alternative-use-the-cbz-format) --- # Visual Sign with Custom File Storage | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF provides functionality to store and reuse files across sessions, particularly useful for features like signatures and commonly used assets. This guide explains how to set up and use custom file storage. Overview[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#overview "Direct link to Overview") ---------------------------------------------------------------------------------------------------------------------------------------- The custom file storage system allows you to: * Store files persistently across sessions * Share files between all users or restrict them to specific users * Access stored files through the web UI * Organize files in a structured way Storage Location[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#storage-location "Direct link to Storage Location") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- All custom files should be stored in the `/customFiles/` directory. For features like signatures, the specific path is: /customFiles/signatures/ Access Levels[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#access-levels "Direct link to Access Levels") ------------------------------------------------------------------------------------------------------------------------------------------------------- The system supports two types of access levels for stored files: ### 1\. All Users Access[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#1-all-users-access "Direct link to 1. All Users Access") Files that should be accessible to all users should be placed in: /customFiles/signatures/ALL_USERS/ This is useful for: * Organization-wide templates * Shared assets * Default signatures or watermarks * Environments where authentication isn't used ### 2\. User-Specific Access[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#2-user-specific-access "Direct link to 2. User-Specific Access") Files that should only be accessible to specific users should be placed in user-specific directories: /customFiles/signatures/{username}/ For example: /customFiles/signatures/john_doe/ These files will only be accessible to the specified user when logged in. Usage in Docker[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#usage-in-docker "Direct link to Usage in Docker") ------------------------------------------------------------------------------------------------------------------------------------------------------------- When using Docker, make sure to mount the customFiles directory as a volume to persist the files: volumes: - ./customFiles:/customFiles/ Best Practices[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#best-practices "Direct link to Best Practices") ---------------------------------------------------------------------------------------------------------------------------------------------------------- 1. File Organization: * Keep files organized in appropriate subdirectories * Use clear, descriptive filenames * Consider using date-based or category-based organization for large numbers of files 2. Security: * Only place files in ALL\_USERS if they truly need to be accessible to everyone * Regularly review and clean up unused files * Monitor storage usage to prevent excessive accumulation of files 3. Supported File Types: * For signatures: common image formats (PNG, JPG, SVG) * Ensure files are of appropriate size and format for their intended use Example Structure[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#example-structure "Direct link to Example Structure") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here's an example of how your custom files directory might look: /customFiles/├── signatures/│ ├── ALL_USERS/│ │ ├── company-logo.png│ │ └── default-signature.png│ ├── john_doe/│ │ ├── personal-signature.png│ │ └── department-stamp.png│ └── jane_smith/│ └── signature-2024.png Accessing Files[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#accessing-files "Direct link to Accessing Files") ------------------------------------------------------------------------------------------------------------------------------------------------------------- Files stored in these locations will automatically be available in the relevant features of the Stirling PDF web interface. For example, saved signatures will appear in the signature selection interface when using the Sign feature. * [Overview](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#overview) * [Storage Location](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#storage-location) * [Access Levels](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#access-levels) * [1\. All Users Access](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#1-all-users-access) * [2\. User-Specific Access](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#2-user-specific-access) * [Usage in Docker](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#usage-in-docker) * [Best Practices](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#best-practices) * [Example Structure](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#example-structure) * [Accessing Files](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Sign%20with%20custom%20files/#accessing-files) --- # Tags | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/#__docusaurus_skipToContent_fallback) Tags ==== A[​](https://docs.stirlingpdf.com/1.5/tags/#A "Direct link to A") ------------------------------------------------------------------ * [advanced feature4](https://docs.stirlingpdf.com/1.5/tags/advanced-feature) * [API1](https://docs.stirlingpdf.com/1.5/tags/api) * * * C[​](https://docs.stirlingpdf.com/1.5/tags/#C "Direct link to C") ------------------------------------------------------------------ * [customisation1](https://docs.stirlingpdf.com/1.5/tags/customisation) * * * D[​](https://docs.stirlingpdf.com/1.5/tags/#D "Direct link to D") ------------------------------------------------------------------ * [database2](https://docs.stirlingpdf.com/1.5/tags/database) * * * E[​](https://docs.stirlingpdf.com/1.5/tags/#E "Direct link to E") ------------------------------------------------------------------ * [enterprise6](https://docs.stirlingpdf.com/1.5/tags/enterprise) * * * F[​](https://docs.stirlingpdf.com/1.5/tags/#F "Direct link to F") ------------------------------------------------------------------ * [feature4](https://docs.stirlingpdf.com/1.5/tags/feature) * * * M[​](https://docs.stirlingpdf.com/1.5/tags/#M "Direct link to M") ------------------------------------------------------------------ * [management4](https://docs.stirlingpdf.com/1.5/tags/management) * * * P[​](https://docs.stirlingpdf.com/1.5/tags/#P "Direct link to P") ------------------------------------------------------------------ * [Premium1](https://docs.stirlingpdf.com/1.5/tags/premium) * [pro5](https://docs.stirlingpdf.com/1.5/tags/pro) * * * U[​](https://docs.stirlingpdf.com/1.5/tags/#U "Direct link to U") ------------------------------------------------------------------ * [UI1](https://docs.stirlingpdf.com/1.5/tags/ui) * * * --- # Database Backups | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > **Tier**: Pro, Enterprise Functionality Overview[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#functionality-overview "Direct link to Functionality Overview") -------------------------------------------------------------------------------------------------------------------------------------------------------------- The newly introduced feature enhances the application with robust database backup and import capabilities. This feature is designed to ensure data integrity and provide a straightforward way to manage database backups. Here's how it works: 1. Automatic Backup Creation * The system automatically creates a database backup every day at midnight. This ensures that there is always a recent backup available, minimizing the risk of data loss. 2. Manual Backup Export * Admin actions that modify the user database trigger a manual export of the database. This keeps the backup up-to-date with the latest changes and provides an extra layer of data security. 3. Importing Database Backups * Admin users can import a database backup either via the web interface or API endpoints. This allows for easy restoration of the database to a previous state in case of data corruption or other issues. * The import process ensures that the database structure and data are correctly restored, maintaining the integrity of the application. 4. Managing Backup Files * Admins can view a list of all existing backup files, along with their creation dates and sizes. This helps in managing storage and identifying the most recent or relevant backups. * Backup files can be downloaded for offline storage or transferred to other environments, providing flexibility in database management. * Unnecessary backup files can be deleted through the interface to free up storage space and maintain an organized backup directory. User Interface[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#user-interface "Direct link to User Interface") -------------------------------------------------------------------------------------------------------------------------------------- ### Web Interface[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#web-interface "Direct link to Web Interface") 1. Upload SQL files to import database backups. 2. View details of existing backups, such as file names, creation dates, and sizes. 3. Download backup files for offline storage. 4. Delete outdated or unnecessary backup files. ### API Endpoints[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#api-endpoints "Direct link to API Endpoints") 1. Import database backups by uploading SQL files. 2. Download backup files. 3. Delete backup files. This new functionality streamlines database management, ensuring that backups are always available and easy to manage, thus improving the reliability and resilience of the application. * [Functionality Overview](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#functionality-overview) * [User Interface](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#user-interface) * [Web Interface](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#web-interface) * [API Endpoints](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE/#api-endpoints) --- # Login, System and Security | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling PDF allows customization of system and security settings. For security features to be enabled, you must use the security jar. For Docker users, this means setting `DISABLE_ADDITIONAL_FEATURES` to `false` via an environment variable. Basic Security Settings[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#basic-security-settings "Direct link to Basic Security Settings") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * `enableLogin`: Enables or disables the login functionality * `csrfDisabled`: Set to 'true' to disable CSRF protection (not recommended for production) * `defaultLocale`: Set the default language (e.g. 'de-DE', 'fr-FR', etc) * `googlevisibility`: 'true' to allow Google visibility (via robots.txt), 'false' to disallow Authentication Setup[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#authentication-setup "Direct link to Authentication Setup") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Prerequisites[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#prerequisites "Direct link to Prerequisites") 1. Ensure the `/configs` directory is mounted as a volume in Docker for persistence across updates 2. For Docker users: Set `DISABLE_ADDITIONAL_FEATURES=false` in environment variables 3. Enable login either via `settings.yml` or set `SECURITY_ENABLELOGIN=true` ### Initial Login Credentials[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#initial-login-credentials "Direct link to Initial Login Credentials") * Default Username: `admin` * Default Password: `stirling` * Note: Users will be forced to change their password on first login * Custom initial credentials can be set using: * `SECURITY_INITIALLOGIN_USERNAME` * `SECURITY_INITIALLOGIN_PASSWORD` ### Database Location[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#database-location "Direct link to Database Location") Upon successful setup, a new `stirling-pdf-DB-2.3.232.mv.db` file will be created in your configured storage location. This file contains user data and should be backed up regularly. ### Account Management[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#account-management "Direct link to Account Management") 1. Access Account Settings: * Click the settings cog menu in the top right navbar * Select "Account Settings" * Here you can manage your profile and find your API key 2. Adding New Users: * Navigate to Account Settings * Scroll to bottom and click 'Admin Settings' * Use the user management interface to add new users ### Role-Based Access Control[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#role-based-access-control "Direct link to Role-Based Access Control") Currently, roles are primarily used for rate limiting purposes. The role system is under active development and will be expanded with additional features in future updates. ### API Authentication[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#api-authentication "Direct link to API Authentication") When using the API: * Each user has a unique API key found in their Account Settings * Include the API key in requests using the `X-API-KEY` header * Example: X-API-KEY: your-api-key-here Configurations Examples ======================= * Settings File * Local Configuration * Docker Run * Docker Compose security: enableLogin: false # set to 'true' to enable login csrfDisabled: truesystem: 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 You can configure these settings in two ways when running locally: **Option 1: Using Java Properties** java -jar Stirling-PDF.jar -DDISABLE_ADDITIONAL_FEATURES=false -DSECURITY_ENABLELOGIN=true **Option 2: Using Environment Variables** export DISABLE_ADDITIONAL_FEATURES=falseexport SECURITY_ENABLELOGIN=true -e DISABLE_ADDITIONAL_FEATURES=false \-e SECURITY_ENABLELOGIN=true \ environment: DISABLE_ADDITIONAL_FEATURES: false true SECURITY_ENABLELOGIN: true * [Basic Security Settings](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#basic-security-settings) * [Authentication Setup](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#authentication-setup) * [Prerequisites](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#prerequisites) * [Initial Login Credentials](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#initial-login-credentials) * [Database Location](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#database-location) * [Account Management](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#account-management) * [Role-Based Access Control](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#role-based-access-control) * [API Authentication](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security/#api-authentication) --- # Google Drive File Picker | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > **Tier**: Pro, Enterprise Stirling-PDF allows users to select Files for processing through tools via google drive. Google Api Access[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#google-api-access "Direct link to Google Api Access") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- To enable this features for your users, you must first set up your Google environment. This includes creating a Google Cloud project. Follow the **Setting up your environment** section of [this guide](https://developers.google.com/workspace/drive/picker/guides/overview#setup) to do so. Stirling PDF configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#stirling-pdf-configuration "Direct link to Stirling PDF configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ premium: ... enabled: true # Enable license key checks for pro/enterprise features proFeatures: ... googleDrive: enabled: true clientId: apiKey: appId: * `premium.enabled`: Set to `true` to enable premium features. * `googleDrive.enabled`: Set to `true` to enable google drive file picker features. * `googleDrive.clientId`: Your Google web app's client ID. [Go to Credentials](https://console.cloud.google.com/apis/credentials) and Click **Create credentials > OAuth client ID**. * `googleDrive.apiKey`: API key for google api access. [Go to Credentials](https://console.cloud.google.com/apis/credentials) and Click **Create credentials > API key**. * `googleDrive.appId`: Google drive app ID also known as your Project Number Found in your [IAM&Admin Project Settings](https://console.cloud.google.com/iam-admin/settings) > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _You must set the Authroized Javascript origins for your OAuth client ID to include your Stirling PDF host domain or IP address._ Configurations Examples[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#configurations-examples "Direct link to Configurations Examples") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Below are examples of the full configuration for enabling the google Drive Picker: * Settings File * Local Environment * Docker Run * Docker Compose premium: enabled: true # Enable license key checks for pro/enterprise features proFeatures: googleDrive: enabled: true clientId: apiKey: appId: export PREMIUM_ENABLED=trueexport PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED=trueexport PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID=""export PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY=""export PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID="" -e PREMIUM_ENABLED=true \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED=true \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID="" \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY="" \-e PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID="" \ environment: PREMIUM_ENABLED: true PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_ENABLED: true PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_CLIENT_ID: PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_API_KEY: PREMIUM_PRO_FEATURES_GOOGLE_DRIVE_APP_ID: * [Google Api Access](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#google-api-access) * [Stirling PDF configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#stirling-pdf-configuration) * [Configurations Examples](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker/#configurations-examples) --- # Endpoints Customisation | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Endpoint%20or%20Feature%20Customisation/#__docusaurus_skipToContent_fallback) Version: 1.6.0 You can selectively disable and remove endpoints and functionalities from Stirling PDF as per your requirements. There are many use-cases for this such as * Avoid confusion for users for functionality you/your business don't use. * Running a reduced version of Stirling-PDF that doesn't have the necessary server power to support the more advanced features. * Cleanup interface for features you don't use To do this `ENDPOINTS_TOREMOVE` and `ENDPOINTS_GROUPSTOREMOVE` have been set up. They can include comma-separated lists of endpoints and groups to disable. For example, `ENDPOINTS_TOREMOVE=img-to-pdf,remove-pages` would disable both the "image to PDF" and "remove pages" functionalities. `ENDPOINTS_GROUPSTOREMOVE=Libre` Would disable a group of endpoints, in this case all endpoints which use Libre in the backend. --- # 4 docs tagged with "management" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/management/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE) Tier: Pro, Enterprise [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker) Tier: Pro, Enterprise [Single Sign-On (SSO) Configuration\ ----------------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) Tier: Pro, Enterprise [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring) Tier: Pro, Enterprise --- # Usage Monitoring | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page > **Tier**: Pro, Enterprise Stirling-PDF provides robust usage monitoring capabilities through its API, allowing you to track application usage patterns and performance metrics. Non-Persistent Usage Monitoring API[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#non-persistent-usage-monitoring-api "Direct link to Non-Persistent Usage Monitoring API") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following API endpoints are available to all users to monitor usage statistics. These endpoints provide non-persistent usage data that can be queried on demand. | Endpoint | Description | | --- | --- | | `GET /api/v1/info/status` | Application status and version information | | `GET /api/v1/info/requests` | Total count of POST requests for a specific endpoint (optional query parameter: `endpoint`) | | `GET /api/v1/info/requests/unique` | Count of unique users for POST requests for a specific endpoint | | `GET /api/v1/info/requests/all` | POST requests count for all endpoints | | `GET /api/v1/info/requests/all/unique` | Unique users count for POST requests for all endpoints | | `GET /api/v1/info/load` | Total count of GET requests for a specific endpoint (optional query parameter: `endpoint`) | | `GET /api/v1/info/load/unique` | Count of unique users for GET requests for a specific endpoint | | `GET /api/v1/info/load/all` | GET requests count for all endpoints | | `GET /api/v1/info/load/all/unique` | Unique users count for GET requests for all endpoints | All endpoints return a JSON response with the requested statistics. Enterprise Usage Monitoring[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#enterprise-usage-monitoring "Direct link to Enterprise Usage Monitoring") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > #### ⚠️ Enterprise Feature[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#%EF%B8%8F-enterprise-feature "Direct link to ⚠️ Enterprise Feature") > > The `/usage` endpoint with graphical displays and the Prometheus integration are enterprise-only features. These features require both an enterprise license (`enterpriseEnabled: true`) and must be explicitly enabled in your configuration. ### Usage Dashboard[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#usage-dashboard "Direct link to Usage Dashboard") Enterprise license holders can access the enhanced usage monitoring dashboard at: /usage This dashboard provides graphical representations and detailed tables of the usage data, similar to the Endpoint Statistics interface shown in the documentation. Prometheus Monitoring Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#prometheus-monitoring-configuration "Direct link to Prometheus Monitoring Configuration") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Stirling-PDF supports application metrics monitoring using Prometheus. This feature allows you to track application performance, usage patterns, and health metrics. ### Prerequisites[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#prerequisites "Direct link to Prerequisites") 1. A valid Stirling-PDF enterprise license 2. Enterprise mode enabled in your configuration 3. Running with Security jar / DOCKER\_ENABLE\_SECURITY flag ### Settings[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#settings "Direct link to Settings") Stirling-PDF can be configured to use Prometheus monitoring by setting the `JAVA_CUSTOM_OPTS` environment variable. The application uses this variable to add custom Java options at runtime. Set the following environment variable in your deployment environment: JAVA_CUSTOM_OPTS="-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true" This configures: * Prometheus metrics endpoint exposure * Health and info endpoints for basic monitoring * Detailed health information * Prometheus metrics export * Enterprise metrics collection ### Configuration in custom\_settings.yml[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#configuration-in-custom_settingsyml "Direct link to Configuration in custom_settings.yml") Alternatively, you can configure these settings in your `/configs/custom_settings.yml` file: management: endpoints: web: exposure: include: prometheus,health,info endpoint: health: show-details: always metrics: export: prometheus: enabled: trueenterprisemanagement: metrics: enabled: true ### Accessing Metrics[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#accessing-metrics "Direct link to Accessing Metrics") Once configured, Prometheus metrics are available at the following endpoint: https://your-stirling-pdf-instance/actuator/prometheus This endpoint provides metrics in a format that can be scraped by a Prometheus server. ### Configuring Prometheus Server[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#configuring-prometheus-server "Direct link to Configuring Prometheus Server") Add the following job configuration to your Prometheus server's configuration file (`prometheus.yml`): scrape_configs: - job_name: 'stirling-pdf' metrics_path: '/actuator/prometheus' scrape_interval: 15s static_configs: - targets: ['your-stirling-pdf-host:port'] ### Available Metrics[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#available-metrics "Direct link to Available Metrics") With Prometheus integration enabled, Stirling-PDF exposes the following types of metrics: * **JVM metrics**: Memory usage, garbage collection, thread utilization * **System metrics**: CPU usage, file descriptors * **Application metrics**: Request rates, processing times * **PDF processing metrics**: Document operations, conversion statistics * [Non-Persistent Usage Monitoring API](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#non-persistent-usage-monitoring-api) * [Enterprise Usage Monitoring](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#enterprise-usage-monitoring) * [Usage Dashboard](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#usage-dashboard) * [Prometheus Monitoring Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#prometheus-monitoring-configuration) * [Prerequisites](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#prerequisites) * [Settings](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#settings) * [Configuration in custom\_settings.yml](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#configuration-in-custom_settingsyml) * [Accessing Metrics](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#accessing-metrics) * [Configuring Prometheus Server](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#configuring-prometheus-server) * [Available Metrics](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring/#available-metrics) --- # 4 docs tagged with "advanced feature" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/advanced-feature/#__docusaurus_skipToContent_fallback) [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker) Tier: Pro, Enterprise [Single Sign-On (SSO) Configuration\ ----------------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) Tier: Pro, Enterprise [UI Customisation\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own. [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring) Tier: Pro, Enterprise --- # 2 docs tagged with "database" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/database/#__docusaurus_skipToContent_fallback) [Database Backups\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/DATABASE) Tier: Pro, Enterprise [External Database\ -----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/External%20Database) Tier: Enterprise --- # 4 docs tagged with "feature" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/feature/#__docusaurus_skipToContent_fallback) [Google Drive File Picker\ ------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Google%20Drive%20File%20Picker) Tier: Pro, Enterprise [Single Sign-On (SSO) Configuration\ ----------------------------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Single%20Sign-On%20Configuration) Tier: Pro, Enterprise [UI Customisation\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own. [Usage Monitoring\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Usage%20Monitoring) Tier: Pro, Enterprise --- # Pipeline Automation | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page * Configure the pipeline config file and input files to run files against it. * For reuse, download the config file and re-upload it when needed, or place it in `/pipeline/defaultWebUIConfigs/` to auto-load in the web UI for all users. Steps to Configure and Use Your Pipeline[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline/#steps-to-configure-and-use-your-pipeline "Direct link to Steps to Configure and Use Your Pipeline") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. **Access Configuration** * Upon entering the screen, click on the **Configure** button. 2. **Enter Pipeline Name** * Provide a name for your pipeline in the designated field. 3. **Select Operations** * Choose the operations for your pipeline (e.g., **Split Pages**), then click **Add Operation**. 4. **Configure Operation Settings** * Input the necessary settings for each added operation. Settings are highlighted in yellow if customization is needed. 5. **Add More Operations** * You can add and adjust the order of multiple operations. Ensure each operation's settings are customized. 6. **Save Settings** * Click **Save Operation Settings** after customizing settings for each operation. 7. **Validate Pipeline** * Use the **Validation** button to check your pipeline. A green indicator signifies correct setup; a pop-out error indicates issues. 8. **Download Pipeline Configuration** * To use the configuration for [folder scanning](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning) (or save it for future use and re-upload it), download a JSON file in this menu. You can also pre-load it for future use by placing it in `/pipeline/defaultWebUIConfigs/`. It will then appear in the dropdown menu for all users to use. 9. **Submit Files for Processing** * If your pipeline is correctly set up, close the configure menu, input the files, and hit **Submit**. 10. **Note on Web UI Limitations** * The current web UI version does not support operations that require multiple different types of inputs, such as adding a separate image to a PDF. ### Current Limitations[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline/#current-limitations "Direct link to Current Limitations") * Cannot have more than one of the same operation. * Cannot input additional files via UI. * All files and operations run in serial mode. * [Steps to Configure and Use Your Pipeline](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline/#steps-to-configure-and-use-your-pipeline) * [Current Limitations](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline/#current-limitations) --- # OCR (Optical Character Recognition) | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page This document provides instructions on how to add additional language packs for the OCR tab in Stirling-PDF, both inside and outside of Docker. How does the OCR Work[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#how-does-the-ocr-work "Direct link to How does the OCR Work") ------------------------------------------------------------------------------------------------------------------------------------------------------ Stirling-PDF uses Tesseract for its text recognition. All credit goes to them for this awesome work! Language Packs[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#language-packs "Direct link to Language Packs") --------------------------------------------------------------------------------------------------------------------------------- Tesseract OCR supports a variety of languages. You can find additional language packs in the Tesseract GitHub repositories: * [tessdata\_fast](https://github.com/tesseract-ocr/tessdata_fast) : These language packs are smaller and faster to load but may provide lower recognition accuracy. * [tessdata](https://github.com/tesseract-ocr/tessdata) : These language packs are larger and provide better recognition accuracy, but may take longer to load. Depending on your requirements, you can choose the appropriate language pack for your use case. By default, Stirling-PDF uses `tessdata_fast` for English, but this can be replaced. ### Installing Language Packs manually[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#installing-language-packs-manually "Direct link to Installing Language Packs manually") 1. Download the desired language pack(s) by selecting the `.traineddata` file(s) for the language(s) you need. 2. Place the `.traineddata` files in the Tesseract tessdata directory: `/usr/share/tessdata` (or equivalent) **DO NOT REMOVE EXISTING `eng.traineddata`, IT'S REQUIRED.** ### Docker Setup[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#docker-setup "Direct link to Docker Setup") If you are using Docker, you need to expose the Tesseract tessdata directory as a volume in order to use the additional language packs. * Docker Compose * Docker Run Modify your `docker-compose.yml` file to include the following volume configuration: services: your_service_name: image: your_docker_image_name volumes: - /location/of/trainingData:/usr/share/tessdata Add the following to your existing Docker run command: -v /location/of/trainingData:/usr/share/tessdata ### Non-Docker Setup[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#non-docker-setup "Direct link to Non-Docker Setup") * Debian-based Systems * Fedora * Windows For Debian-based systems, use the following commands to manage Tesseract languages: sudo apt update &&\# All languages# sudo apt install -y 'tesseract-ocr-*'# Find available languages:apt search tesseract-ocr-# View installed languages:dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g' For Fedora systems, use the following commands: # All languages# sudo dnf install -y tesseract-langpack-*# Find available languages:dnf search -C tesseract-langpack-# View installed languages:rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g' Follow these steps to set up Tesseract languages on Windows: 1. Download desired `.traineddata` files from [tessdata](https://github.com/tesseract-ocr/tessdata) or [tessdata\_fast](https://github.com/tesseract-ocr/tessdata_fast) 2. Place them in the tessdata folder within your Tesseract installation directory: C:\Program Files\Tesseract-OCR\tessdata 3. Verify the installation by running: tesseract --list-langs 4. Edit your `/configs/settings.yml` and update the `system.tessdataDir`: system: tessdataDir: C:/Program Files/Tesseract-OCR/tessdata # path to Tessdata files * [How does the OCR Work](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#how-does-the-ocr-work) * [Language Packs](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#language-packs) * [Installing Language Packs manually](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#installing-language-packs-manually) * [Docker Setup](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#docker-setup) * [Non-Docker Setup](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/OCR/#non-docker-setup) --- # Folder Scanning | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page User Guide for Local Directory Scanning and File Processing[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#user-guide-for-local-directory-scanning-and-file-processing "Direct link to User Guide for Local Directory Scanning and File Processing") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Folder scanning uses settings configured from our pipeline tool, it is advised you first read the [Pipeline Guide](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline) ### Setting Up Watched Folders[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#setting-up-watched-folders "Direct link to Setting Up Watched Folders") * Create a folder where you want your files to be monitored. This is your 'watched folder'. * The default directory for this is `./pipeline/watchedFolders/`. * Place any directories you want to be scanned into this folder. This folder should contain multiple folders, each for their own tasks and pipelines. ### Configuring Processing with JSON Files[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#configuring-processing-with-json-files "Direct link to Configuring Processing with JSON Files") * In each directory you want processed (e.g., `./pipeline/watchedFolders/officePrinter`), include a JSON configuration file. * This JSON file should specify how you want the files in the directory to be handled (e.g., what operations to perform on them). This can be made, configured, and downloaded from the Stirling-PDF Pipeline interface. For JSON creation guide please see [Pipeline setup](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Pipeline) ### Automatic Scanning and Processing[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#automatic-scanning-and-processing "Direct link to Automatic Scanning and Processing") * The system automatically checks the watched folder every minute for new directories and files to process. * When a directory with a valid JSON configuration file is found, it begins processing the files inside according to the configuration. ### Processing Steps[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#processing-steps "Direct link to Processing Steps") * Files in each directory are processed according to the instructions in the JSON file. * This might involve file conversions, data filtering, renaming files, etc. If the output of a step is a zip, this zip will be automatically unzipped as it passes to the next process. ### Results and Output[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#results-and-output "Direct link to Results and Output") * After processing, the results are saved in a specified output location. This could be a different folder or location as defined in the JSON file or the default location `./pipeline/finishedFolders/`. * Each processed file is named and organized according to the rules set in the JSON configuration. ### Completion and Cleanup[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#completion-and-cleanup "Direct link to Completion and Cleanup") * Once processing is complete, the original files in the watched folder's directory are removed. * You can find the processed files in the designated output location. ### Error Handling[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#error-handling "Direct link to Error Handling") * If there's an error during processing, the system will not delete the original files, allowing you to check and retry if necessary. ### User Interaction[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#user-interaction "Direct link to User Interaction") * As a user, your main tasks are to set up the watched folders, place directories with files for processing, and create the corresponding JSON configuration files. * The system handles the rest, including scanning, processing, and outputting results. * [User Guide for Local Directory Scanning and File Processing](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#user-guide-for-local-directory-scanning-and-file-processing) * [Setting Up Watched Folders](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#setting-up-watched-folders) * [Configuring Processing with JSON Files](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#configuring-processing-with-json-files) * [Automatic Scanning and Processing](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#automatic-scanning-and-processing) * [Processing Steps](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#processing-steps) * [Results and Output](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#results-and-output) * [Completion and Cleanup](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#completion-and-cleanup) * [Error Handling](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#error-handling) * [User Interaction](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Folder%20Scanning/#user-interaction) --- # One doc tagged with "UI" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/ui/#__docusaurus_skipToContent_fallback) [UI Customisation\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own. --- # Custom Settings Configuration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page Stirling-PDF provides a `/configs/custom_settings.yml` file where users can configure additional settings beyond the standard configuration. This file follows standard YAML format and supports Spring Boot application properties, allowing you to customize the application without modifying core files. Logging Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#logging-configuration "Direct link to Logging Configuration") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- Control the verbosity of logs by adjusting log levels for different components: logging: level: root: INFO org.springframework: WARN org.hibernate: WARN org.eclipse.jetty: WARN stirling.software.SPDF: INFO # Enable debug logging for specific components when troubleshooting # org.springframework.security.saml2: TRACE # org.springframework.security: DEBUG # org.opensaml: DEBUG Server Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#server-configuration "Direct link to Server Configuration") -------------------------------------------------------------------------------------------------------------------------------------------------------------- Configure server behavior including port, address binding, and session timeout: server: port: 8080 # Default port address: 0.0.0.0 # Bind to all interfaces servlet: context-path: / # Application context path session: timeout: 30m # Session timeout jetty: threads: max: 200 # Maximum number of request processing threads min: 10 # Minimum number of threads always kept running connection-idle-timeout: 30000 # Connection idle timeout in milliseconds SSL/TLS Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#ssltls-configuration "Direct link to SSL/TLS Configuration") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Configure HTTPS for secure connections: server: port: 8443 # Standard HTTPS port ssl: enabled: true key-store: classpath:keystore.p12 # Path to keystore file key-store-password: your-keystore-password key-store-type: PKCS12 # Type of keystore key-alias: tomcat # Alias of the certificate ### Creating a Self-Signed Certificate[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#creating-a-self-signed-certificate "Direct link to Creating a Self-Signed Certificate") To generate a self-signed certificate for development or testing: keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 365 > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#%EF%B8%8F-note "Direct link to ⚠️ Note") > > _For production use, it's recommended to use a certificate from a trusted Certificate Authority._ Configuration Examples[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#configuration-examples "Direct link to Configuration Examples") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Basic Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#basic-configuration "Direct link to Basic Configuration") A simple configuration that changes the port and adjusts logging levels: # custom_settings.ymlserver: port: 9000logging: level: root: INFO org.springframework: WARN org.hibernate: WARN stirling.software.SPDF: INFO ### HTTPS Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#https-configuration "Direct link to HTTPS Configuration") Enable HTTPS with a custom certificate: # custom_settings.ymlserver: port: 8443 ssl: enabled: true key-store: classpath:keystore.p12 key-store-password: your-keystore-password key-store-type: PKCS12 key-alias: tomcatlogging: level: root: INFO org.springframework: WARN Troubleshooting Common Issues[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#troubleshooting-common-issues "Direct link to Troubleshooting Common Issues") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Authentication Issues[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#authentication-issues "Direct link to Authentication Issues") Increase security logging to diagnose authentication problems: logging: level: org.springframework.security: DEBUG stirling.software.SPDF.config.security: DEBUG ### SAML/OAuth Issues[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#samloauth-issues "Direct link to SAML/OAuth Issues") Increase SAML-related logging for SSO troubleshooting: logging: level: org.springframework.security.saml2: TRACE org.springframework.security.oauth2: DEBUG org.opensaml: DEBUG ### General Application Issues[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#general-application-issues "Direct link to General Application Issues") For general application issues: logging: level: stirling.software.SPDF: DEBUG > #### ⚠️ Note[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#%EF%B8%8F-note-1 "Direct link to ⚠️ Note") > > _Debug-level logging can significantly increase log volume and may impact performance in production environments. Return logging to normal levels after troubleshooting._ * [Logging Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#logging-configuration) * [Server Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#server-configuration) * [SSL/TLS Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#ssltls-configuration) * [Creating a Self-Signed Certificate](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#creating-a-self-signed-certificate) * [Configuration Examples](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#configuration-examples) * [Basic Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#basic-configuration) * [HTTPS Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#https-configuration) * [Troubleshooting Common Issues](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#troubleshooting-common-issues) * [Authentication Issues](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#authentication-issues) * [SAML/OAuth Issues](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#samloauth-issues) * [General Application Issues](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/Extra-Settings/#general-application-issues) --- # One doc tagged with "customisation" | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/tags/customisation/#__docusaurus_skipToContent_fallback) [UI Customisation\ ----------------](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/UI%20Customisation) Stirling PDF allows straightforward customization of the application name and appearance to make Stirling-PDF your own. --- # Fail2Ban Integration | Stirling PDF ![x](https://static.scarf.sh/a.png?x-pxid=5d074971-2ecb-4c54-8397-30c0f91896b3) [Skip to main content](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#__docusaurus_skipToContent_fallback) Version: 1.6.0 On this page This document provides instructions on how to set up Fail2Ban with Stirling-PDF to protect against unauthorized login attempts. (Note Stirling-PDF blocks IPs after a set retry count regardless of Fail2Ban, This configuration is only useful for users specifically wanting Fail2Ban configuration) How does Fail2Ban Work with Stirling-PDF[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#how-does-fail2ban-work-with-stirling-pdf "Direct link to How does Fail2Ban Work with Stirling-PDF") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Stirling-PDF logs failed authentication attempts to a log file which Fail2Ban monitors. When it detects multiple failed login attempts from the same IP address, Fail2Ban automatically blocks that IP address for a configured period of time. Prerequisites[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------------------------------- * Fail2Ban installed on your system * Access to Stirling-PDF log directory * Security settings configured in `/configs/settings.yml`: security: enableLogin: true # Login must be enabled for Fail2Ban integration loginAttemptCount: -1 # Set to -1 when using Fail2Ban recommended but not required ### Important Configuration Notes[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#important-configuration-notes "Direct link to Important Configuration Notes") * The `enableLogin` setting must be set to `true` as Fail2Ban integration requires authentication to be active * When using Fail2Ban, set `loginAttemptCount` to `-1` to disable the built-in account locking mechanism and let Fail2Ban handle login attempt management * For more details on security configuration options, refer to the [System and Security](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/System%20and%20Security) documentation Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#configuration "Direct link to Configuration") ----------------------------------------------------------------------------------------------------------------------------------- ### Log File Location[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#log-file-location "Direct link to Log File Location") The log file location containing the failed authentication messages depends on your installation type: * **Default/Docker Installation**: `./logs/invalid-auths.log` * **Windows Desktop**: `%APPDATA%\Stirling-PDF\logs\invalid-auths.log` * **MacOS Desktop**: `~/Library/Application Support/Stirling-PDF/logs/invalid-auths.log` * **Linux Desktop**: `~/.config/Stirling-PDF/logs/invalid-auths.log` ### Example Fail2Ban Filter[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#example-fail2ban-filter "Direct link to Example Fail2Ban Filter") `/etc/fail2ban/filter.d/stirling-pdf.conf` [Definition]failregex = Failed login attempt from IP: ### Example Jail Configuration[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#example-jail-configuration "Direct link to Example Jail Configuration") `/etc/fail2ban/jail.local` [stirling-pdf]enabled = truefilter = stirling-pdflogpath = /logs/invalid-auths.logmaxretry = 5findtime = 300bantime = 3600 Configuration parameters: * `maxretry`: Number of failed attempts before ban (default: 5) * `findtime`: Time window for failed attempts in seconds (default: 300 seconds / 5 minutes) * `bantime`: Duration of the ban in seconds (default: 3600 seconds / 1 hour) ### Ensure access to Logs path[​](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#ensure-access-to-logs-path "Direct link to Ensure access to Logs path") * Docker Compose * Docker Run Modify your `docker-compose.yml` to expose the log directory: services: stirling-pdf: volumes: - ./logs:/logs Add the volume mount to your Docker run command: -v ./logs:/logs * [How does Fail2Ban Work with Stirling-PDF](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#how-does-fail2ban-work-with-stirling-pdf) * [Prerequisites](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#prerequisites) * [Important Configuration Notes](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#important-configuration-notes) * [Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#configuration) * [Log File Location](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#log-file-location) * [Example Fail2Ban Filter](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#example-fail2ban-filter) * [Example Jail Configuration](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#example-jail-configuration) * [Ensure access to Logs path](https://docs.stirlingpdf.com/1.5/Advanced%20Configuration/fail2ban/#ensure-access-to-logs-path) ---