Mustafa ERBAY

Posted on Jul 30 • Originally published at mustafaerbay.com.tr

Stirling PDF Setup: Process Documents Without Uploading to the Cloud

#selfhosting #guide #software

When you need to edit, merge, or convert your sensitive documents in PDF format, sending your data to third-party cloud services can raise serious security and privacy concerns. Stirling PDF offers a comprehensive, open-source solution that you can host on your own server to address this problem. This tool allows you to keep all your PDF operations within your local network, maximizing your data security.

In this post, I will guide you step-by-step on how to install Stirling PDF using Docker Compose and make it securely accessible with an Nginx reverse proxy. Our goal is to acquire a powerful PDF management tool without cloud dependency and keep full control of your sensitive data in your hands.

Why Should We Process Our Documents Without Uploading Them to the Cloud?

Uploading sensitive data to cloud-based PDF processing services carries potential security breaches and privacy risks. Critical documents such as company contracts, financial reports, personal identification information, or patent documents, when uploaded to such services, become subject to the service provider's security policies and legal jurisdiction. This situation can lead to undesirable outcomes like data leaks or unauthorized access.

In corporate environments, data protection regulations like KVKK (Turkish Personal Data Protection Law) and GDPR impose strict rules on the processing of personal and sensitive data. Compliance with these regulations requires transparency and control over where data is stored and who can access it. Uploading documents to a third-party service can mean losing some or all of this control.

⚠️ Data Sovereignty and Security

While cloud-based services generally offer high security standards, data sovereignty is always a concern. Issues such as how long your documents are kept on servers, who can access them, and for what purposes they can be used, depend on the service provider's terms and conditions. Hosting your own solution provides full control over these matters.

Solutions like Stirling PDF, hosted on your own infrastructure, ensure that all processing remains under your control. Your documents never leave your server, which significantly reduces the risk of sensitive information leaking externally. This approach offers significant advantages for both individual privacy and corporate data security.

What is Stirling PDF and What Features Does It Offer?

Stirling PDF is an open-source, web-based PDF processing tool that can be easily deployed as a Docker container. Its primary goal is to provide users with a wide range of operations on PDF documents while ensuring that documents are never uploaded to a third-party server. This way, the privacy and security of your sensitive data remain under your control.

This tool incorporates many basic and advanced features such as merging, splitting, compressing, converting (e.g., image to PDF or PDF to image), rotating, encrypting PDFs, and OCR (Optical Character Recognition). It can also be used for more specific tasks like adding watermarks to PDFs, editing metadata, and even converting PDFs to web pages.

ℹ️ Open Source Advantage

Being open source means that Stirling PDF is continuously developed by the community, and security vulnerabilities can be identified and fixed more quickly. Furthermore, you can examine the software's source code to fully understand its operation and eliminate potential "backdoor" concerns.

Stirling PDF's user interface is quite intuitive and easy to use. This allows even users without technical knowledge to perform PDF operations comfortably. All these features make it an attractive self-hosted solution for both individual users and small to medium-sized businesses.

Pre-Installation Preparations: Requirements and Infrastructure

To run Stirling PDF on your own server, you need to meet some basic requirements. First, you will need a Linux server. This could be a Virtual Private Server (VPS), a Raspberry Pi at home, or even a corporate bare-metal server. The important thing is that it has an operating system capable of running Docker and Docker Compose, and sufficient resources.

Minimum system requirements can generally be considered 2GB RAM and 2 CPU cores, but if you plan to process large or numerous PDF files simultaneously, more RAM (4GB or more) and a more powerful processor (2 cores or more) are recommended. Especially intensive operations like OCR can consume a significant amount of CPU and RAM. In terms of disk space, it is recommended to have at least 20GB of free space, depending on the size of the documents you will process and the historical data you wish to keep. Processed files are generally not stored permanently, but components like OCR language packs do use disk space.

# Docker Engine and Docker Compose installation on Ubuntu/Debian based systems
# Remove old Docker versions (if any)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt remove $pkg; done

