x
Skip to main content
Version: 2.0 (Beta)

Production Deployment Guide

Welcome! This guide will walk you through deploying Stirling-PDF for your organization, from initial installation to advanced configuration and scaling.

For Organizations & Teams

This guide is designed for server administrators deploying Stirling-PDF for teams, departments, or entire organizations. If you're interested in Pro or Enterprise features (SSO, advanced user management, priority support), we'll highlight upgrade paths throughout this guide.

Overview: What You'll Accomplish​

By the end of this guide, you'll have:

  1. ✅ Stirling-PDF running on your infrastructure
  2. ✅ User authentication configured with admin access
  3. ✅ Settings customized for your organization
  4. ✅ Security hardened with HTTPS and proper access controls
  5. ✅ Monitoring setup to track usage and performance
  6. ✅ Understanding of Pro/Enterprise upgrade paths

Time estimate: 30-60 minutes for basic setup, 2-3 hours for full enterprise configuration

Step 1: Choose Your Deployment Path​

Best for: Most organizations, production deployments, easy management

Why Docker Compose?

  • ✅ Simple one-command deployment
  • ✅ Easy updates and rollbacks
  • ✅ Persistent data management
  • ✅ Production-ready configuration
  • ✅ Easy to scale and customize

Requirements:

  • Docker Engine 20.10+
  • Docker Compose 1.29+
  • 2GB RAM minimum (4GB+ recommended)
  • 10GB disk space

Jump to: Docker Compose Setup

Step 2: Installation​

Follow the installation instructions for your chosen deployment method from Step 1.

Docker Compose Setup​

This is the recommended approach for production deployments.

2.1: Create docker-compose.yml​

Create a directory for your Stirling-PDF deployment:

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

Create docker-compose.yml with this production-ready configuration:

version: '3.3'

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      # Persistent data storage
      - ./stirling-data/tessdata:/usr/share/tessdata    # OCR language files
      - ./stirling-data/configs:/configs                 # Settings & database
      - ./stirling-data/logs:/logs                       # Application logs
      - ./stirling-data/customFiles:/customFiles:rw      # Custom branding files
      - ./stirling-data/pipeline:/pipeline               # Automation configs
    environment:
      # Core Settings
      - SECURITY_ENABLELOGIN=true            # Enable user authentication

      # Language & Localization
      - LANGS=en_GB                          # Change to your locale

      # System Configuration
      - SYSTEM_DEFAULTLOCALE=en-GB           # Default locale
      - SYSTEM_GOOGLEVISIBILITY=false        # Hide from search engines
      - SYSTEM_ROOTURIPATH=/                 # Base URL path
      - SYSTEM_CONNECTIONTIMEOUTMINUTES=5    # Connection timeout
      - SYSTEM_MAXFILESIZE=2000              # Max file size in MB

      # Optional: Logging
      - SYSTEM_CUSTOMSTATICFILEPATH=/customFiles/static/  # Custom files path

    restart: unless-stopped

    # Optional: Resource limits
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 2G
          cpus: '1.0'

2.2: Start Stirling-PDF​

# Start the container
docker-compose up -d

# Check if it's running
docker-compose ps

# View logs
docker-compose logs -f

2.3: Verify Installation​

Open your browser and navigate to:

http://your-server-ip:8080

You should see the Stirling-PDF homepage!

Success!

If you see the Stirling-PDF interface, your installation is successful. Continue to Step 3 to set up authentication.

Troubleshooting:

  • Can't connect? Check firewall rules: sudo ufw allow 8080
  • Container won't start? Check logs: docker-compose logs
  • Permission errors? Fix permissions: sudo chmod -R 755 ./stirling-data

Step 3: Initial Login & Admin Setup​

Now that Stirling-PDF is running with authentication enabled, you need to create your admin account.

3.1: First-Time Login​

  1. Navigate to your Stirling-PDF instance:

    http://your-server-ip:8080

  2. Log in with default credentials:

    Username: admin
    Password: stirling

  3. Change the default password immediately:

    • After first login, go to Settings → Account
    • Change to a strong password (12+ characters, mixed case, numbers, symbols)
