# How to Configure Stirling-PDF via YAML Settings Files

> Learn to configure Stirling-PDF using YAML settings files. Discover how Stirling-PDF loads application properties from settings.yml for easy customization. Read now.

- Repository: [Stirling Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF)
- Tags: how-to-guide
- Published: 2026-03-01

---

**Stirling-PDF reads its entire runtime configuration from a YAML file named [`settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/common/src/main/java/stirling/software/common/configuration/ConfigInitializer.java)) ensures that [`settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/settings.yml) is determined by `InstallationPathConfig.getSettingsPath()`, which defaults to [`./configs/settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/./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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/app/common/src/main/java/stirling/software/common/configuration/InstallationPathConfig.java) (lines 44-46).

This file contains the complete configuration hierarchy:

```yaml
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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/custom_settings.yml) file in the same directory ([`./configs/custom_settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/./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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/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:

```bash
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**:
   ```bash
   mkdir -p ./configs
   ```

2. **Copy the template** (only required for manual setup; the application creates this automatically on first run):
   ```bash
   cp app/core/src/main/resources/settings.yml.template configs/settings.yml
   ```

3. **Edit the configuration**:
   ```bash
   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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/configs/custom_settings.yml) for environment-specific values that should not be in the main file.

5. **Start the application**:
   ```bash
   ./gradlew bootRun
   ```

   Or using Docker:
   ```bash
   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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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:

```yaml
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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/ApplicationProperties.java)), where the `enabled` boolean triggers the security configuration chain.

## Summary

- **Primary configuration** happens in [`./configs/settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/./configs/settings.yml), automatically created from `settings.yml.template` by the `ConfigInitializer` class.
- **YAML structure** maps directly to nested POJOs in [`ApplicationProperties.java`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/settings.yml) is located at [`./configs/settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/./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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/settings.yml) when upgrading. The `ConfigInitializer` class automatically merges any new default keys from the updated `settings.yml.template` into your existing [`settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/settings.yml) or use [`custom_settings.yml`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/custom_settings.yml) for critical overrides that you can preserve separately.