Production Deployment Guide

This guide takes you from installation to a secured, monitored Stirling PDF server for your team or organization. Features that need a paid plan are marked where they appear.

Step 1: Choose Your Deployment Path#

Allow at least 2 GB of RAM (4 GB recommended) and 10 GB of disk space. A JAR installation also needs Java 25 or later, plus LibreOffice and Tesseract for conversions and OCR.

Step 2: Installation#

mkdir -p ~/stirling-pdf
cd ~/stirling-pdf

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata    # OCR language files
      - ./stirling-data/configs:/configs                 # Settings and database
      - ./stirling-data/logs:/logs                       # Application logs
      - ./stirling-data/customFiles:/customFiles:rw      # Custom branding files
      - ./stirling-data/pipeline:/pipeline               # Automation configs
    environment:
      - SECURITY_ENABLELOGIN=true            # Require sign-in
      - SYSTEM_DEFAULTLOCALE=en-US           # Default UI language for new users
      - SYSTEM_GOOGLEVISIBILITY=false        # Hide from search engines
      - SYSTEM_ROOTURIPATH=/                 # Base URL path
      - SYSTEMFILEUPLOADLIMIT=2GB            # Max upload size; numeric part must be 0-999
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 2G
          cpus: '1.0'

docker compose up -d
docker compose ps
docker compose logs -f

mkdir -p ~/stirling-data

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ~/stirling-data/tessdata:/usr/share/tessdata \
  -v ~/stirling-data/configs:/configs \
  -v ~/stirling-data/logs:/logs \
  -v ~/stirling-data/customFiles:/customFiles:rw \
  -e SECURITY_ENABLELOGIN=true \
  -e SYSTEM_DEFAULTLOCALE=en-US \
  -e SYSTEM_GOOGLEVISIBILITY=false \
  -e SYSTEMFILEUPLOADLIMIT=2GB \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

docker ps | grep stirling-pdf
docker logs -f stirling-pdf

Step 3: Initial Login & Admin Setup#

3.1: First-Time Login#

Open your Stirling PDF address and sign in with the default administrator account:

Username: admin
Password: stirling

You are asked to set a new password on first sign-in. Use a strong password of 12 or more characters.

environment:
  - SECURITY_INITIALLOGIN_USERNAME=youradmin
  - SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123!

3.2: Verify Admin Access#

Open Settings from your account at the bottom of the quick access bar on the left. Administrators also see the Workspace, Server, and Monitoring groups. Other users see only their own preferences.

If the server sections are missing:

• Check the logs with docker logs stirling-pdf.
• Confirm SECURITY_ENABLELOGIN=true is set.
• Confirm you signed in with the initial administrator account.

Consider single sign-on so your identity provider manages passwords.

Step 4: Configure Essential Settings#

Change these settings in settings.yml, or as an administrator in Settings.

4.1: General Settings#

System Locale & Language#

system:
  defaultLocale: en-US  # or en-GB, de-DE, fr-FR, etc.

ui:
  languages: []  # Empty = all languages enabled. Or specify: ["en_GB", "de_DE", "fr_FR"]

The default locale applies to new users. ui.languages limits which languages users can choose.

Search Engine Visibility#

system:
  googlevisibility: false  # Prevents search engines from indexing your site

File Upload Limits#

system:
  fileUploadLimit: 2GB  # numeric part must be 0-999, followed by KB, MB or GB

The numeric part is limited to 0-999, so 2000MB is rejected and leaves the limit unset. Use 2GB instead. An empty value means no limit.

Legal & Compliance#

Link your own policies from the app footer, or leave a value empty to hide the link:

legal:
  termsAndConditions: https://yourcompany.com/tos
  privacyPolicy: https://yourcompany.com/privacy
  accessibilityStatement: ''
  cookiePolicy: ''
  impressum: ''  # required in some countries, such as Germany

Update Notifications#

showUpdate and showUpdateOnlyAdmin both default to true, so only administrators see update notifications. To turn them off for everyone:

system:
  showUpdate: false

To show update notifications to every user, keep showUpdate: true and set showUpdateOnlyAdmin: false.

Process Limits#

Limit how many conversions and OCR jobs run at once so they fit your server's capacity:

processExecutor:
  sessionLimit:
    libreOfficeSessionLimit: 1
    tesseractSessionLimit: 1
    pythonOpenCvSessionLimit: 8
  timeoutMinutes:
    libreOfficetimeoutMinutes: 30
    tesseractTimeoutMinutes: 30

4.2: Security Settings#

Open Settings → Server → Sign-in & security.

User Registration Control#

By default, only administrators add users (see Step 6). To send email invitations, configure mail:

mail:
  enabled: true
  enableInvites: true
  host: smtp.gmail.com
  port: 587
  username: [email protected]
  password: ${MAIL_PASSWORD}  # Use environment variable
  from: [email protected]
  startTlsEnable: true  # STARTTLS upgrade after connecting (port 587)

MAIL_ENABLED=true
MAIL_ENABLEINVITES=true
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password
MAIL_FROM=[email protected]
MAIL_STARTTLSENABLE=true

Single Sign-On#

Stirling PDF supports OAuth2 / OpenID Connect providers such as Google, GitHub, and Keycloak, and SAML 2.0 providers such as Okta and Azure AD. OAuth2 is free on every plan; SAML 2.0 requires an Enterprise license.

security:
  enableLogin: true
  loginMethod: oauth2  # or 'saml2' or 'all'
  oauth2:
    enabled: true
    autoCreateUser: true  # Create users on first sign-in
    blockRegistration: false  # Set true to require admin pre-registration

See the SSO Configuration Guide for provider examples.

Login Security Settings#

security:
  loginAttemptCount: 5  # Lock account after 5 failed attempts
  loginResetTimeMinutes: 120  # Unlock after 2 hours

• JWT lifetimes are configurable with security.jwt.tokenExpiryMinutes and security.jwt.desktopTokenExpiryMinutes, both in minutes.
• Password length and complexity rules are not configurable. Use SSO to apply your organization's password policy.

4.3: Feature Control#

Open Settings → Server → System and go to Endpoint Management to choose which PDF tools users can see. All PDF tools are enabled by default. AI features are controlled separately by aiEngine and are off by default; see Step 11.

endpoints:
  toRemove:
    - 'add-password'
    - 'remove-password'
    - 'change-permissions'
  groupsToRemove:
    - 'LibreOffice'  # Disables all LibreOffice-based conversions

In Endpoint Management, pick the tools under Disabled Endpoints, or whole groups under Disabled Endpoint Groups, then save. See Endpoint Customisation for every tool ID.

4.4: Save and Apply Settings#

Select Save on each settings page. Some settings need a restart, and Stirling PDF tells you when. To restart:

# Docker Compose
docker compose restart

# Docker Run
docker restart stirling-pdf

Step 5: HTTPS & Domain Setup#

Use HTTPS for access to Stirling PDF. You can terminate HTTPS at your existing reverse proxy or load balancer, or configure it directly in Stirling PDF.

Reverse proxy integration#

• Route requests to Stirling PDF's HTTP port (8080 by default), using an address reachable from your proxy.
• Preserve the public hostname and pass the original HTTPS scheme in X-Forwarded-Proto. If the upstream Host differs from the public hostname, also pass X-Forwarded-Host. These values are used when constructing login redirects.
• Match the proxy's upload limit to the uploads you allow in Stirling PDF, and allow enough time for document processing.
• For a subdirectory such as /pdf, set SYSTEM_ROOTURIPATH=/pdf and forward requests with that prefix intact.

Use your proxy or hosting provider's documentation for certificate issuance, renewal and DNS setup.

HTTPS directly in Stirling PDF#

Place your certificate keystore in the mounted configs/ directory and configure server.ssl in configs/custom_settings.yml. Set server.port to the HTTPS port and publish that port in your container configuration.

See SSL/TLS Configuration for the Stirling PDF settings and examples.

Step 6: User Management#

6.1: User Roles#

6.2: Adding Users#

Open Settings → Workspace → Users and select Invite people. You can add several people at once.

• Invite by email sends each person a link to join and set their own password. This needs mail configured.
• Create account directly sets a username and password for them. Share the password securely and turn on Require a password change on first login.

Choose each person's role and team before sending.

6.3: Managing Users#

From Settings → Workspace → Users you can reset a password, change a role, disable an account, or remove a member. Disabled users cannot sign in. Removing a member cannot be undone.

Step 7: Monitoring & Usage Tracking#

7.1: Logs#

# Docker Compose
docker compose logs -f stirling-pdf

# Docker Run
docker logs -f stirling-pdf

# Last 100 lines
docker logs --tail 100 stirling-pdf

# Errors only
docker logs stirling-pdf 2>&1 | grep ERROR

Look for errors, repeated warnings about disk space or memory, and failed sign-in attempts.

To limit log size, or forward logs to a collector such as the ELK Stack, Splunk, Graylog, or Datadog, configure a Docker logging driver:

services:
  stirling-pdf:
    logging:
      driver: "json-file"   # local rotation; does not forward
      options:
        max-size: "10m"
        max-file: "3"

services:
  stirling-pdf:
    logging:
      driver: syslog
      options:
        syslog-address: "tcp://your-syslog-server:514"