Customizing Default Credentials

You can set custom default credentials before first startup using environment variables:

environment:
  - SECURITY_INITIALLOGIN_USERNAME=youradmin
  - SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123!

Important: These only work on first startup. If you change them after the database is created, the old credentials remain active. Always change the password through the UI after first login.

User Registration

After first login, you can control how additional users are created through Settings → Security (covered in Step 4).

3.2: Verify Admin Access​

  1. Log in with your admin account

  2. Click the Settings gear icon ⚙️ in the top navigation bar

  3. Verify you have admin access by checking for admin-only sections:

    • General Settings - System configuration
    • Security Settings - User management, login settings
    • UI Customization - Branding and appearance
    • User Management - Create/manage users
    • Endpoint Configuration - Enable/disable tools

    Note: Regular users can also access Settings but only see their personal preferences (language, theme). Only admins see the sections listed above.

  4. If you don't see admin sections:

    • Check logs: docker logs stirling-pdf
    • Verify you're the first user created
    • Confirm SECURITY_ENABLELOGIN=true is set
Secure Your Admin Account
  • Change the default password immediately after first login
  • Use a strong password (12+ characters, mixed case, numbers, symbols)
  • Consider using SSO (OAuth2/SAML2) to avoid password management entirely

Step 4: Configure Essential Settings​

Now that you're logged in as admin, let's configure Stirling-PDF for your organization.

4.1: General Settings​

Navigate to Settings → General

These settings should be configured immediately:

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"]

Why: Ensures UI appears in the correct language for your users

Search Engine Visibility​

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

Why: Keeps your internal PDF tool private

File Upload Limits​

system:
  fileUploadLimit: 2000MB  # or "2GB" - adjust based on your needs

Why: Prevents users from uploading files that crash the system

4.2: Security Settings​

Navigate to Settings → Security

Critical for Production

These settings directly impact your organization's security. Review carefully!

User Registration Control​

Best for: Controlled environments, enterprises, security-conscious orgs

How it works:

  1. Admin creates user accounts manually in Settings → User Management
  2. Admin shares credentials with users securely
  3. Users log in with provided credentials

Email Invitations (Optional): If you configure email, admins can send invitation links instead.

mail:
  enabled: true
  enableInvites: true
  smtp:
    host: smtp.gmail.com
    port: 587
    username: noreply@yourcompany.com
    password: ${MAIL_PASSWORD}  # Use environment variable
    tls:
      enabled: true

Login Security Settings​

security:
  csrfDisabled: false  # NEVER disable CSRF protection in production
  loginAttemptCount: 5  # Lock account after 5 failed attempts
  loginResetTimeMinutes: 120  # Unlock after 2 hours

Notes:

  • Session timeout is not configurable via settings
  • Password policies (length, complexity) are not currently configurable
  • Use SSO/OAuth2 for enterprise password policies

4.3: Feature Control​

Navigate to Settings → Endpoints

Control which PDF tools are available to users.

All tools are enabled by default. You can disable specific tools if needed:

endpoints:
  toRemove: []  # Add tool IDs to disable, e.g. ['sign', 'add-password']
  groupsToRemove: []  # Disable entire groups, e.g. ['LibreOffice']

Most organizations don't need to disable anything - all tools are useful and safe

4.4: Save and Apply Settings​

After configuring all settings:

  1. Click "Save" button at the bottom of each settings page
  2. Verify settings saved - You should see a success message
  3. Some settings require restart - Check if restart notification appears
  4. Test changes - Log out and log in as a regular user to verify

If restart is needed:

# Docker Compose
docker-compose restart

# Docker Run
docker restart stirling-pdf

Step 5: HTTPS & Domain Setup​

Production Requirement

Never run in production without HTTPS. User credentials and PDF files will be transmitted in plain text over the network.

5.1: Choose Your HTTPS Method​

Best for: Simple deployments, no reverse proxy needed

Stirling-PDF can handle HTTPS directly using built-in SSL configuration.

