How to Enable and Use DOCKER_ENABLE_SECURITY in Stirling-PDF

Setting DOCKER_ENABLE_SECURITY=true activates Spring Security authentication in Stirling-PDF by including the proprietary authentication module at compile-time, enabling login endpoints, user management, and SSO capabilities.

Stirling-PDF is an open-source PDF manipulation tool that optionally supports enterprise-grade security features through the DOCKER_ENABLE_SECURITY environment variable. This flag controls whether the application compiles and runs with Spring Security enabled, determining if users must authenticate before accessing PDF tools.

What DOCKER_ENABLE_SECURITY Controls

When set to "true", DOCKER_ENABLE_SECURITY enables the following features:

Feature	Description
Spring Security	HTTP basic auth, form-login, CSRF protection, and session handling
Login UI	"Sign in" page and /api/v1/auth/** endpoints
User service	UserServiceInterface bean for user management (proprietary module)
SSO/OAuth2/SAML2	Optional external authentication providers
Admin-only sections	isAdmin, isNewUser, and enableLogin configuration flags

When unset or set to "false", the proprietary module containing authentication code is excluded from compilation. All security-related Spring beans are omitted, the UI hides the login screen, and the backend returns 403 Forbidden for any authentication request.

How Security Mode Works Internally

The security flag operates at compile-time through Gradle build logic, then at runtime through Spring bean configuration.

Gradle Configuration

In the root build.gradle, the isSecurityDisabled closure determines whether to exclude security features:

// build.gradle
ext.isSecurityDisabled = {
    System.getenv('DOCKER_ENABLE_SECURITY') == 'false' ||
    System.getenv('DISABLE_ADDITIONAL_FEATURES') == 'true' ||
    (project.hasProperty('DISABLE_ADDITIONAL_FEATURES') &&
     System.getProperty('DISABLE_ADDITIONAL_FEATURES') == 'true')
}

This closure is referenced throughout the build to conditionally exclude the :proprietary module and any security-related dependencies when the flag evaluates to true【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/build.gradle#L45-L49】.

Module Inclusion Logic

The app/core/build.gradle conditionally includes the proprietary authentication module:

// app/core/build.gradle
if (System.getenv('DISABLE_ADDITIONAL_FEATURES') != 'true' ||
    (project.hasProperty('DISABLE_ADDITIONAL_FEATURES')
     && System.getProperty('DISABLE_ADDITIONAL_FEATURES') != 'true')) {
    implementation project(':proprietary')
}

The :proprietary module contains UserServiceInterface and authentication services. It compiles only when DISABLE_ADDITIONAL_FEATURES is false and DOCKER_ENABLE_SECURITY is not "false"【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/app/core/build.gradle#L40-L46】.

Runtime Configuration Detection

At runtime, ConfigController builds the configuration payload consumed by the frontend:

// ConfigController.java
boolean enableLogin = applicationProperties.getSecurity().isEnableLogin()
                      && userService != null;   // only present when security is compiled
configData.put("enableLogin", enableLogin);

If enableLogin is false, the React UI hides the login screen; otherwise it displays the sign-in form【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/app/core/src/main/java/stirling/software/SPDF/controller/api/misc/ConfigController.java#L62-L70】.

Frontend Error Handling

When security is disabled, the desktop auth service provides clear feedback:

// authService.ts
if (errMsg.includes('403') || errMsg.includes('forbidden')) {
  throw new Error(
    'Login is not enabled on this server. Please enable security mode (DOCKER_ENABLE_SECURITY=true).'
  );
}

This error appears when the server returns 403 Forbidden for authentication requests【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/frontend/src/desktop/services/authService.ts#L360-L367】.

How to Enable DOCKER_ENABLE_SECURITY

Security mode requires both DOCKER_ENABLE_SECURITY=true and DISABLE_ADDITIONAL_FEATURES=false.

Docker Compose

Edit your compose file (e.g., docker/compose/docker-compose-unified-both.yml):

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:unified
    environment:
      DOCKER_ENABLE_SECURITY: "true"
      DISABLE_ADDITIONAL_FEATURES: "false"
    ports:
      - "8080:8080"

Source: docker/compose/docker-compose-unified-both.yml line 27【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/docker/compose/docker-compose-unified-both.yml#L27】.

Docker Run

For pre-built images, override at runtime:

docker run -e DOCKER_ENABLE_SECURITY=true \
           -e DISABLE_ADDITIONAL_FEATURES=false \
           -p 8080:8080 \
           stirlingtools/stirling-pdf:latest

Local Development (Gradle)

Set environment variables before building:

export DOCKER_ENABLE_SECURITY=true
export DISABLE_ADDITIONAL_FEATURES=false
./gradlew clean build       # compiles the proprietary module

./gradlew bootRun          # starts with Spring Security enabled

Root build script defines the flag【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/build.gradle#L45-L49】.

Standalone JAR

Use the helper script to select the correct JAR:

export DOCKER_ENABLE_SECURITY=true
./scripts/download-security-jar.sh  # selects security-enabled JAR

java -jar stirling-pdf-*.jar

Source: scripts/download-security-jar.sh lines 4-5【/cache/repos/github.com/Stirling-Tools/Stirling-PDF/main/scripts/download-security-jar.sh#L4-L5】.

Summary

• DOCKER_ENABLE_SECURITY toggles Spring Security and the entire authentication stack in Stirling-PDF.
• The flag is evaluated at compile-time via Gradle to include or exclude the :proprietary module containing authentication code.
• When enabled, the backend exposes login APIs, ConfigController sets enableLogin:true, and the UI displays the sign-in page.
• Critical requirement: Set both DOCKER_ENABLE_SECURITY=true and DISABLE_ADDITIONAL_FEATURES=false to activate security mode.
• Enable it via Docker Compose, Docker run flags, Gradle environment variables, or the standalone JAR helper script.

Frequently Asked Questions

What happens if I set DOCKER_ENABLE_SECURITY=true but still cannot log in?

If authentication endpoints return 403 Forbidden, verify that DISABLE_ADDITIONAL_FEATURES is set to "false". The proprietary authentication module is excluded from compilation when this variable is "true", causing userService to remain null and enableLogin to evaluate to false in ConfigController.

Is DOCKER_ENABLE_SECURITY evaluated at runtime or compile time?

The flag operates at both phases. At compile-time, Gradle uses the variable to conditionally include the :proprietary module in app/core/build.gradle. At runtime, Spring Boot checks the resulting bean configuration to expose authentication endpoints and set the enableLogin flag consumed by the frontend.

Can I enable security mode on an existing Stirling-PDF container?

No. Because the authentication code resides in the :proprietary module that is conditionally compiled, you cannot enable security on a container built with DOCKER_ENABLE_SECURITY=false. You must restart a new container using an image built with DOCKER_ENABLE_SECURITY=true (or use the latest tag which includes the security module by default) and set the environment variable to "true".

What authentication methods are available when security is enabled?

When DOCKER_ENABLE_SECURITY=true, Stirling-PDF supports HTTP Basic Auth, form-based login, and optional SSO/OAuth2/SAML2 providers. The UserServiceInterface bean handles user management, and the frontend displays the "Sign in" page when ConfigController detects the security beans are present.

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