x
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 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

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)
  • SAML2 (Okta, Azure AD) - Pro/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​