Configure SSL in Stirling-PDF​

  1. Generate or obtain SSL certificate:

    Option A: Self-signed (for testing/internal use):

    # Generate self-signed certificate
    keytool -genkeypair \
      -alias stirling \
      -keyalg RSA \
      -keysize 2048 \
      -storetype PKCS12 \
      -keystore keystore.p12 \
      -validity 365

    # Move to configs directory
    mv keystore.p12 ./stirling-data/configs/

    Option B: Let's Encrypt (for production):

    # Get certificate with certbot
    sudo certbot certonly --standalone -d pdf.yourcompany.com

    # Convert to PKCS12 format
    sudo openssl pkcs12 -export \
      -in /etc/letsencrypt/live/pdf.yourcompany.com/fullchain.pem \
      -inkey /etc/letsencrypt/live/pdf.yourcompany.com/privkey.pem \
      -out keystore.p12 \
      -name stirling

    # Move to configs
    sudo mv keystore.p12 ./stirling-data/configs/
    sudo chown $USER:$USER ./stirling-data/configs/keystore.p12

  2. Create custom_settings.yml:

    Create ./stirling-data/configs/custom_settings.yml:

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

  3. Update docker-compose.yml to expose port 8443:

    services:
      stirling-pdf:
        ports:
          - '8443:8443'  # Change from 8080:8080

  4. Restart Stirling-PDF:

    docker-compose down
    docker-compose up -d

  5. Access via HTTPS:

    https://pdf.yourcompany.com:8443

Benefits:

  • ✅ Simple setup, no reverse proxy needed
  • ✅ Direct SSL termination in application
  • ✅ Good for small deployments

Limitations:

  • ⚠️ Manual certificate renewal
  • ⚠️ No load balancing
  • ⚠️ Port 8443 instead of standard 443

Learn more: Custom Settings - SSL Configuration

5.2: Update Stirling-PDF Configuration​

After setting up HTTPS, update Stirling-PDF to use the correct URL:

In Settings → General:

System Settings:
  Root URI Path: / (or /pdf if using subdirectory)
  Frontend URL: https://pdf.yourcompany.com
  CORS Allowed Origins: https://pdf.yourcompany.com

Environment variable (if using split deployment):

environment:
  - VITE_API_BASE_URL=https://pdf.yourcompany.com
  - SYSTEM_ROOTURIPATH=/
  - SECURITY_CSRFDISABLED=false

Step 6: User Management​

Now that your system is secure and accessible, let's set up users.

6.1: Understanding User Roles​

Out-of-the-box roles:

RolePermissionsUse Case
AdminFull access to all features, settings, user managementSystem administrators, IT staff
UserAccess to enabled PDF tools, no settings accessRegular employees, end users

Admin capabilities:

  • ✅ Access all PDF tools
  • ✅ Manage users (create, delete, reset passwords)
  • ✅ Configure all settings
  • ✅ View usage statistics
  • ✅ Enable/disable features
  • ✅ View logs (if configured)

User capabilities:

  • ✅ Access enabled PDF tools only
  • ✅ Upload and process files
  • ✅ Download results
  • ❌ No settings access
  • ❌ No user management
  • ❌ No system configuration

6.2: Adding Users​

As admin, manually create user accounts:

  1. Navigate to Settings → User Management

  2. Click "Add User" button

  3. Fill in user details:

    Username: john.doe
    Email: john.doe@yourcompany.com (optional but recommended)
    Password: Auto-generate or set manually
    Role: User (or Admin for additional admins)
    Enabled: Yes

  4. Click "Create User"

  5. Share credentials with user (via secure channel)

Bulk user creation: You can paste a list of email addresses (one per line) to create multiple users at once.

Best practices:

  • Use email as username for easier identification
  • Auto-generate strong passwords
  • Keep records of who has access

6.3: User Management Tasks​

Common admin tasks:

View All Users​

  • Navigate to Settings → User Management
  • See list of all users with status, role, last login

