# Project pack: Paperless-ngx @ f25fd53

Facts about **Paperless-ngx** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Paperless-ngx turns paper into a searchable archive. Scan or photograph a letter, drop in a PDF or forward an email, and it reads the text, files it and suggests who it is from and what kind of document it is. Find any bill, payslip, warranty or school letter by typing a word. It runs on your own computer or server, so your private documents stay at home.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/paperless-ngx/paperless-ngx
- Pinned commit: `f25fd5365fcc32d06c24306535c7b55e93fbb259`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/paperless-ngx/paperless-ngx/archive/f25fd5365fcc32d06c24306535c7b55e93fbb259.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.paperless-ngx.com
- Live demo: https://demo.paperless-ngx.com (username: demo / password: demo). Shared demo; content is reset often. Don't upload real documents.
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/paperless-ngx/paperless-ngx bespoke-paperless-ngx
  cd bespoke-paperless-ngx
  git checkout --detach f25fd5365fcc32d06c24306535c7b55e93fbb259
  # Prepare development requirements and local configuration first.
  # Setup notes: then in src-ui/: pnpm install && pnpm ng serve
  cd src && uv run manage.py runserver & uv run manage.py document_consumer & uv run celery --app paperless worker
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
  # or: copy docker/compose/docker-compose.sqlite.yml and docker-compose.env, set PAPERLESS_SECRET_KEY,
  # run docker compose pull && docker compose up -d, then open http://localhost:8000 and create the admin user
  ```
- Tools these commands use: Docker with Docker Compose, For development, Python 3.11+ with uv, Node.js 24+ with pnpm, and Redis
- Develop: `cd src && uv run manage.py runserver & uv run manage.py document_consumer & uv run celery --app paperless worker   # then in src-ui/: pnpm install && pnpm ng serve`
- Test: `cd src && uv run pytest   # frontend: cd src-ui && pnpm ng test`
- Check/lint: `uv run prek run --all-files   # frontend: cd src-ui && pnpm ng lint`
- Stack: python, typescript, html, scss (Django, Django REST framework, Celery, Angular, Bootstrap). Difficulty for a non-developer with an AI: **moderate**. Tags, matching rules, workflows, mail rules and custom fields cover most household needs without code. Code changes mean a Django backend (src/) and an Angular frontend (src-ui/), plus Redis and a Celery worker for processing.
Personal data: **yes**. Stored in: Original and archived files in the media volume; database (SQLite by default, or PostgreSQL/MariaDB) in the data volume. Files dropped in ./consume are imported; ./export holds exports. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/paperless-ngx/f25fd53/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/paperless-ngx/f25fd53/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/paperless-ngx/f25fd53/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/paperless-ngx/f25fd53/r3/SKILL.md)