x
Skip to main content

Settings Changes from V1 to V2

This page documents all settings.yml changes between V1 and V2.

New Settings in V2​

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 | Security Configuration

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 | Certificate Configuration

Split Deployment Support​

New settings added:

system:
  corsAllowedOrigins: [] # NEW in V2
  frontendUrl: '' # NEW in V2

What it does:

  • corsAllowedOrigins: Allow frontend from different origin
  • frontendUrl: Base URL for generating invite links

Migration: Leave empty for unified deployment (default).

Example split deployment:

system:
  corsAllowedOrigins: ['https://pdf.example.com']
  frontendUrl: 'https://pdf.example.com'

Learn more: Docker Installation - Split Mode

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​

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​

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​

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

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​

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​

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​

Use this checklist when upgrading your settings.yml:

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​

  • 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
  • Add system.corsAllowedOrigins if using split deployment
  • Set system.frontendUrl if using split deployment
  • Enable mail.enableInvites if you want email invitations

Environment Variable Changes​

New Environment Variables in V2​

# Signature validation
SECURITY_VALIDATION_TRUST_SERVERASANCHOR=true
SECURITY_VALIDATION_TRUST_USESYSTEMTRUST=true
SECURITY_VALIDATION_TRUST_USEMOZILLABUNDLE=true
SECURITY_VALIDATION_TRUST_USEAATL=false
SECURITY_VALIDATION_TRUST_USEEUTL=false
SECURITY_VALIDATION_REVOCATION_MODE=none

# Server certificates
SYSTEM_SERVERCERTIFICATE_ENABLED=true
SYSTEM_SERVERCERTIFICATE_ORGANIZATIONNAME="My Company"
SYSTEM_SERVERCERTIFICATE_VALIDITY=365

# Split deployment
SYSTEM_CORSALLOWEDORIGINS=https://pdf.example.com
SYSTEM_FRONTENDURL=https://pdf.example.com

# JWT
SECURITY_JWT_PERSISTENCE=true
SECURITY_JWT_ENABLEKEYROTATION=true
SECURITY_JWT_ENABLEKEYCLEANUP=true

# Email invites
MAIL_ENABLEINVITES=true

# Logo
UI_LOGOSTYLE=modern

Deprecated Environment Variables​

# These no longer work in V2
SECURITY_JWT_ENABLED  # Use SECURITY_JWT_PERSISTENCE
SECURITY_JWT_KEYCLEANUP  # Use SECURITY_JWT_ENABLEKEYCLEANUP
SECURITY_JWT_SECURECOOKIE  # Removed
UI_APPNAME  # Use in-app settings
UI_HOMEDESCRIPTION  # Use in-app settings

Configuration Examples​

Minimal V2 Configuration (Works Out of Box)​

security:
  enableLogin: false

system:
  defaultLocale: en-US

ui:
  appNameNavbar: ''

All new V2 features use sensible defaults.

V1 to V2 Configuration Diff​

V1 Configuration:

security:
  jwt:
    enabled: false
    keyCleanup: false
    secureCookie: true

ui:
  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: true

system:
  serverCertificate:  # NEW section
    enabled: true
    organizationName: Stirling-PDF

ui:
  appNameNavbar: 'PDF Tool'
  logoStyle: classic  # NEW
  # appName and homeDescription removed - use in-app settings

Troubleshooting​

"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​

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​

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

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!