Skip to content
Klutch.sh Docs

Deploying a Stirling-PDF App

Introduction

Stirling-PDF is an open-source suite for manipulating PDF files—merging, splitting, converting, and more. Deploying Stirling-PDF with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for uploads—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample requests.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Stirling-PDF Dockerfile (GitHub is the only supported git source)
  • Optional: external storage if you prefer object storage for processed files

For onboarding, see the Quick Start.

Architecture and ports

  • Stirling-PDF serves HTTP on internal port 8080. Choose HTTP traffic and set the internal port to 8080.
  • Persistent storage is recommended for uploads and processed documents.

Repository layout

stirling-pdf/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally:

Terminal window
docker build -t stirling-pdf-local .
docker run -p 8080:8080 \
  -e PORT=8080 \
  stirling-pdf-local

Dockerfile for Stirling-PDF (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM frooodle/s-pdf:latest


ENV PORT=8080


EXPOSE 8080
CMD ["java", "-jar", "/app.jar"]

Notes:

  • Pin to a specific tag (e.g., frooodle/s-pdf:0.41.2) for stability.
  • app.jar starts the web server on the configured port.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=8080
  • Optional security: SPRING_SECURITY_USER_NAME / SPRING_SECURITY_USER_PASSWORD for basic auth
  • Optional file paths: adjust if you relocate storage paths in your image

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=java -jar /app.jar

Attach persistent volumes

Add storage in Klutch.sh (path and size only):

  • /data — uploads and processed PDFs (adjust if your image uses a different path).

Ensure the path is writable inside the container.

Deploy Stirling-PDF on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add environment variables (port, optional basic auth credentials).
  5. Attach a volume at /data sized for your uploads and generated PDFs.
  6. Deploy. Your app will be reachable at https://example-app.klutch.sh.

Sample requests

Health check:

Terminal window
curl -I https://example-app.klutch.sh

Example PDF merge (replace endpoint/params with the app’s API routes if exposed):

Terminal window
curl -X POST https://example-app.klutch.sh/api/merge \
  -F "files=@/path/to/file1.pdf" \
  -F "files=@/path/to/file2.pdf" \
  -o merged.pdf

Health checks and production tips

  • Add an HTTP readiness probe to / or your health endpoint.
  • Keep any auth credentials in Klutch.sh secrets; rotate regularly.
  • Pin image versions and test upgrades in staging before production rollout.
  • Monitor /data volume usage; resize proactively as files accumulate.

Stirling-PDF on Klutch.sh delivers reproducible Docker builds, managed secrets, and persistent storage—without extra YAML or CI steps. Configure ports, env vars, and storage, then start processing PDFs.