How to Configure Stirling-PDF via YAML Settings Files

Stirling-PDF reads its entire runtime configuration from a YAML file named settings.yml, which is automatically created from a bundled template and loaded into Spring's environment through the ApplicationProperties class.

The open-source Stirling-Tools/Stirling-PDF repository uses a hierarchical YAML configuration system that allows you to control everything from upload limits to OAuth2 authentication without modifying code. This guide explains how to configure Stirling-PDF via YAML settings files by examining the actual source implementation, including the ConfigInitializer class that manages file creation and the ApplicationProperties POJOs that map YAML properties to Java objects.

Understanding the YAML Configuration Architecture

Stirling-PDF's configuration system relies on three core components working together at startup:

1. Template file: app/core/src/main/resources/settings.yml.template contains the default configuration values shipped with the application.

2. ConfigInitializer: This class (app/common/src/main/java/stirling/software/common/configuration/ConfigInitializer.java) ensures that settings.yml exists in the file system. If the file is missing, it copies the template. If the file exists but new defaults have been added to the template, it merges those new keys into the existing user file while preserving custom values.

3. ApplicationProperties: Located at app/common/src/main/java/stirling/software/common/model/ApplicationProperties.java, this class defines nested POJOs (Plain Old Java Objects) that mirror the YAML hierarchy. The dynamicYamlPropertySource() bean (lines 78-99) registers the YAML file as a Spring PropertySource, making every property available for dependency injection.

Configuration File Locations and Structure

Primary Configuration File (settings.yml)

The physical location of settings.yml is determined by InstallationPathConfig.getSettingsPath(), which defaults to ./configs/settings.yml relative to the application working directory. You can verify the exact path in the source at app/common/src/main/java/stirling/software/common/configuration/InstallationPathConfig.java (lines 44-46).

This file contains the complete configuration hierarchy:

system:
  defaultLocale: "en-GB"
  fileUploadLimit: "100MB"
  enableAnalytics: true
  enablePosthog: true

ui:
  appNameNavbar: "Stirling PDF"
  languages:
    - en-GB
    - de-DE
  logoStyle: "classic"

security:
  enableLogin: true
  loginMethod: "all"
  oauth2:
    enabled: false
    issuer: ""
    clientId: ""
    clientSecret: ""

pdfEditor:
  cache:
    maxBytes: -1
    maxPercent: 20
  fontNormalization:
    enabled: false

premium:
  enabled: false
  key: ""

Custom Overrides (custom_settings.yml)

Stirling-PDF also creates an empty custom_settings.yml file in the same directory (./configs/custom_settings.yml). You can place any additional properties or overrides in this file, which is loaded alongside the main configuration. This separation allows you to keep sensitive data or environment-specific tweaks isolated from the main settings.yml that might be version-controlled or shared.

Environment Variable Overrides

Specific properties can be overridden via environment variables, which take precedence over YAML values. The ApplicationProperties.initializeFileUploadLimitFromEnv() method (lines 1010-1047) checks for:

• SYSTEMFILEUPLOADLIMIT – Sets the system.fileUploadLimit value
• SYSTEM_MAXFILESIZE – Plain number in MB, also mapped to upload limits

For example, to set a 500MB limit via Docker:

docker run -e SYSTEMFILEUPLOADLIMIT=500MB stirling-pdf

Step-by-Step Configuration Setup

Follow these steps to configure Stirling-PDF via YAML settings files:

1. Locate or create the config directory:

   mkdir -p ./configs

2. Copy the template (only required for manual setup; the application creates this automatically on first run):

   cp app/core/src/main/resources/settings.yml.template configs/settings.yml

3. Edit the configuration:

   nano configs/settings.yml

   Modify values such as system.fileUploadLimit, ui.appNameNavbar, or security.enableLogin according to your requirements.

4. Add custom overrides (optional): Create or edit configs/custom_settings.yml for environment-specific values that should not be in the main file.