# Install necessary packages
sudo apt update
sudo apt install ca-certificates curl gnupg -y

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Set up the Docker APT repository
echo \
  "deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  \"$(. /etc/os-release && echo \"$VERSION_CODENAME\")\" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Docker Compose Plugin
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Add current user to the docker group to run docker commands without sudo (optional)
sudo usermod -aG docker $USER
newgrp docker # To activate the group immediately, logging out and back in also works.

Before installation, configuring your server's firewall is also important. To make Stirling PDF accessible via the web, relevant ports (usually 80 and 443) may need to be opened for external access. If you are using a reverse proxy like Nginx, it is a more secure approach to open only the ports Nginx listens on, rather than directly exposing Stirling PDF's port.

Installing Stirling PDF with Docker Compose

The easiest and recommended way to install Stirling PDF is by using Docker Compose. This method allows you to define all application dependencies within a single file and run them with a single command. First, create a directory for Stirling PDF on your server and navigate into it.

# Create the main directory for Stirling PDF and necessary subdirectories
mkdir -p stirling-pdf/stirling-data/{tessdata,configs,logs,pipeline}
cd stirling-pdf

Next, create a file named docker-compose.yml in this directory and paste the following content:

version: '3.8'

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest # Official Stirling PDF Docker image
    container_name: stirling-pdf
    ports:
      - "8080:8080" # Maps your server's 8080 port to the container's 8080 port
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata # For OCR language files
      - ./stirling-data/configs:/configs # For settings and database
      - ./stirling-data/logs:/logs # For application logs
      - ./stirling-data/pipeline:/pipeline # For automation configurations
    environment:
      - SECURITY_ENABLELOGIN=true # Enables security features (login screen)
      - SYSTEM_DEFAULTLOCALE=tr_TR # Turkish language support
      # The following limits are resource constraints applied by Docker Compose.
      # You may need to increase the memory limit for large PDFs or OCR operations.
      - DOCKER_DEFAULT_MEMORY_LIMIT=2048m # Default memory limit for the container (e.g., 2GB)
      - DOCKER_DEFAULT_CPU_LIMIT=1 # Default CPU core limit for the container
    restart: unless-stopped

Let's examine this docker-compose.yml file:

image: stirlingtools/stirling-pdf:latest: This will pull the latest official Docker image for Stirling PDF.
container_name: stirling-pdf: Gives the container a readable name.
ports: - "8080:8080": Maps your server's 8080 port to the container's 8080 port. Stirling PDF runs on this port by default.
volumes: Important for persistent data storage. ./stirling-data/tessdata binds your local directory to /usr/share/tessdata inside the container (for OCR language files). ./stirling-data/configs binds your local directory to /configs inside the container (for settings and internal database). ./stirling-data/logs directs logs to your local logs directory. ./stirling-data/pipeline is used for automation configurations.
environment: Contains various configuration settings. SECURITY_ENABLELOGIN=true enables security controls (login screen). The default login credentials are admin username and stirling password; it is strongly recommended to change these upon first login. SYSTEM_DEFAULTLOCALE=tr_TR enables Turkish language support. DOCKER_DEFAULT_MEMORY_LIMIT and DOCKER_DEFAULT_CPU_LIMIT are resource constraints applied by Docker Compose and limit the container's system resources. This is important, especially on shared servers, to prevent other services from being affected.
restart: unless-stopped: Ensures the container restarts automatically unless it is explicitly stopped.

After saving the file, run the following command to start Stirling PDF:

docker compose up -d

The up command starts the services, and -d allows you to run the container in the background. Stirling PDF should be up and running within a few minutes. You can check the container's status with the docker compose ps command.

Now you can access Stirling PDF from your browser via your server's IP address and port 8080 (e.g., http://your_server_ip_address:8080).

Securing Access with Nginx Reverse Proxy

Accessing Stirling PDF directly via IP address and port is not ideal for security, especially on an internet-facing server. Using a reverse proxy like Nginx allows you to provide SSL/TLS encryption (HTTPS) and customize access. This is a critical step for adding extra security layers such as traffic encryption, rate limiting, and basic authentication.

