Skip to main content

Configuration Guide

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

Configuration Methods​

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 \
  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:

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

Configure user login:

security:
  enableLogin: true
  initialLogin:
    username: admin
    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

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

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​

x