A few months ago, I needed to digitally sign a rental lease agreement. It was loaded with my social security number, bank details, and personal phone number. I searched Google for a “free PDF editor,” clicked the first result, and was immediately asked to upload my sensitive document to a random server hosted who-knows-where.
Have you ever stopped to think about what happens to those files? The moment you upload your tax returns or medical records to a “free” cloud service, you are committing one of the most common OSINT mistakes. These free platforms rarely offer real End-to-End Encryption. Instead, they harvest your metadata, run your documents through AI data-mining algorithms (similar to the models powering the top free AI tools for students), and store your files on their servers indefinitely.
If you are trying to establish a secure, private digital life—or building an internal document pipeline following a strict software development lifecycle (SDLC)—you cannot rely on SaaS PDF editors.
This is where Stirling-PDF comes in. It is one of the best open-source software alternatives on the market: a fully local, Docker-based web application that gives you 60+ PDF tools (including merging, splitting, OCR, and redaction) directly on your own hardware. Your files never leave your network. In this guide, I’ll show you exactly how to deploy it.
1. Why Stirling-PDF is the FOSS Gold Standard
Stirling-PDF completely reverses the SaaS model. Instead of you sending your documents to the internet, you bring the processing engine to your documents.
By running Stirling-PDF inside a container, you leverage the exact same isolation benefits I talk about in my Docker vs Podman benchmark. Once you process a document (like compressing a massive 50MB manual down to 2MB), Stirling-PDF wipes the file from its temporary memory instantly. It leaves absolutely no trace, stopping Open Source Intelligence (OSINT) harvesting dead in its tracks.
If you don’t already have a server running, check out my guide on installing Docker on Ubuntu to get started. You can deploy it manually, use a PaaS like Dokploy, or even connect Stirling-PDF’s native REST API endpoints to n8n automation workflows to build invisible, automated document pipelines.
2. Under the Hood: The Architecture
Understanding what makes Stirling-PDF tick helps you optimize its performance. Unlike lightweight APIs you might build if you create a Node.js REST API, Stirling-PDF relies on a Java Spring Boot backend.
It acts as an orchestration layer for several heavy-duty, open-source libraries. For example, it bundles LibreOffice to convert .docx and .xlsx spreadsheets to PDF. It uses Ghostscript for HTML-to-PDF rendering and compression. Because it handles large binary streams, it manages massive HTTP data payloads directly in system RAM.
The beauty of Stirling-PDF is that it is completely stateless. It does not require a massive relational database, so you don’t need to worry about PostgreSQL vs MySQL tuning. It just spins up, processes the file, and idles. However, because it runs a Java Virtual Machine (JVM), you should occasionally check on it using the top 20 Linux security commands (like htop) to ensure it isn’t causing memory leaks, or manage its lifecycle via systemd processes.
3. Step-by-Step Docker Compose Installation
Let’s get this running on your server. I highly recommend running this on a cheap VPS running one of the best Linux distros for beginners, like Ubuntu 24.04 LTS.
Log into your server and create a project directory:
mkdir -p ~/stirling-pdf
cd ~/stirling-pdfTo edit the configuration file, you need a text editor. I despise Nano, so I recommend reading my guide on Micro vs Nano or picking another tool from my list of the top 13 Linux CLI text editors.
micro docker-compose.ymlPaste the following stack:
version: '3.8'
services:
stirling-pdf:
image: frooodle/s-pdf:latest
container_name: stirling-pdf
ports:
- "8080:8080"
volumes:
- ./trainingData:/usr/share/tesseract-ocr/4.00/tessdata
- ./extraConfigs:/configs
- ./customFiles:/customFiles/
environment:
- DOCKER_ENABLE_SECURITY=true
- SECURITY_INIT_ADMIN_USERNAME=admin
- SECURITY_INIT_ADMIN_PASSWORD=change_this_secure_password
- INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
- SYSTEM_DEFAULT_LOCALE=en-US
- UI_THEME=dark
restart: unless-stoppedBefore you spin this up, change change_this_secure_password. Use my Password Generator to create a randomized string, and verify it with the Password Strength Checker.
Bring the container online:
docker compose up -d4. User Authentication & Tesseract OCR
Because we set DOCKER_ENABLE_SECURITY=true, Stirling-PDF will block public access and require a login. You must immediately log in with your admin credentials and change your password in the account settings. Store this new credential in one of the best password managers, like a self-hosted Vaultwarden server or an offline vault like KeePassDX.
Once logged in, you’ll see dozens of tools. One of the most powerful is the OCR (Optical Character Recognition) engine, powered by Tesseract.
Tesseract bridges the gap between old-school image scanning and modern machine learning vs deep learning algorithms. It analyzes flat images (like a scanned photo of a receipt) and turns them into selectable, searchable text PDFs.
By default, the Docker image only includes English OCR training data. If you need Spanish, French, or German, download the .traineddata files from the official Tesseract GitHub repository and drop them into the ./trainingData directory we mapped in the compose file. If you aren’t sure how to move files on a headless server, use the Linux Command Explorer to learn the mv and wget commands.
5. Reverse Proxy Setup (Crucial for Large Uploads)
If you plan to use Stirling-PDF outside your home network, you must secure it with HTTPS. My preferred method is the Caddy web server. Caddy will automatically enable HTTPS with Let’s Encrypt.
Alternatively, if you prefer a GUI, my Nginx Proxy Manager security guide covers exactly how to map internal ports. The most critical step here is bypassing default proxy upload limits.
By default, Nginx limits client uploads to 1MB. If you try to upload a 50MB PDF textbook, Nginx will throw a 413 Payload Too Large error.
If you are using a raw Nginx configuration (which you can build easily using my Nginx Config Generator), ensure you include the client_max_body_size directive:
server {
listen 443 ssl http2;
server_name pdf.yourdomain.com;
# Increase maximum upload file size
client_max_body_size 100M;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
}
}Assuming you know how DNS works, point an A record to your server, apply this configuration, and your connection will be fully encrypted.
6. The Danger of Fake Redaction
One of the most important tools in Stirling-PDF is the Redaction feature.
When people want to censor a bank account number on a PDF, they often open a basic editor and draw a black rectangle over the text. This is a fatal security flaw. A black rectangle does not delete the text; it just covers it. Anyone can open the document, click the text underneath the rectangle, and copy-paste it into Notepad.
Stirling-PDF’s Redaction tool actually alters the underlying document structure. It strips the text vector paths from the file completely and burns flat black pixels into the layout, ensuring the data is permanently eradicated.
Because Stirling-PDF handles these operations efficiently, you can pair it with secure Docker containers to process sensitive HR documents at scale. If you are collaborating with a team, you can manage the raw files on the host using precise Linux file permissions (verified via my Linux Permission Calculator), transfer them securely via SFTP, and finally store the redacted copies long-term in a Nextcloud instance.
7. Troubleshooting and Maintenance
Running a JVM-based application means you need to keep an eye on memory. If you try to OCR a 500-page document on a server with 1GB of RAM, the container will crash with an Out-of-Memory (OOM) error. If this happens, you either need to add swap space to your Linux host or upgrade your RAM.
To keep your application secure from external threats, immediately lock down your exposed ports using my UFW firewall guide and install Fail2ban to block brute-force login attempts against your web dashboard. Always check the website URL before clicking a link to ensure you aren’t logging into a spoofed phishing page of your own PDF server.
Finally, set up a ping monitor using Uptime Kuma to alert you if the container goes offline, review my secure home server checklist, and implement automated snapshot routines based on my home server backup strategies.
Frequently Asked Questions (FAQ)
What is Stirling-PDF?
Stirling-PDF is a robust, open-source web application that provides over 60 different PDF manipulation tools. It allows you to merge, split, compress, watermark, redact, and OCR documents directly in your web browser.
Why should I self-host my PDF tools?
Privacy. When you use free online PDF editors, you upload your personal documents to third-party servers where they can be scanned, harvested for data, or stolen in a breach. Self-hosting Stirling-PDF guarantees that your files never leave your local machine or trusted private server.
Does Stirling-PDF keep copies of my files?
No. Stirling-PDF is designed with privacy in mind. It processes files in system memory or temporary directories and wipes them immediately after the process finishes or the file is downloaded. It does not permanently store your documents.
What are the system requirements for Stirling-PDF?
Because it runs on Java and bundles heavy tools like LibreOffice and Tesseract OCR, it requires at least 1GB of RAM for basic operations. If you plan to OCR massive documents or run complex conversions, 2GB to 4GB of RAM is highly recommended to prevent Out-of-Memory (OOM) crashes.
How do I enable user logins and passwords?
In your docker-compose.yml file, set the environment variable DOCKER_ENABLE_SECURITY=true. This will activate the authentication system, forcing users to log in before accessing any PDF tools. You can configure the default admin credentials in the same file.
Can Stirling-PDF convert Word documents to PDF?
Yes! Stirling-PDF bundles LibreOffice inside the Docker container. This allows you to natively convert Microsoft Office files (.docx, .xlsx, .pptx) into pristine PDF documents without needing a Microsoft license.
Why do my large PDF uploads fail with an error?
If you are running Stirling-PDF behind a reverse proxy like Nginx or Caddy, the proxy usually imposes a strict file upload limit (often 1MB). You must configure your proxy to accept larger payloads. In Nginx, this is done by adding client_max_body_size 100M; to your server block.
Does Stirling-PDF support API automation?
Absolutely. It features a fully documented REST API. This allows developers to integrate Stirling-PDF into automated pipelines, meaning you can use tools like n8n or Python scripts to automatically compress or watermark PDFs as they arrive in a specific folder.
How do I add more languages to the OCR tool?
Stirling-PDF uses Tesseract OCR, which defaults to English. To add more languages, download the specific .traineddata files (like fra.traineddata for French) from the official Tesseract GitHub repository and place them into the ./trainingData folder mounted to your container.
Is the redaction tool actually secure?
Yes. Unlike cheap PDF editors that simply draw a black square over text, Stirling-PDF’s redaction tool strips the vector text data from the underlying file structure. The text is physically removed and replaced with black pixels, making it impossible to copy or extract.
Discussion
Loading comments...