First, make sure Nginx is installed:

sudo apt install nginx -y

Next, create a configuration file for Nginx. For example, create a file at /etc/nginx/sites-available/stirling-pdf.conf and add the following content. You should use your own domain name instead of example.com.

server {
    listen 80;
    server_name stirling.example.com; # Enter your domain name here

    location / {
        proxy_pass http://localhost:8080; # Address where Stirling PDF is running
        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;
        proxy_read_timeout 90;
        proxy_connect_timeout 90;
        proxy_send_timeout 90;
    }
}

This configuration directs requests coming from port 80 to the stirling.example.com domain and forwards these requests to the Stirling PDF container running at localhost:8080. The proxy_set_header directives ensure that original client information is correctly passed to the Stirling PDF application.

Now, to enable this configuration, create a symbolic link and restart Nginx:

sudo ln -s /etc/nginx/sites-available/stirling-pdf.conf /etc/nginx/sites-enabled/
sudo nginx -t # Check the configuration file
sudo systemctl restart nginx

Enabling HTTPS with SSL/TLS

To provide secure HTTPS access to your website, you can use Let's Encrypt and Certbot. This automatically updates your Nginx configuration to provide and renew SSL certificates.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d stirling.example.com # Use your own domain name

Certbot will automatically configure your Nginx to redirect to HTTPS and install the certificates. After these steps, you can securely access Stirling PDF via https://stirling.example.com.

💡 Additional Security with Fail2ban

You can monitor Nginx access logs with fail2ban to prevent brute-force attacks. Automatically blacklisting IPs that make failed login attempts significantly increases your system's security.

These steps help you establish basic security standards when exposing your Stirling PDF installation to the outside world. Using a reverse proxy not only provides SSL but also lays the groundwork for future security enhancements (e.g., WAF integration).

Stirling PDF Usage and Basic Operations

After installing Stirling PDF and making it accessible via Nginx, you can enter the web interface to perform various PDF operations. The interface is quite intuitive and allows you to select the desired operation from the left menu.

Basic Operations:

Merge PDF: Used to combine multiple PDF files into a single document. Click "Merge PDF," drag and drop or select the files you want to merge, and click the "Merge" button. Your files will be merged on your server, and the result will be automatically downloaded.
Split PDF: Ideal for splitting a large PDF file by page ranges or into separate files for each page. Go to "Split PDF," upload your file, and complete the operation by choosing the splitting method (e.g., "Extract Pages" or "Split By Page Range").
Compress PDF: Used to reduce the size of PDF files, making them easier to email or store. Select "Compress PDF," upload your file, and start the process by adjusting the compression level.
Convert PDF: You can convert PDFs to different formats (e.g., Word, Excel, image) or convert different formats to PDF. For example, to convert a JPG file to PDF, use the "Image to PDF" option.
OCR (Optical Character Recognition): Recognizes text in scanned PDFs, making them searchable. This feature is very useful, especially for digitizing old documents. Go to "OCR PDF," upload your PDF, and start the OCR process by selecting the language.

ℹ️ Management of Processed Documents

Stirling PDF typically processes documents in server memory and deletes them immediately after the operation is complete. Your documents are not permanently stored on disk. This is an important principle for protecting data privacy. Persistent data, such as application settings and the internal database, are stored in defined volumes like configs.

After each operation, Stirling PDF usually automatically downloads the resulting file to your browser. This prevents your documents from remaining on your server unnecessarily and adheres to the principle of local control. You can configure the application's general behavior and default settings from the "Admin" or "Settings" sections in the interface.

Common Problems and Solutions

While Stirling PDF installation usually proceeds smoothly, unexpected situations can sometimes arise. Here are some common problems and possible solutions:

