Self-hosted server

Extra settings

custom_settings.yml holds server settings that settings.yml does not cover, such as logging, HTTPS and the port. It sits next to settings.yml (/configs/custom_settings.yml in Docker) and overrides it where both set the same key (Which setting wins). Restart Stirling PDF after editing it.

Logging#

yaml

logging:
  level:
    root: INFO

Single sign-on logging is covered on the OAuth and SAML pages. For other problems, raise one area at a time and set it back afterwards, because debug logging is large and slows the server:

yaml

logging:
  level:
    stirling.software: DEBUG  # general problems

Port and session length#

yaml

server:
  port: 8080
  servlet:
    session:
      timeout: 30m

bash

SERVER_PORT=8080
SERVER_SERVLET_SESSION_TIMEOUT=30m

Both values shown are the defaults.

SSL/TLS configuration#

Stirling PDF can serve HTTPS itself from a PKCS12 keystore. In production it is usually simpler to put it behind a reverse proxy that handles HTTPS (see Production checklist).

yaml

server:
  port: 8443
  ssl:
    enabled: true
    key-store: file:./configs/keystore.p12
    key-store-password: your-keystore-password
    key-store-type: PKCS12
    key-alias: stirling

bash

SERVER_PORT=8443
SERVER_SSL_ENABLED=true
SERVER_SSL_KEYSTORE=file:./configs/keystore.p12
SERVER_SSL_KEYSTOREPASSWORD=your-keystore-password
SERVER_SSL_KEYSTORETYPE=PKCS12
SERVER_SSL_KEYALIAS=stirling

yaml

services:
  stirling-pdf:
    environment:
      SERVER_PORT: 8443
      SERVER_SSL_ENABLED: "true"
      SERVER_SSL_KEYSTORE: file:./configs/keystore.p12
      SERVER_SSL_KEYSTOREPASSWORD: your-keystore-password
      SERVER_SSL_KEYSTORETYPE: PKCS12
      SERVER_SSL_KEYALIAS: stirling

To create a self-signed certificate for testing:

bash

keytool -genkeypair -alias stirling -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore configs/keystore.p12 -validity 365

Large request headers (HTTP 431)#

If sign-in or single sign-on fails with HTTP 431 Request Header Fields Too Large, raise the header limit and restart:

yaml

server:
  max-http-request-header-size: 65536

bash

SERVER_MAXHTTPREQUESTHEADERSIZE=65536

yaml

services:
  stirling-pdf:
    environment:
      SERVER_MAXHTTPREQUESTHEADERSIZE: 65536

Try 131072 if the error continues.

Serve under a sub-path#

To serve the app at a path such as https://example.com/pdf instead of the domain root, set:

bash

SYSTEM_ROOTURIPATH=/pdf

In Docker, use this variable: the image's health check reads it too. Outside Docker you can instead set server.servlet.context-path: /pdf in custom_settings.yml.

Also set Frontend URL (system.frontendUrl) to the full address, for example https://example.com/pdf, so links in emails, share links and mobile QR codes include the path.

Outgoing HTTP(S) proxy#

To send the server's outgoing requests, such as licence checks, through a proxy, pass the standard Java proxy options. In Docker, use JAVA_CUSTOM_OPTS:

yaml

services:
  stirling-pdf:
    environment:
      JAVA_CUSTOM_OPTS: "-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8888 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8888 -Dhttp.nonProxyHosts=localhost|127.*|[::1]|10.*|*.svc|*.cluster.local"

When running the JAR, put the same -D options before -jar on the java command line.

Edit this page on GitHub