# How to Enable and Use DOCKER_ENABLE_SECURITY in Stirling-PDF

> Enable DOCKER_ENABLE_SECURITY in Stirling-PDF to activate Spring Security authentication. Secure your application with login endpoints user management and SSO.

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

---

**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:

```groovy
// 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:

```groovy
// 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:

```java
// 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:

```typescript
// 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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/compose/docker-compose-unified-both.yml)):

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

```bash
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:

```bash
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:

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