Deploy Stirling PDF with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it easy to self-host your own PDF toolkit.

This guide walks you through deploying Stirling PDF with authentication enabled, persistent configuration, and automatic HTTPS. Stirling PDF provides a comprehensive set of PDF tools (merge, split, convert, compress, OCR, and more) through a web interface.

Prerequisites

• A VPS with at least 1 vCPU, 2 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., pdf.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - SECURITY_ENABLELOGIN=${SECURITY_ENABLELOGIN:-true}
      - SECURITY_INITIALLOGIN_USERNAME=${SECURITY_INITIALLOGIN_USERNAME:-admin}
      - SECURITY_INITIALLOGIN_PASSWORD=${SECURITY_INITIALLOGIN_PASSWORD}
      - LANGS=${LANGS:-en_GB}
      - SYSTEM_DEFAULTLOCALE=${SYSTEM_DEFAULTLOCALE:-en-US}
      - SYSTEM_MAXFILESIZE=${SYSTEM_MAXFILESIZE:-2000}
    volumes:
      - ../files/stirling-pdf-configs:/configs
      - ../files/stirling-pdf-tessdata:/usr/share/tessdata
      - ../files/stirling-pdf-logs:/logs
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: For additional PDF processing capabilities (LibreOffice conversions, OCR), use the fat variant: stirlingtools/stirling-pdf:latest-fat. This image is larger but includes extra tools for advanced operations.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
SECURITY_ENABLELOGIN	Enable user authentication	true
SECURITY_INITIALLOGIN_USERNAME	Initial admin username	admin
SECURITY_INITIALLOGIN_PASSWORD	Initial admin password	a-strong-password
LANGS	Available interface languages	en_GB
SYSTEM_DEFAULTLOCALE	Default locale	en-US
SYSTEM_MAXFILESIZE	Maximum upload file size in MB	2000

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Always enable authentication (SECURITY_ENABLELOGIN=true) for production deployments and change the default password immediately after first login.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/stirling-pdf-configs — Application settings, user database (SQLite), and custom configurations
• ../files/stirling-pdf-tessdata — Tesseract OCR language data files (download additional languages as needed)
• ../files/stirling-pdf-logs — Application logs

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/stirling-pdf) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., pdf.yourdomain.com)
3. Set the container port to 8080
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Stirling PDF container.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the stirling-pdf container pull and start
3. Check the Logs tab for the stirling-pdf service. Look for the Spring Boot startup message indicating the server is running on port 8080
4. Open https://pdf.yourdomain.com in your browser — you should see the Stirling PDF login page
5. Log in with your initial admin credentials and change the password
6. Test a PDF operation (e.g., merge two PDF files or convert a document to PDF) to verify everything works

Troubleshooting

Login page not appearing (direct access to tools) Verify SECURITY_ENABLELOGIN is set to true in your environment variables. Without this, Stirling PDF is accessible without authentication. Redeploy after changing the variable.

File upload fails with "413 Request Entity Too Large" Increase SYSTEM_MAXFILESIZE in the environment variables. If Dokploy's Traefik proxy is also limiting upload size, you may need to add Traefik labels for traefik.http.middlewares.limit.buffering.maxRequestBodyBytes in the compose file.

OCR features not working The standard image includes basic OCR support. For full OCR capabilities, switch to the fat variant (stirlingtools/stirling-pdf:latest-fat). Additional Tesseract language packs can be placed in the ../files/stirling-pdf-tessdata volume.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Stirling PDF in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Stirling PDF.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.