Container Not Starting or Inaccessible:
- Port Conflict: Check if another service is using port 8080, which Stirling PDF uses. You can see if an application is listening on this port with the command sudo netstat -tulnp | grep 8080. If so, change the port mapping in your docker-compose.yml file to a different port (e.g., 8081:8080).
- Docker Service Not Running: Ensure the Docker daemon is running. You can check its status with sudo systemctl status docker and start it with sudo systemctl start docker.
- Check Logs: To understand why the container is not starting, check its logs. The docker compose logs stirling-pdf command will provide valuable information.
File Saving or Uploading Issues:
- Volume Permissions: Ensure that the volume directories you defined in docker-compose.yml (e.g., ./stirling-data/configs) are writable by the Docker user. If necessary, you can adjust permissions with sudo chown -R 1000:1000 stirling-data (the Docker container typically uses UID/GID 1000). Broad permissions like sudo chmod -R 777 stirling-data pose a security risk and should be used cautiously, with more restricted permissions preferred if possible.
- Insufficient Disk Space: Check if you have enough disk space on your server. The df -h command will give you disk usage information. Insufficient disk space can cause errors during file operations.
Inaccessibility via Nginx:
- Nginx Configuration Error: Check for errors in your Nginx configuration file (e.g., /etc/nginx/sites-available/stirling-pdf.conf) with the command sudo nginx -t. If there's an error, fix it and restart Nginx with sudo systemctl restart nginx.
- DNS Resolution Issue: Ensure your domain name (e.g., stirling.example.com) points to the correct IP address. You can check DNS records with dig stirling.example.com or nslookup stirling.example.com.
- Firewall Block: Make sure your server's firewall allows incoming connections on ports 80 (HTTP) and 443 (HTTPS). You can review firewall rules with sudo ufw status (for Ubuntu) or sudo firewall-cmd --list-all (for CentOS).

🔥 Memory Limits and OOM Issues

When processing large PDF files or performing memory-intensive operations like OCR, your container might hit its memory limit (Out Of Memory - OOM). You can resolve this by increasing the DOCKER_DEFAULT_MEMORY_LIMIT value in your docker-compose.yml file (e.g., 2048m or 4096m). However, be careful not to exceed your server's total RAM capacity.

These troubleshooting steps should help you resolve most problems you might encounter with your Stirling PDF installation. Remember, the first step in any problem is always to check the logs and monitor system resources.

Conclusion

Setting up Stirling PDF on your own server with Docker Compose provides full control over your PDF documents while maximizing privacy and security. With this setup, you avoid the risk of uploading your sensitive data to third-party cloud services. Integration with an Nginx reverse proxy further secures access by adding SSL/TLS encryption and additional security layers.

This guide covers the entire process, from basic Stirling PDF installation to secure access with Nginx. You now have your own PDF processing center and can securely process your documents entirely under your control. Especially for corporate or personal projects where data sovereignty is critical, Stirling PDF is a powerful and practical solution.

Official Resources

Top comments (3)

Mia Keller • Jul 30

That breakdown of self-hosting alternatives is really insightful. For someone spinning this up in a homelab or tight resource environment, do you have any specific recommendations for resource allocation regarding the OCR language packs, or is the default container configuration usually enough to handle heavier batches smoothly?

Mustafa ERBAY • Jul 30

It really depends on the workload. For basic PDF operations (merge, split, compress, rotate), the default configuration is usually sufficient. OCR is the exception—it is both CPU and memory intensive, especially when processing large scanned documents or multiple files concurrently.

In my experience, for a small homelab or a few users, 2 CPU cores and 2–4 GB RAM work well. If OCR becomes a regular workload or you’re processing large batches, I’d recommend increasing both the memory limit and CPU allocation, and installing only the language packs you actually need instead of every available language. That keeps both disk usage and OCR initialization time under control.

I also recommend monitoring container memory and CPU usage during real workloads before increasing limits. It’s usually better to size the container based on observed usage than to over-allocate resources from the start.

Mia Keller • Jul 30

Thanks for the detailed breakdown, Mustafa! That makes a lot of sense—especially keeping an eye on resource usage before over-allocating.

I hadn't thought about limiting the language packs upfront to help with OCR initialization times, but that's a great tip for keeping things lean. I’ll start with a conservative 2-core / 3 GB RAM setup and monitor how it handles batch jobs from there. Appreciate the advice!