Engrafo
A minimal self-hostable document archive — the short path through Paperless-ngx,
and nothing else.
cubicecho.github.io/engrafo
Upload a file. It goes straight into an S3-compatible bucket, a small pipeline
runs over it, the text it found lands in a second bucket, and what came out is on
the document's page. Postgres holds the metadata and nothing bulky. That is the
whole product.
- Upload — drag in a folder's worth of PDFs or scans, each with its own
progress bar. The browser uploads directly to the bucket; the server only
signs the URL.
- OCR, optionally —
ocrmypdf with Paperless's own flags, so a scan becomes
a searchable PDF/A plus the plain text it found. A born-digital PDF keeps the
text layer it already has.
- EPUB — an ebook's text is read in-process, no extra tools, with each
chapter named from the book's table of contents.
- Search — by meaning and by exact words at once, over every document's
text and title, with the passage that matched. Runs on this machine: a small
embedding model (granite-embedding-small, about 50 MB, baked into the image)
and Postgres's full-text search, fused the way mcp-ragdown does it. Each
person searches only their own documents. A search can be narrowed to a
folder (and everything in it), a kind of file (PDF, image, text, ebook), a
range of document dates, or receipts only.
- Document dates — the date printed on a receipt, letter or invoice is read
from its text (ISO,
12.03.2025, 03/12/2025, 12 March 2025), shown on the
document, and yours to correct. A date you set or clear is never replaced
when the document is processed again.
- Receipts — a receipt's vendor, total and currency are read from its text
by plain rules (no AI model), shown on the document and editable there, and
exported as a CSV (
date,vendor,total,currency,title,folder) for a date
range or a folder. Fields it is unsure of are left empty rather than guessed:
a bare $ is several currencies, and a document with no labelled total is
not taken for a receipt.
- Folders — file documents into folders, nested as deep as you like, and
see the archive as a tree in the sidebar, on every page. Drag a document or a folder onto another folder,
or use "Move to…". Names are unique within a folder, ignoring case, the way
files are: a second upload of
scan.pdf becomes scan (2), and a rename or
move onto a taken name is refused rather than overwriting. Deleting a folder,
once you have typed its name, puts everything in it in the Trash.
- Trash — a deleted document goes to the Trash rather than away: restore it
to the folder it came from (the top level, if that folder was deleted too,
and numbered if its name has been taken since), delete it forever, or empty
the Trash. What has sat there for
TRASH_RETENTION_DAYS (30) is deleted for
good on its own. Until then it is out of search, the tree and MCP, but its
files are still stored.
- Duplicate warnings — upload a file you already have and Engrafo says so,
on the upload's row and on the document's page, with a link to the other
copy and a way to delete this one. It warns rather than refuses, since the
same file in two folders is sometimes what you meant. Files are compared by
their SHA-256, and only against your own documents.
- MCP for AI agents — share a folder from its menu, make an API key in
Settings, and an MCP client (Claude Code, Claude Desktop, any other) can
list, search and read what is in it. Sharing a folder shares the folders
inside it; nothing else is visible, and the tools are read-only. See
Connecting an agent.
- A watched folder — point a scanner's network share at
WATCH_DIR and
whatever lands there is filed into one account's archive, its subfolders
as folders, then removed. Paperless's consume folder. See
The watched folder.
- A pipeline you can watch — every step is a row with a status, so a document
says where it got to, and a failed one says why and offers a retry.
- Preview, download, rename, delete — the archived PDF where there is one,
the original otherwise.
- Sign-in by magic link, through an OpenID Connect provider such as
heautou, or with no link at all on a private instance.
No tags, no correspondents, no mail ingestion. Folders are the one way to
organise. Those are what Paperless is for.
Quickstart
Four containers: Engrafo, Postgres, RustFS, and a one-shot job that creates the
two buckets. The app and the API are served from the same origin; the bucket is
its own, because browsers upload to it directly.
Nothing to clone and nothing to build —
docker-compose.quickstart.yml pulls a
published image. Its header comments are the install instructions, and they
repeat what is below.
mkdir engrafo && cd engrafo
curl -fsSLO https://raw.githubusercontent.com/cubicecho/engrafo/main/docker-compose.quickstart.yml
# The three secrets it refuses to start without, plus the address you reach it at.
printf 'ENGRAFO_HOST=%s\nBETTER_AUTH_SECRET=%s\nPOSTGRES_PASSWORD=%s\nRUSTFS_PASSWORD=%s\n' \
"$(hostname -f)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" "$(openssl rand -hex 24)" > .env
docker compose -f docker-compose.quickstart.yml up -d
On TrueNAS SCALE or Portainer, paste the file's contents instead of
downloading it — Portainer's Stacks → Add stack → Web editor, or TrueNAS's
Apps → Discover → Custom App → Install via YAML — and put the four variables in
the stack's environment-variables box.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
