Production Deployment Guide

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

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 paid plan upgrade paths (Server/Enterprise)

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

Step 1: Choose Your Deployment Path#

Step 2: Installation#

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

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:
      # 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
      - SYSTEM_DEFAULTLOCALE=en-US           # Default UI locale for new users

      # System Configuration
      - SYSTEM_GOOGLEVISIBILITY=false        # Hide from search engines
      - SYSTEM_ROOTURIPATH=/                 # Base URL path
      - SYSTEMFILEUPLOADLIMIT=2000MB         # Max upload size (legacy: SYSTEM_MAXFILESIZE in MB)

    restart: unless-stopped

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

# Start the container
docker-compose up -d

# Check if it's running
docker-compose ps

# View logs
docker-compose logs -f

http://your-server-ip:8080

# Create data directory
mkdir -p ~/stirling-data

# Run Stirling-PDF
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=2000MB \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

# Check if running
docker ps | grep stirling-pdf

# View logs
docker logs -f stirling-pdf

http://your-server-ip:8080

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)

environment:
  - SECURITY_INITIALLOGIN_USERNAME=youradmin
  - SECURITY_INITIALLOGIN_PASSWORD=YourSecurePassword123!

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

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

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

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

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

legal:
  termsAndConditions: https://yourcompany.com/tos  # or empty string to disable
  privacyPolicy: https://yourcompany.com/privacy  # or empty string to disable
  accessibilityStatement: ''  # optional
  cookiePolicy: ''  # optional
  impressum: ''  # optional (required in some countries like Germany)

system:
  showUpdate: false  # Set true to show update notifications
  showUpdateOnlyAdmin: false  # Only admins see updates (requires showUpdate: true)

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

4.2: Security Settings#

Navigate to Settings → Security

User Registration Control#

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

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

Login Security Settings#

security:
  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.

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

endpoints:
  toRemove:
    - 'add-password'  # Disable password protection tool
    - 'remove-password'  # Disable password removal tool
    - 'change-permissions'  # Disable permissions modification

endpoints:
  groupsToRemove:
    - 'LibreOffice'  # Disables all LibreOffice-based conversions

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#

5.1: Choose Your HTTPS Method#

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