7.2: Health Checks#

/api/v1/info/status is always reachable without signing in. Use it for load balancer health checks and uptime monitors such as Uptime Robot or Pingdom:

curl http://localhost:8080/api/v1/info/status

Request counts are available at /api/v1/info/requests/all and /api/v1/info/requests/all/unique. They need a signed-in user or an API key, and metrics.enabled: true (the default).

Also watch disk space for the data directories:

df -h
du -sh ./stirling-data/*
docker stats stirling-pdf

7.3: Prometheus (Team / Enterprise)#

Team and Enterprise licenses include a Prometheus endpoint with HTTP request counts, grouped by endpoint, request method, and session. See Usage Monitoring for setup.

Step 8: Backup & Disaster Recovery#

8.1: What to Backup#

Without an external database, Stirling PDF stores users in a local H2 file named stirling-pdf-DB-<schema-version>.mv.db, for example stirling-pdf-DB-2.3.232.mv.db. The simplest backup is the whole configs/ directory.

Step 9: Performance Optimization#

For resource sizing recommendations, scaling guidance, and fine tuning, see the dedicated Performance Optimization & Sizing guide.

Step 10: Paid Plans (Team/Enterprise)#

Team and Enterprise plans add features for organizations, including:

• SAML 2.0 single sign-on (Enterprise), with providers such as Okta and Azure AD.
• External PostgreSQL database for reliability and scale.
• Prometheus metrics and Usage Analytics under Settings → Monitoring.

See Paid Offerings for the full comparison, pricing, or email [email protected].

Step 11: Optional - Document Automation & AI#

11.1: Stirling Processor#

Sign in through a web browser and select Processor in the quick access bar on the left. It is not currently accessible from the desktop app, although we will be adding it for desktop apps connected to supported environments. Administrators and team leaders have access by default. Default users or environments without login will not be able to access Processor. Allow server folders before creating a folder workflow.

Follow Setup and access, then Create your first pipeline.

11.2: AI Features#

AI is off by default. Choose where it runs under Settings → Server → AI Engine:

• Run your own engine: host the AI engine on an internal network with your own model providers. Follow Self-Hosting the AI Engine.
• Use Stirling Cloud AI: no engine or provider keys; the work runs on Stirling Cloud and is billed to the linked account. Follow Stirling Cloud AI.

See AI Overview for the available features.

Recommended Steps#

• Learn Stirling PDF: the Getting Started Guide and the Tool Reference.
• Configure further: OCR languages, Pipeline Automation, the API, and LibreOffice Parallel Processing.
• Harden security: Fail2Ban, an External Database, and System and Security settings.
• Keep it running: test restoring your backups, and watch logs, disk space, and performance.

Resources#

• Documentation: https://docs.stirlingpdf.com
• GitHub: https://github.com/Stirling-Tools/Stirling-PDF
• Issue Tracker: https://github.com/Stirling-Tools/Stirling-PDF/issues
• Release Notes: https://github.com/Stirling-Tools/Stirling-PDF/releases
• Discord: https://discord.gg/HYmhKj45pU

Troubleshooting Common Issues#

Authentication Issues#

Problem: Can't log in as admin

Solutions:

1. Check logs: docker logs stirling-pdf | grep ERROR
2. Verify SECURITY_ENABLELOGIN=true is set
3. If another administrator can sign in, use Settings → Workspace → Users to reset the affected account's password.

Performance Issues#

Problem: Slow processing, timeouts

Solutions:

1. Check resource limits: docker stats stirling-pdf
2. Increase JVM heap - see Performance Optimization
3. Increase LibreOffice instances if document conversions are slow - see LibreOffice Parallel Processing
4. Use SSD storage for temporary files
5. Run the built-in diagnostics tool and check application logs

HTTPS/Certificate Issues#

Problem: Certificate errors, HTTPS not working

Solutions:

1. For direct HTTPS, check the Stirling PDF logs and verify the keystore path, password and certificate alias.
2. Behind a proxy, verify the upstream address and forwarded hostname and scheme. See HTTPS & Domain Setup.

File Upload Issues#

Problem: Can't upload large files

Solutions:

1. Check that the proxy's upload limit allows the file size configured in Stirling PDF.
2. Raise the Stirling PDF limit: system.fileUploadLimit: 2GB (env SYSTEMFILEUPLOADLIMIT=2GB)
3. Check disk space: df -h
4. Check whether the proxy closes the request before processing finishes.

Need More Help?#

Run the built-in diagnostics tool inside your Docker container to collect logs, configuration, and system information into a shareable archive.

• Community support: Discord and GitHub Issues
• Priority support: included with Team and Enterprise plans, via [email protected]