Configuration Guide

Stirling PDF can be configured in three ways, depending on your deployment and preferences.

Configuration Methods#

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#

Configure via Docker environment variables or system environment variables.

To use:

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

Best for: Docker deployments, infrastructure-as-code, initial setup

3. Settings File (settings.yml)#

Edit /configs/settings.yml directly for advanced configuration.

To use:

security:
  enableLogin: true
system:
  defaultLocale: en-US

Best for: Complex configurations, when you prefer file-based config

Common Settings#

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 (Recommended)

The plain Stirling-PDF.jar does not include authentication or additional features.

Configure user login:

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

SECURITY_ENABLELOGIN=true
SECURITY_INITIALLOGIN_USERNAME=admin
SECURITY_INITIALLOGIN_PASSWORD=changeme123

Default credentials: admin / stirling (change immediately after first login)

For more details, see System and Security Configuration.

Language & Localization#

ui:
  languages: []        # Available languages (empty = all enabled), e.g. ["en_US", "de_DE"]
system:
  defaultLocale: en-US # Default language for new users

UI_LANGUAGES=en_US,de_DE       # Restrict available languages (omit to enable all)
SYSTEM_DEFAULTLOCALE=en-US     # Default language

Leaving defaultLocale empty (the default) auto-detects the language from the browser and falls back to en-US if no preference is found.

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. System default locale

   • Set via SYSTEM_DEFAULTLOCALE or system.defaultLocale
   • When configured, it overrides the browser's detected language for users who have not made a manual selection

3. Browser's language preference

   • Automatically detected from the browser's language setting
   • Example: Firefox set to Swedish (sv-SE) shows Swedish UI when no defaultLocale is configured

4. Fallback (lowest priority)

   • en-US is used when none of the above resolve to an available language

Example:

• Config: SYSTEM_DEFAULTLOCALE=en-US
• Browser: Swedish (sv-SE)
• Result: UI shows English (US) (the configured default overrides the browser preference)

If defaultLocale is left empty (the default), the browser-detected language is used instead. Users can always override either choice by manually selecting a language 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#

system:
  fileUploadLimit: "500MB"  # Number (0-999) followed by KB, MB, or GB. Empty = no limit
spring:
  servlet:
    multipart:
      max-file-size: 2000MB
      max-request-size: 2000MB

SYSTEM_MAXFILESIZE=500        # Size in MB (valid range 1-999)
SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=2000MB
SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=2000MB

Memory Management#

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

Specialized Configuration Guides#

For advanced features and specific use cases, see these detailed guides:

Authentication & Security#

Single Sign-On (SSO)

• OAuth2 (Google, GitHub, Keycloak, OIDC) - Server tier
• SAML2 (Okta, Azure AD) - Enterprise tier
• Complete configuration examples

System and Security

• Server certificates
• JWT configuration

Fail2Ban Integration

• Protect against brute-force attacks
• Auto-ban after failed login attempts

Features & Customization#

UI Customization

• Branding and logos
• Theme customization
• Custom styling

Endpoint/Feature Control

• Enable/disable specific tools
• Control feature availability by user/role

Pipeline (Automation)

• Automated workflows
• Folder scanning
• Batch processing
• Multi-step operations

Integration & Storage#

External Database

• PostgreSQL configuration (Pro/Enterprise)
• Database migration
• Backup strategies

Google Drive File Picker

• Direct Google Drive integration
• OAuth setup

MCP Server

• Expose Stirling PDF tools over the Model Context Protocol
• OAuth2 or API-key authentication
• Operation allow/deny lists

S3 / Object Storage

• Store uploads and job artifacts in S3-compatible object storage
• Shared storage for multi-node deployments

Telegram Bot

• Run a Telegram bot that processes PDFs sent in chat

OCR Configuration

• Tesseract language packs
• OCR optimization

Usage Monitoring

• Prometheus metrics (Pro/Enterprise)
• Application monitoring
• Performance tracking

Performance & Scaling#

Performance Optimization & Sizing

• Resource sizing, JVM tuning, memory model, and scaling guidance

Process Limits

• Session limits and timeouts for external tools

LibreOffice Parallel Processing

• Configure multiple LibreOffice instances for faster document conversion
• Local UNO server pool and remote UNO server endpoints

Diagnostics & Support#

Diagnostics & Reporting Issues

• Built-in diagnostics tool for Docker containers
• How to report issues via GitHub, Discord, and email

Other Configuration#

Folder Scanning

• Watch folders for automatic processing

Custom Signature Files

• Pre-loaded signatures for quick signing

Extra Settings

• Logging configuration
• Server settings (port, SSL/TLS)
• Advanced Spring Boot settings

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#

Convert YAML paths to environment variables:

# settings.yml
security:
  enableLogin: true

Becomes:

SECURITY_ENABLELOGIN=true

Rules:

• Uppercase everything
• Replace . with _
• Nested properties become PARENT_CHILD

Troubleshooting#

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#

Default database location: /configs/stirling-pdf-DB-<schema-version>.mv.db (the schema version is part of the filename, e.g. /configs/stirling-pdf-DB-2.3.232.mv.db).

If missing:

• Ensure /configs volume is mounted
• Check write permissions
• Review startup logs

Next Steps#

• Production Deployment: See Production Deployment Guide
• API Usage: See API Documentation
• Tool Reference: See Functionality
• Troubleshooting: See Diagnostics & Reporting Issues