server {
    listen 80;
    server_name pdf.yourcompany.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name pdf.yourcompany.com;

    # SSL certificates (will be added by certbot)
    ssl_certificate /etc/letsencrypt/live/pdf.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.yourcompany.com/privkey.pem;

    # Strong SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Large file uploads
    client_max_body_size 2000M;
    client_body_timeout 300s;

    # Proxy to Stirling-PDF
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support (if needed)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeouts for large files
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/stirling-pdf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Get Let's Encrypt certificate
sudo certbot --nginx -d pdf.yourcompany.com

# Auto-renewal (certbot sets this up automatically)
sudo certbot renew --dry-run

A record: pdf.yourcompany.com → your-server-ip

https://pdf.yourcompany.com

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

Step 6: User Management#

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

6.1: Understanding User Roles#

6.2: Adding Users#

Email Settings:
  SMTP Host: smtp.gmail.com
  SMTP Port: 587
  SMTP Username: [email protected]
  SMTP Password: your-app-password
  From Address: [email protected]

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#

# 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

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

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

# Request counts
curl http://localhost:8080/api/v1/info/requests/all

# Unique users
curl http://localhost:8080/api/v1/info/requests/all/unique

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

# Response:
{"status":"UP","version":"<version>"}

services:
  stirling-pdf:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

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

7.2: Set Up Monitoring#

Basic monitoring approach:

1. Monitor Docker logs regularly:

   bash

   docker logs stirling-pdf --tail 100 -f

2. Check Docker container health:

   bash

   docker ps
   docker stats stirling-pdf

3. Monitor disk space:

   bash

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

4. Use external uptime monitoring:

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

Step 8: Backup & Disaster Recovery#

Protect your users' data and configuration with proper backups.

8.1: What to Backup#

Critical data to backup:

*Note on User Database:

• Free edition: Uses a local H2 database file named stirling-pdf-DB-<schema-version>.mv.db (the schema version is embedded in the filename, e.g. stirling-pdf-DB-2.3.232.mv.db) - must be backed up. The simplest approach is to back up the whole configs/ directory.
• Server/Enterprise: Should use external PostgreSQL database (backed up separately)

8.2: Backup Strategies#

#!/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"

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

# Stop container
docker-compose stop stirling-pdf

# Backup volumes
docker run --rm \
  -v $(pwd)/stirling-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar -czf /backup/stirling-data-$(date +%Y%m%d).tar.gz /data

# Start container
docker-compose start stirling-pdf

#!/bin/bash
cd /path/to/stirling-pdf
docker-compose stop stirling-pdf
docker run --rm \
  -v "$(pwd)/stirling-data:/data" \
  -v "$(pwd)/backups:/backup" \
  alpine tar -czf /backup/stirling-data-$(date +%Y%m%d).tar.gz /data
docker-compose start stirling-pdf

# Cleanup old backups (keep 30 days)
find backups/ -name "stirling-data-*.tar.gz" -mtime +30 -delete

8.3: Restore from Backup#

Restore procedure:

1. Stop Stirling-PDF:

   bash

   docker-compose stop stirling-pdf

2. Extract backup:

   bash

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

3. Verify files restored:

   bash

   ls -la ./stirling-data/configs/
   # Should see: stirling-pdf-DB-<schema-version>.mv.db, settings.yml

4. Start Stirling-PDF:

   bash

   docker-compose start stirling-pdf

5. Verify functionality:

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

Step 9: Performance Optimization#

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

Step 10: Paid Plans (Server/Enterprise)#

Stirling-PDF offers Server and Enterprise paid plans with additional features for organizations.

Key Paid Plan Features#

Authentication & Security:

• OAuth2 SSO: Server tier (Google, GitHub, Keycloak, OIDC)
• SAML2 SSO: Enterprise tier (Okta, Azure AD, etc.)
• Enhanced security features

Database & Infrastructure:

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

Monitoring & Analytics:

• Prometheus Integration: Advanced metrics and monitoring
• Usage Monitoring UI: Graphical usage statistics in the admin interface
• Enhanced monitoring APIs

For pricing and enterprise inquiries:

• Email: [email protected]
• Website: https://stirling.com/pricing
• Documentation: Paid Offerings
• External Database Setup: External Database Guide
• Monitoring Setup: Usage Monitoring

Next Steps & Resources#

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

Recommended Next Steps#

1. 📚 Train your users

   • Share the Getting Started Guide
   • Point them to Tool Reference
   • Create internal documentation for your specific workflows

2. 🔧 Advanced configuration

   • OCR Configuration - Add more languages
   • Pipeline Automation - Automate workflows
   • API Integration - Integrate with other systems
   • LibreOffice Parallel Processing - Scale document conversions

3. 🔒 Harden security

   • Fail2Ban Setup - Prevent brute force
   • External Database - Use PostgreSQL
   • Review System and Security settings

4. 📊 Monitor and optimize

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

Support & Community#

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

Stay Updated#

• Release Notes: https://github.com/Stirling-Tools/Stirling-PDF/releases
• Blog: https://stirlingtools.com/blog
• Newsletter: Subscribe at https://stirlingtools.com

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

   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 JVM heap - see Performance Optimization
3. Increase LibreOffice instances if document conversions are slow - see LibreOffice Parallel Processing
4. Check disk I/O: Use SSD for temp file storage
5. Run the built-in diagnostics tool and check application logs

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.fileUploadLimit: 2000MB (env SYSTEMFILEUPLOADLIMIT=2000MB)
3. Check disk space: df -h
4. Increase timeouts: client_body_timeout 300s;

Need More Help?#

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

For Community Support:

• Join Discord: https://discord.gg/HYmhKj45pU
• Search GitHub Issues: https://github.com/Stirling-Tools/Stirling-PDF/issues

For Priority Support:

• Upgrade to Server or Enterprise plan
• Email: [email protected]
• Get dedicated support team

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 a paid plan (Server or Enterprise) for dedicated support.

Happy PDF processing! 📄✨