# Project pack: Stirling-PDF @ 5c59188

Facts about **Stirling-PDF** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Stirling-PDF is a self-hosted toolbox for PDF files. It can merge, split, rotate, compress, redact, sign, add watermarks, convert to and from other formats, and read scanned pages with OCR. Files are processed on your own machine, so your documents are not uploaded to a third-party service.

## Version and source
- Repository: https://github.com/Stirling-Tools/Stirling-PDF
- Pinned commit: `5c59188758c14efb9c5df1bd28e1e9ed568c6e45`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/Stirling-Tools/Stirling-PDF/archive/5c59188758c14efb9c5df1bd28e1e9ed568c6e45.zip
- Official docs: https://docs.stirlingpdf.com
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice. The app/proprietary and app/saas folders are under a separate commercial licence.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/Stirling-Tools/Stirling-PDF bespoke-stirling-pdf
  cd bespoke-stirling-pdf
  git checkout --detach 5c59188758c14efb9c5df1bd28e1e9ed568c6e45
  # Prepare development requirements and local configuration first.
  task dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name stirling-pdf -p 8080:8080 -v stirling-data:/usr/share/tessdata docker.stirlingpdf.com/stirlingtools/stirling-pdf
  # then open http://localhost:8080
  ```

- Needs: Docker for a trial; JDK 21, Node 22 and the Task runner for development
- Develop: `task dev`
- Build: `task build`
- Stack: java, typescript, python (Spring Boot, React, Gradle, Taskfile). Difficulty for a non-developer with an AI: **advanced**. A large Java back end with a React front end and an optional Python engine. Using it needs no code; adding or changing a PDF tool means touching the Java service and the React tool list.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **tool-visibility** [settings]: Hide or show tools and pick languages. → `Settings → Preferences and the settings.yml config`
- **login-and-users** [settings]: Require login and create users. → `settings.yml security section`
- **pipelines** [extend]: Chain tools into a repeatable workflow, or call them from scripts. → `Pipeline feature and the REST API at /swagger-ui`
- **front-end** [code]: Tool pages, themes and layout. → `frontend/`
- **new-tool** [code]: Add a new PDF operation. → `app/core/src/main/java/stirling/software/SPDF/controller`

## Must keep working
- Files are processed locally and deleted after use. Don't add uploads to third-party services.
- The REST API contracts that scripts rely on.
- Security checks when login is on.

## Staying updatable
Prefer configuration, pipelines and the REST API. Add new tools in new controllers, and stay out of the proprietary folders.

## Data, costs and safety
- Personal data: **yes**. Stored in: Uploaded files are processed in temporary storage and removed. Optional settings and login data live in a config folder. PDFs can hold very private information. Keep the server on your own network unless you add a login.
- Setting `SECURITY_ENABLELOGIN`: Set to true to require a login before using the tools.
- Setting `LANGS`: Interface and OCR languages to enable.
- Online PDF sites can keep your files. Running this yourself avoids that, but only if you keep it off the public internet or add a login.
- Redaction tools should be verified by opening the result. Check that text is truly removed.

---

# Customising Stirling-PDF

Stirling-PDF needs no code for everyday use. Source changes mean the Java service and the React front end.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Java back end and PDF operations | app/core/src/main/java/stirling/software/SPDF/ |
| Shared code | app/common/ |
| React front end | frontend/ |
| Python engine (AI and conversions) | engine/ |
| Docker files and examples | docker/ |
| Developer guide | docs/developer/DeveloperGuide.md |

## Use the gentlest change first

1. **Settings (no code):** enabled tools, languages, login and branding in `settings.yml`.
2. **Extend:** pipelines and the REST API.
3. **Code:** new tools and screens.

## Recipes

- **Script it:** open `/swagger-ui` on your running instance, find the endpoint you need, and call it with curl or Python.
- **New tool:** add a controller that takes a PDF and returns a PDF, then register it in the front end tool list.

## Running and checking your changes

- `task dev` starts back end and front end on free ports.
- `task` lists build and test commands.
- Run your new tool on a small PDF and open the result in two viewers.

## Pitfalls

- OCR needs the language data in the tessdata folder.
- Never log or keep uploaded file contents.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/stirling-pdf/5c59188/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/stirling-pdf/5c59188/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/stirling-pdf/5c59188/r2/SKILL.md)