Paperjet/README.md

PaperJet

PaperJet is a self-hosted, single-user PDF annotation editor. It keeps the uploaded PDF immutable, stores annotations separately, autosaves the working layer, and flattens supported annotations only when exporting.

Run with Docker

1. Copy .env.example to .env.
2. Replace SECRET_KEY with a long random value. Compose refuses to start without it.
3. Start the stack:

docker compose up --build -d

Open http://localhost:4982 (or the value of HTTP_PORT). The first visit asks you to create the single master password.

The db, pdf_storage, and thumbnails volumes contain application data. Back them up before maintenance or upgrades. Put the frontend behind HTTPS when exposing PaperJet beyond localhost and set COOKIE_SECURE=true.

Development

Backend:

cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload

Frontend, in a second terminal:

cd frontend
npm ci
npm run dev

The Vite server proxies /api to http://localhost:8000.

Validation

# frontend
cd frontend
npm test -- --run
npm run typecheck
npm run lint
npm run build

# backend
cd ../backend
pytest -q
mypy app/
ruff check .

The editor uses PDF.js for display and PyMuPDF for export. Stored annotation coordinates are PDF points with a top-left origin relative to the unrotated CropBox; this is the contract shared by the editor and export renderer.