5. Start the application:

   ./gradlew bootRun

   Or using Docker:

   docker run -v $(pwd)/configs:/configs -e SYSTEMFILEUPLOADLIMIT=200MB stirling-pdf

If you upgrade Stirling-PDF later, the ConfigInitializer automatically merges any new default keys from the updated template into your existing settings.yml without overwriting your custom values.

Key Configuration Sections

System Settings

The system block controls core application behavior:

• defaultLocale: Sets the default language (e.g., "en-GB", "de-DE")
• fileUploadLimit: Maximum upload size (e.g., "100MB", "2GB")
• enableAnalytics: Toggle for anonymous usage analytics
• backendUrl: External URL if running behind a reverse proxy

UI Customization

The ui block allows branding changes without code modification:

• appNameNavbar: Display name in the navigation bar
• languages: Array of available language codes
• logoStyle: Choose between "classic" or "modern" logo variants

Security and Authentication

The security block manages access control:

• enableLogin: Boolean to require authentication
• loginMethod: Options include "all", "normal", "oauth2", "saml2"
• oauth2 and saml2: Sub-blocks for SSO configuration (see advanced example below)

PDF Editor Options

The pdfEditor block tunes processing behavior:

• cache.maxPercent: Memory percentage allowed for PDF caching
• fontNormalization.enabled: Convert fonts to prevent embedding issues
• cffConverter.method: Choose between "python" or external tools for CFF font conversion

Advanced Configuration Example (OAuth2)

To enable OAuth2 authentication via Keycloak or similar providers, modify the security section:

security:
  enableLogin: true
  loginMethod: "oauth2"
  oauth2:
    enabled: true
    issuer: "https://login.example.com/realms/stirling"
    clientId: "stirling-client"
    clientSecret: "s3cr3t"
    scopes: "openid,email,profile"
    provider: "keycloak"

The corresponding Java implementation maps these to ApplicationProperties.Security.OAuth2 (lines 51-124 in ApplicationProperties.java), where the enabled boolean triggers the security configuration chain.

Summary

• Primary configuration happens in ./configs/settings.yml, automatically created from settings.yml.template by the ConfigInitializer class.
• YAML structure maps directly to nested POJOs in ApplicationProperties.java, with top-level blocks for system, ui, security, pdfEditor, and premium.
• Environment variables like SYSTEMFILEUPLOADLIMIT can override specific YAML properties.
• Custom overrides can be placed in custom_settings.yml to separate sensitive or environment-specific values from the main configuration.
• Automatic merging preserves your custom values when upgrading Stirling-PDF and new defaults are added to the template.

Frequently Asked Questions

Where is the settings.yml file located?

By default, settings.yml is located at ./configs/settings.yml relative to the application working directory. The exact path is determined by InstallationPathConfig.getSettingsPath() in the source code. If you run Stirling-PDF via Docker, you typically mount a host directory to /configs inside the container.

Can I use environment variables instead of YAML?

Yes. While the YAML file is the primary configuration method, specific properties can be overridden via environment variables. For example, SYSTEMFILEUPLOADLIMIT sets the maximum file upload size, and SYSTEM_MAXFILESIZE (accepting a plain number in MB) also maps to upload limits. These are processed by ApplicationProperties.initializeFileUploadLimitFromEnv() during startup.

How do I update settings after upgrading Stirling-PDF?

You do not need to manually update settings.yml when upgrading. The ConfigInitializer class automatically merges any new default keys from the updated settings.yml.template into your existing settings.yml file during startup. This merge preserves your custom values while adding new configuration options introduced in the newer version.

What happens if I delete the settings.yml file?

If you delete settings.yml, the ConfigInitializer will recreate it on the next application startup by copying the bundled settings.yml.template from the JAR resources. However, you will lose any custom configurations you had previously set. To avoid this, maintain a backup of your settings.yml or use custom_settings.yml for critical overrides that you can preserve separately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}