How to Install and Configure Stirling-

1. What is Stirling-PDF and why you need it on your own server

By 2026, the issue of data privacy has become critical. Every time you upload a document to a free online service for a "quick PDF merge," you are handing over your personal data, financial reports, or corporate secrets to third parties. Stirling-PDF is an open-source solution that brings the functionality of professional PDF editors to your browser while running exclusively on your own hardware.

Unlike desktop applications, Stirling-PDF is accessible from any device: smartphone, tablet, or laptop. Unlike SaaS solutions, there are no subscriptions, page limits, or "premium features." You get full control over the processing workflow.

Key features:

• Merge, split, rotate, and delete pages.
• PDF compression with a choice of optimization algorithms.
• Add watermarks, signatures, and stamps.
• Convert PDF to Word, Excel, PowerPoint, HTML formats and vice versa.
• OCR (Optical Character Recognition): converting scans into searchable text documents.
• Remove passwords and set new ones (AES-256).
• Page organization tools: reordering, numbering, cropping.

Self-hosting on a VPS gives you independence from provider sanctions, stable processing speeds (depending only on your server's resources), and the confidence that your files are not being used to train neural networks without your consent.

2. What VPS configuration is needed for this task

Stirling-PDF is a Java application (Spring Boot) that actively uses external libraries such as LibreOffice and Tesseract OCR. These components are resource-intensive, especially when converting large files or performing high-resolution text recognition.

For stable OCR operation, especially if you plan to process documents with more than 100 pages, the amount of RAM is critical. The Java process can consume significant resources during peak loads. For comfortable work without delays, you can choose a suitable VPS with 4 or 8 GB of RAM — this will ensure a smooth interface and fast task queue processing.

When should you choose a Dedicated server? If your task involves automated processing of thousands of documents per day via the Stirling-PDF API, or if you are building an internal corporate service for a staff of 50+ employees. In other cases, a modern VPS will be more than enough.

Location: Choose a server as close as possible to you or your target audience. Although PDF processing happens on the backend, latency affects the upload and download speeds of heavy files.

3. Server preparation: basic hardening and utilities

Before installing the application itself, you need to prepare the environment. We will use Ubuntu 24.04, but the instructions are also applicable to newer 2026 versions.

First, let's update the packages and install a basic set of tools:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git htop ufw fail2ban

Security configuration is an important step. We will close all ports except SSH and standard web ports:

# Allow SSH (make sure you have access!)
sudo ufw allow 22/tcp
# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Enable firewall
sudo ufw enable

To prevent brute-force attacks on SSH, we will configure fail2ban. Let's create a local config:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

It is also recommended to create a separate user with sudo privileges so as not to work under root constantly:

adduser pdfadmin
usermod -aG sudo pdfadmin
# Switch to the new user
su - pdfadmin

4. Installing Docker and Docker Compose (relevant for 2026)

Stirling-PDF is officially distributed as a Docker image. This is the ideal installation method as it includes all dependencies (Python, LibreOffice, Java, Tesseract) in an isolated container without "cluttering" the main system.

Install Docker via the official script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add our user to the docker group to run containers without sudo:

sudo usermod -aG docker $USER
# Apply group changes (or log back into SSH)
newgrp docker

Verify the installation:

docker compose version
docker --version

In 2026, Docker Compose is a built-in part of the docker command (compose plugin), so a separate docker-compose installation is no longer required.

5. Deploying Stirling-PDF: step-by-step instructions

We will use Stirling-PDF-Ultra — this is the most complete version of the image, including all OCR languages and additional tools. Let's create a working directory:

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

Create a docker-compose.yml file. In this file, we will describe the application launch parameters:

nano docker-compose.yml

Insert the following content:

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest-ultra
    container_name: stirling-pdf
    restart: always
    ports:
      - "8080:8080"
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
      - LANGS=ru_RU,en_GB
      - APP_LOCALE=ru_RU
      - SYSTEM_DEFAULT_LOCALE=ru_RU
      - TZ=Europe/Moscow
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - /usr/share/tesseract-ocr/4.00/tessdata:/usr/share/tesseract-ocr/4.00/tessdata # Optional for custom dictionaries

Let's break down the key environment variables:

• DOCKER_ENABLE_SECURITY: enables the authorization system (login/password). Default login is admin, password is stirling. Be sure to change it after the first login!
• LANGS: list of languages for OCR. We specified Russian and English.
• INSTALL_BOOK_AND_ADVANCED_HTML_OPS: enables support for ebook conversion and advanced HTML operations.

Launch the container:

docker compose up -d

You can check the launch status with the docker ps command or by viewing the logs: docker logs -f stirling-pdf. During the first launch, downloading the "Ultra" image may take several minutes as it weighs about 2-3 GB due to the built-in LibreOffice and language packs.

6. Configuring Access via HTTPS (Caddy)

Running the service on port 8080 without encryption is a bad idea, especially if you are working with documents. We need HTTPS. The simplest and most modern way is to use the Caddy web server, which automatically obtains and renews SSL certificates from Let's Encrypt.

Let's install Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Let's configure proxying. Edit the file /etc/caddy/Caddyfile:

sudo nano /etc/caddy/Caddyfile

Replace the content with the following (specify your domain):

pdf.yourdomain.com {
    reverse_proxy localhost:8080
    
    encode gzip
    
    log {
        output file /var/log/caddy/pdf_access.log
    }
}

Restart Caddy:

sudo systemctl restart caddy

Now, provided that your domain's A-record points to your VPS IP, the service will be available at https://pdf.yourdomain.com with a valid SSL certificate.

7. Advanced Configuration: OCR, Localization, and Security

Stirling-PDF allows you to fine-tune the text recognition process. OCR is based on the Tesseract engine. If you find that the quality of Russian language recognition is not high enough, you can add additional trained data.

Authorization Setup

After the first login, go to the Settings -> Security Settings section. Here you can:

• Change the default administrator password.
• Enable API keys for integration with other services (for example, for automation via Python scripts or n8n).
• Configure session lifetime.

Performance Optimization

If the server starts to "lag" when processing PDFs, you can limit the container resources in docker-compose.yml:

    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G

This will prevent a situation where one heavy file "hangs" the entire VPS, depriving you of SSH access.

Custom Fonts

To correctly display Cyrillic when converting from PDF to Word/HTML, specific fonts are sometimes required. You can mount your server's fonts folder into the container:

      - /usr/share/fonts:/usr/share/fonts:ro

8. Backups and Automatic System Updates

Although Stirling-PDF does not store your documents forever by default (they are deleted from temporary storage after processing), application settings, users, and custom watermarks need to be backed up.

Backup Script

Let's create a simple backup.sh script:

#!/bin/bash
BACKUP_DIR="/home/pdfadmin/backups"
DATE=$(date +%Y-%m-%d)
mkdir -p $BACKUP_DIR

# Останавливаем контейнер для консистентности данных (опционально)
cd /home/pdfadmin/stirling-pdf
docker compose stop

# Архивация конфигов
tar -czf $BACKUP_DIR/stirling_conf_$DATE.tar.gz ./configs

# Запуск контейнера
docker compose start

# Удаление старых бэкапов (старше 30 дней)
find $BACKUP_DIR -type f -mtime +30 -delete

Add the script to crontab for a daily run at 3 AM:

0 3   * /bin/bash /home/pdfadmin/stirling-pdf/backup.sh

Updating Stirling-PDF

Developers actively release updates. To update to the latest version, run:

cd ~/stirling-pdf
docker compose pull
docker compose up -d --remove-orphans

Docker will automatically download new image layers and restart the service while preserving all your settings (since they are stored in external volumes).

9. Troubleshooting + FAQ

Why is OCR working very slowly?

OCR is a process that puts maximum load on the CPU. If your VPS has only 1-2 cores, recognizing a 50-page document may take several minutes. Check the load with the htop command. If the CPU is 100% loaded, consider upgrading your VPS plan.

Out of Memory error when uploading large files

This is related to Java Heap Size limits. You can increase the limit by adding a variable to docker-compose.yml:

      - JAVA_OPTS=-Xmx2g

This will allocate 2 GB of RAM specifically for the Java process needs.

What is the minimum suitable VPS configuration?

Minimum — 2 CPU cores and 4 GB RAM. On 2 GB RAM, the application will start, but when trying to use OCR or convert PDF to DOCX, the container will likely be killed by the system (OOM Killer).

What to choose — VPS or dedicated for this task?

For personal use and small teams (up to 10 people), a VPS is the ideal choice. It is flexible and easy to scale. A dedicated server is only worth getting if you plan to process huge archives of documents (tens of thousands of pages per day), where multithreading and the absence of "neighbors" on the hypervisor are important.

Is it safe to store documents on the server?

Stirling-PDF is designed to delete files immediately after you close the page or download the result. However, for maximum security, make sure you use HTTPS and a strong password to log into the system.

How to add support for other OCR languages?

In the LANGS variable in the docker-compose.yml file, add the required codes separated by commas (for example, deu for German, fra for French). A full list of codes is available in the Tesseract documentation.

10. Conclusions and Next Steps

We have successfully deployed a professional PDF management tool on our own server. Now you have full control over your documents, no subscriptions, and a powerful OCR engine available from anywhere in the world.

What to do next?

• Integration: Try using the Stirling-PDF API to automate routine tasks. For example, you can set up a script that automatically applies a watermark to all PDFs in a specific folder.
• Mobile App: Since the interface is responsive, you can add a page shortcut to your smartphone screen — it will work like a full-fledged PWA application.
• Optimization: If you plan for public access, set up Cloudflare in front of your VPS for protection against DDoS attacks and additional static caching.

Self-hosting is not only about saving money but also an important step towards digital sovereignty. With Stirling-PDF, your data belongs only to you.