Reset User Password​

  1. Find user in user list
  2. Click "Reset Password" button
  3. New password generated or set manually
  4. Share new password securely

Disable/Enable User​

  1. Find user in user list
  2. Toggle "Enabled" switch
  3. Disabled users cannot log in

Delete User​

  1. Find user in user list
  2. Click "Delete" button
  3. Confirm deletion
  4. ⚠️ Warning: This is permanent

Change User Role​

  1. Find user in user list
  2. Change role dropdown (User/Admin)
  3. Save changes

Step 7: Monitoring & Usage Tracking​

Understanding how your users are using Stirling-PDF helps with capacity planning and identifying issues.

7.1: Basic Monitoring​

View application 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

# Filter for errors
docker logs stirling-pdf 2>&1 | grep ERROR

What to look for:

  • ✅ Successful operations
  • ⚠️ Warnings (disk space, memory)
  • ❌ Errors (failed operations, crashes)
  • 🔒 Security events (failed logins, unauthorized access)

Common log entries:

INFO: User john.doe uploaded file document.pdf
INFO: Operation MERGE completed successfully
WARN: Disk space low: 85% used
ERROR: OCR operation failed: Tesseract not found

7.2: Set Up Monitoring​

Basic monitoring approach:

  1. Monitor Docker logs regularly:

    docker logs stirling-pdf --tail 100 -f

  2. Check Docker container health:

    docker ps
    docker stats stirling-pdf

  3. Monitor disk space:

    df -h
    du -sh ./stirling-data/*

  4. Use external uptime monitoring:

    • Uptime Robot (free)
    • Pingdom
    • StatusCake
    • Monitor the health endpoint: http://localhost:8080/api/v1/health

Step 8: Backup & Disaster Recovery​

Protect your users' data and configuration with proper backups.

8.1: What to Backup​

Critical data to backup:

DataLocationFrequencyImportance
User Database (if local)./stirling-data/configs/stirling-pdf.dbDailyCritical*
Settings File./stirling-data/configs/settings.ymlAfter changesCritical
Custom Files./stirling-data/customFiles/After changesHigh
OCR Languages./stirling-data/tessdata/WeeklyMedium
Logs./stirling-data/logs/OptionalLow

*Note on User Database:

  • Free edition: Uses local H2 database (stirling-pdf.db) - must be backed up
  • Pro/Enterprise: Should use external PostgreSQL database (backed up separately)
Pro/Enterprise Recommendation

Pro and Enterprise users should configure an external PostgreSQL database instead of using the local H2 database. This provides better reliability, scalability, and backup capabilities.

Learn more: External Database Configuration

8.2: Backup Strategies​

Create automated backup script:

Create backup-stirling.sh:

#!/bin/bash

# Configuration
BACKUP_DIR="/backups/stirling-pdf"
STIRLING_DATA="/path/to/stirling-data"
RETENTION_DAYS=30

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Generate timestamp
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_FILE="$BACKUP_DIR/stirling-backup-$TIMESTAMP.tar.gz"

# Stop container (optional, for consistency)
# docker-compose -f /path/to/docker-compose.yml stop stirling-pdf

# Create backup
tar -czf "$BACKUP_FILE" \
  -C "$STIRLING_DATA" \
  configs/ \
  customFiles/ \
  tessdata/

# Start container (if stopped)
# docker-compose -f /path/to/docker-compose.yml start stirling-pdf

# Delete old backups
find "$BACKUP_DIR" -name "stirling-backup-*.tar.gz" -mtime +$RETENTION_DAYS -delete

# Log result
echo "[$TIMESTAMP] Backup completed: $BACKUP_FILE"

Make executable and schedule:

chmod +x backup-stirling.sh

# Add to crontab (daily at 2 AM)
crontab -e
# Add: 0 2 * * * /path/to/backup-stirling.sh >> /var/log/stirling-backup.log 2>&1

8.3: Restore from Backup​

Restore procedure:

  1. Stop Stirling-PDF:

    docker-compose stop stirling-pdf

  2. Extract backup:

    tar -xzf stirling-backup-YYYYMMDD-HHMMSS.tar.gz -C ./stirling-data/

  3. Verify files restored:

    ls -la ./stirling-data/configs/
    # Should see: stirling-pdf.db, settings.yml

  4. Start Stirling-PDF:

    docker-compose start stirling-pdf

  5. Verify functionality:

    • Access web interface
    • Log in as admin
    • Check users exist
    • Verify settings

Step 9: Performance Optimization​

Optimize Stirling-PDF for your workload and server capacity.

9.1: Resource Allocation​

Recommended specifications:

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 20GB
  • Concurrent operations: 2-4

Docker resource limits:

deploy:
  resources:
    limits:
      memory: 4G
      cpus: '2.0'
    reservations:
      memory: 2G
      cpus: '1.0'

Settings:

system:
  maxFileSize: 500  # 500MB max file
  connectionTimeoutMinutes: 5
  maxConcurrentOperations: 2

9.2: Storage Management​

Monitor disk usage:

# Check Docker disk usage
docker system df

# Check Stirling-PDF data usage
du -sh ./stirling-data/*

Cleanup strategies:

system:
  # Automatic cleanup settings
  tempFileCleanup: true
  tempFileMaxAge: 24  # hours

  # Log rotation
  logRetentionDays: 30
  maxLogSize: 100  # MB

Manual cleanup:

# Clean Docker system
docker system prune -a --volumes

# Clean old logs
find ./stirling-data/logs -name "*.log" -mtime +30 -delete

# Clean temporary files (if not auto-cleaned)
find ./stirling-data/temp -type f -mtime +1 -delete

Step 10: Pro/Enterprise Edition​

Stirling-PDF offers Pro and Enterprise editions with additional features for organizations.

Key Pro/Enterprise Features​

Authentication & Security:

  • SAML2 SSO: Enterprise-grade single sign-on (OAuth2 is free)
  • Enhanced security features

Database & Infrastructure:

  • External PostgreSQL Database: Required for Pro/Enterprise deployments
  • Better reliability and scalability than local H2 database
  • Professional backup and replication strategies

Monitoring & Analytics:

  • Prometheus Integration: Advanced metrics and monitoring
  • Usage Dashboard: Graphical usage statistics at /usage
  • Enhanced monitoring APIs

For pricing and enterprise inquiries:

Next Steps & Resources​

Congratulations! You've successfully deployed and configured Stirling-PDF for your organization.

  1. 📚 Train your users

  2. 🔧 Advanced configuration

  3. 🔒 Harden security

  4. 📊 Monitor and optimize

    • Set up regular backup verification
    • Review logs weekly
    • Monitor disk space and performance
    • Plan for growth

Support & Community​

Stay Updated​

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. Reset admin password via command line: 
    docker exec -it stirling-pdf sh
    # Use built-in password reset tool

Performance Issues​

Problem: Slow processing, timeouts

Solutions:

  1. Check resource limits: docker stats stirling-pdf
  2. Increase memory: Update deploy.resources.limits.memory
  3. Reduce concurrent operations: Lower maxConcurrentOperations
  4. Check disk I/O: Use SSD for better performance

HTTPS/Certificate Issues​

Problem: Certificate errors, HTTPS not working

Solutions:

  1. Check Nginx/Traefik logs
  2. Verify DNS points to correct IP
  3. Ensure ports 80 and 443 are open
  4. Test Let's Encrypt manually: sudo certbot certificates

File Upload Issues​

Problem: Can't upload large files

Solutions:

  1. Increase Nginx limit: client_max_body_size 2000M;
  2. Increase Stirling-PDF limit: system.maxFileSize: 2000
  3. Check disk space: df -h
  4. Increase timeouts: client_body_timeout 300s;

Need More Help?​

For Community Support:

For Priority Support:

You're all set! 🎉

Your Stirling-PDF deployment is ready for production use. If you have any questions or need assistance, don't hesitate to reach out to our community or consider upgrading to Pro/Enterprise for dedicated support.

Happy PDF processing! 📄✨