Skip to 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 LANGS=en_GB \
  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-GB

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

Common Settings

Authentication

Enable user login: 

SECURITY_ENABLELOGIN=true
SECURITY_INITIALLOGIN_USERNAME=admin
SECURITY_INITIALLOGIN_PASSWORD=changeme123

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

Language & Localization

LANGS=en_GB                    # Available languages
SYSTEM_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)
  2. When a user clicks the language globe icon and selects a language
  3. Choice is stored in browser's localStorage (persists across sessions)

  4. Storage key: i18nextLng

  5. Browser's language preference

  6. Automatically detected from browser's Accept-Language header via the navigator API

  7. Example: Firefox set to Swedish (sv-SE) will show Swedish UI

  8. System default locale (lowest priority)

  9. Set via SYSTEM_DEFAULTLOCALE or system.defaultLocale
  10. 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.

Deployment Mode

MODE=BOTH      # Options: BOTH, FRONTEND, BACKEND

File Upload Limits

SYSTEM_MAXFILESIZE=2000        # MB
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) - Enterprise only - SAML2 (Okta, Azure AD) - Enterprise only - Complete configuration examples

System and Security - Split deployment (frontend/backend separation) - CORS configuration - 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

OCR Configuration - Tesseract language packs - OCR optimization

Usage Monitoring - Prometheus metrics (Pro/Enterprise) - Application monitoring - Performance tracking

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.mv.db

If missing: - Ensure /configs volume is mounted - Check write permissions - Review startup logs

Next Steps