Papra: the open source document management system to archive invoices and contracts on your own server
Papra is an open source document management system built for one job: keeping invoices, contracts, warranties and receipts for years and finding them in seconds when you need them. You run it on your own server as a single Docker container, upload files (or forward them by email, or drop them into a folder), and Papra extracts the text with OCR, indexes it for search and tags it automatically, with rules or with an AI model if you turn that on.
For a small business or an agency it is a lightweight digital archive: no per-seat licenses and no handing your documents to a SaaS. In this review we read its source code (app 26.7.1, main branch as of October 31, 2026) to explain what it really does, how it is built, how to deploy it right the first time and which errors you are going to hit.
What Papra is and who maintains it
- Repository: github.com/papra-hq/papra
- Version reviewed:
@papra/app26.7.1. It uses year-based versions (YY.MINOR.PATCH): 26.x are the 2026 releases, and only the latest one gets patches, so you have to upgrade to receive security fixes. - License: AGPL-3.0 (more on that below).
- Author: Corentin Thomasset, with outside contributors. Funded through sponsorships.
- Stack: SolidJS + UnoCSS on the client, Hono + Drizzle + Better Auth on the server, SQLite (libSQL) as the database, in a pnpm monorepo.
- UI languages: 17.
- Stated inspiration: Paperless-ngx, the best-known self-hosted document manager.
A note on the license
On codigoagente we usually cover MIT projects; Papra is not one. The AGPL-3.0 lets you use it for free, including inside your company and for client documents. The obligation kicks in if you modify the code and offer that version to others over a network (for example, as a SaaS for third parties): then you must publish your changes under the same license. If you deploy it as-is for your team, you don't have to do anything.
What Papra does: features in 26.7.1
| Area | What it includes |
|---|---|
| Document intake | Web upload, intake email (a generated address per organization), watched folder, REST API, SDK (`@papra/api-sdk` 1.4.0) and CLI (`@papra/cli` 0.2.6) |
| Organization | Organizations with members and invitations, tags with descriptions, per-organization custom properties, document date |
| Text and search | Text extraction and OCR, full-text search with filters (`tag:`, `content:`, `created:`...) |
| Automation | Condition-based tagging rules, AI auto tagging, signed webhooks |
| Sharing | External links with optional expiry and password |
| Security | Optional AES-256-GCM file encryption, optional database encryption, OAuth (GitHub, Google or custom providers), 2FA |
| Administration | `/admin` panel (read-only for now) and first user as admin |
The monorepo also includes a React Native mobile app built with Expo (apps/mobile, version 1.1.0), even though the README still lists it as "maybe one day". We did not check whether it is in the app stores.
How it works under the hood
Three design decisions set it apart from heavier alternatives.
1. It never modifies the original file. The "no mutation" principle is documented and the code follows it: Papra does not convert formats, inject metadata or overlay an OCR layer on scanned PDFs. What you upload is exactly what you download. The extracted text lives in the database, not inside the file. For a legal or accounting archive, that is exactly what you want.
2. Content-based deduplication. On upload it computes a SHA-256 hash while streaming the file. The database has a unique index on (organization_id, original_sha256_hash), so the same PDF is never stored twice in an organization, even under a different name. If the duplicate was in the trash, it gets restored instead.
3. One process and SQLite. No PostgreSQL or Redis required. By default the database is a SQLite (libSQL) file, search uses SQLite's FTS5 index, and the background job queue (CadenceMQ, by the same team) persists in memory or in libSQL. If you outgrow that, you can split the API and the workers with PROCESS_MODE=web and PROCESS_MODE=worker, and point DATABASE_URL and DATABASE_AUTH_TOKEN at Turso or another remote libSQL.
Papra vs Paperless-ngx
| Papra | Paperless-ngx | |
|---|---|---|
| License | AGPL-3.0 | GPL-3.0 |
| Required services | One container (SQLite included) | Django app + Redis, usually PostgreSQL |
| Original file | Kept untouched, no OCR layer | Keeps the original and also generates an archived PDF with text |
| Storage | Disk, S3 or Azure Blob | Disk |
| AI tagging | Built in and optional (OpenAI, Anthropic, Ollama...) | Its own classifier trained on your documents |
| Maturity | Young project, fast release cycle | Years in production and a large ecosystem |
If you already run Paperless-ngx and it works for you, there is no strong reason to migrate. Papra is a better fit when you want something that deploys in five minutes, stays small and stores originals in S3.
Install Papra with Docker
The quick test is a single command, but AUTH_SECRET must be at least 32 characters; generate yours with openssl rand -hex 48:
docker run -d \
--name papra \
--restart unless-stopped \
--env APP_BASE_URL=http://localhost:1221 \
--env AUTH_SECRET=<your-auth-secret> \
-p 1221:1221 \
ghcr.io/papra-hq/papra:latestOpen http://localhost:1221 and create your account: with AUTH_FIRST_USER_AS_ADMIN=true (the default) the first registered user becomes the admin. Without volumes, the data is gone when you remove the container, so this is for testing only.
The latest image is the *rootless* variant (recommended). There is also latest-root, per-version tags, and a Docker Hub mirror (corentinth/papra) if GHCR gives you trouble. We pulled the image from Docker Hub without issues.
Docker Compose for production
This is the setup we recommend for a VPS: persistent data, multi-language OCR, file encryption, an ingestion folder, and registration closed once your account exists. Create the structure:
mkdir -p papra/app-data/{db,documents} papra/ingestion && cd papraCreate a .env next to the compose file with your secrets and your user. PUID and PGID come from id -u and id -g:
AUTH_SECRET=paste-openssl-rand-hex-48-here
PAPRA_KEK=paste-openssl-rand-hex-32-here
PUID=1000
PGID=1000And the docker-compose.yml:
services:
papra:
container_name: papra
image: ghcr.io/papra-hq/papra:latest
restart: unless-stopped
ports:
- "1221:1221"
environment:
- APP_BASE_URL=https://docs.yourdomain.com
- AUTH_SECRET=${AUTH_SECRET}
- DOCUMENTS_OCR_LANGUAGES=eng,spa
- DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true
- DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS=${PAPRA_KEK}
- INGESTION_FOLDER_IS_ENABLED=true
volumes:
- ./app-data:/app/app-data
- ./ingestion:/app/ingestion
user: "${PUID}:${PGID}"docker compose up -d
docker compose logs -fThree details in this setup:
DOCUMENTS_OCR_LANGUAGESdefaults toeng. If you have documents in other languages, add them (spa,fra,deu...) or OCR on scans will come out garbled. Any Tesseract language works, comma-separated.APP_BASE_URLmust be the exact public URL you use (withhttps://). Papra validates the origin of every request against CSRF and will reject your login if it doesn't match.- Close registration once you have your account: add
AUTH_IS_REGISTRATION_ENABLED=falseand rundocker compose up -dagain. Registration is open by default, so anyone with the URL can create an account on your instance.
Any reverse proxy works to put it behind a domain with HTTPS. If you already use Coolify, the procedure is the same one we followed in installing Paymenter on a VPS with Coolify: a Docker Compose resource, the domain on the service, and Coolify handles the certificate.
Configuring it: encryption, OCR, AI and intake
Document encryption
With encryption on, each document gets its own random 256-bit key (DEK) and is encrypted with AES-256-GCM. That key is stored in the database, wrapped with your master key (KEK, the DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS variable). Someone who steals only the storage (the S3 bucket, say) can't read anything without both the database and the environment variable.
Two warnings: turning encryption on doesn't encrypt documents you already had (the project's storage migration guide covers that), and if you lose the KEK, the files are unrecoverable. Put it in your password manager the same day. The variable accepts several versioned keys for rotation.
Text extraction and OCR
CONTENT_EXTRACTION_STRATEGY takes a list of strategies in order of preference; if the first fails or doesn't handle the file type, it tries the next:
| Strategy | What it uses | Needs |
|---|---|---|
| `internal` | The project's `lecture` library + Tesseract | Nothing (default) |
| `mistral-ocr` | Mistral's OCR API | `MISTRAL_API_KEY` |
| `docling` | Your own Docling server | `DOCLING_BASE_URL` |
| `azure-di` | Azure Document Intelligence | Endpoint and key |
| `custom-http` | Your own HTTP service | URL |
Always keep internal last as a safety net: CONTENT_EXTRACTION_STRATEGY=mistral-ocr,internal. Keep in mind that with external strategies the document content leaves your server for that provider.
AI auto tagging
It ships off. You need AI_IS_ENABLED=true and a model in <adapter>://<model> form. There are adapters for OpenAI, Anthropic, Mistral, DeepSeek, OpenRouter, Ollama, LM Studio, vLLM and any OpenAI-compatible API. To keep documents inside your network, a local model is the natural choice:
AI_IS_ENABLED=true
AI_DEFAULT_MODEL=ollama://qwen3:8b
OLLAMA_BASE_URL=http://ollama:11434/v1Each organization then turns it on in its settings and decides whether the AI may create new tags and the maximum number it applies per document (5 by default).
The model decides based on each tag's name and description, so clear descriptions ("Supplier invoices with VAT, not card receipts") make a big difference. If you prefer something deterministic and free, tagging rules apply tags based on conditions on the name or content, and have a button to apply them to existing documents.
Ingestion folder and email
With INGESTION_FOLDER_IS_ENABLED=true, Papra watches /app/ingestion. Each organization gets a subfolder named after its ID (the org_... in the URL); loose files in the root are ignored:
mkdir -p ingestion/org_yourid
cp ~/scanner/*.pdf ingestion/org_yourid/By default it deletes the file after import; with INGESTION_FOLDER_POST_PROCESSING_STRATEGY=move it moves it to ingestion-done/. If import fails, the file is left in ingestion-error/ so nothing is lost. It is the easiest way to connect a network scanner or a synced folder.
Email intake generates an address per organization and needs a service that receives the emails and delivers them via webhook: OwlRelay or a Cloudflare Email Worker, both documented by the project.
Searching documents
Search combines free text with filters, logical operators and parentheses:
tag:invoices supplier
content:"lease agreement"
created:>2026 -has:tags
name:warranty OR name:garantianame: and content: match on "contains", not exact equality. -has:tags is handy for a weekly review of documents that ended up untagged.
API, CLI and webhooks
Create an API key in your user settings, then use it with the CLI:
npm i -g @papra/cli
papra config init
papra config set default-org-id org_yourid
papra documents import october-invoice.pdfWebhooks notify another system on document:created, document:updated, document:deleted, document:tag:added and document:tag:removed, with a signature to verify the source. For example, you can ping your accounting system whenever a document tagged "invoices" arrives. The server ships with SSRF protection on webhook URLs enabled by default: if your target is on the internal network, add it to WEBHOOK_URL_ALLOWED_HOSTNAMES instead of disabling the protection.
Common errors
bash: UID: readonly variable and The "UID" variable is not set. Defaulting to a blank string. The docs suggest starting compose with UID=$(id -u) GID=$(id -g) docker compose up -d. In bash, UID is read-only and not exported: we tested it on bash 5.2 with Docker Compose 5.6 and got user: :0 (no user, root group). That's why our compose uses PUID and PGID in .env, or you can hard-code the numbers (user: "1000:1000").
Error: EACCES: permission denied, mkdir './app-data/db'. The rootless image runs as your user and can't create folders if the mounted directory belongs to someone else. Create app-data/db and app-data/documents before starting and check the owner matches PUID:PGID.
Please provide an auth secret using the AUTH_SECRET environment variable or In production, the auth secret must not be the default one. The secret is missing, shorter than 32 characters, or still the default. Generate one with openssl rand -hex 48.
Invalid origin error on login. APP_BASE_URL doesn't match the browser URL (http vs https, another subdomain or a different port). Fix it or add the extra origin to TRUSTED_ORIGINS, comma-separated.
Document already exists. Not a bug: that exact content is already in the organization under another name. Find it with name: or check the trash.
Document size too large. The default limit is 25 MB. Raise it with DOCUMENT_STORAGE_MAX_UPLOAD_SIZE (in bytes) and check your reverse proxy's limit too.
OCR returns gibberish on non-English documents. The language is missing from DOCUMENTS_OCR_LANGUAGES. After changing it you can reprocess existing documents: version 26.7.0 added reprocessing (DOCUMENT_REPROCESSING_ENABLED, on by default).
FAQ
Is Papra free? Yes. The code is AGPL-3.0 and the self-hosted version has no paid limits. The project has paid plans for its managed instance, but they don't apply on your server.
Is Papra an alternative to Paperless-ngx? It covers the same use case (archiving and searching documents with OCR) with a lighter approach: one container, SQLite and untouched originals. Paperless-ngx is more mature and has a bigger ecosystem.
Do my documents leave my server? No, unless you enable external extraction strategies (Mistral, Azure, remote Docling) or a cloud AI model. With internal and Ollama everything stays on your machine.
Can I store files in S3 or a compatible bucket? Yes. DOCUMENT_STORAGE_DRIVER accepts filesystem, s3 and azure-blob. For MinIO, Cloudflare R2 and similar, use the s3 driver with DOCUMENT_STORAGE_S3_ENDPOINT and, if needed, DOCUMENT_STORAGE_S3_FORCE_PATH_STYLE=true.
How do I back it up? Copy the whole app-data/ folder (SQLite database and documents) and keep the .env with AUTH_SECRET and the KEK somewhere else. Without the KEK, a backup of encrypted documents is useless.
Does it work for a firm or company with several users? Yes, through organizations with members and invitations. An organization has three roles (owner, admin and member); if you need fine-grained permissions per folder or per document, it doesn't have them yet.
Conclusion
Papra does a few things and does them well: it keeps the original as-is, avoids duplicates, extracts the text and lets you find everything with one search. Running as a single container on SQLite makes it very easy to deploy and maintain on a small VPS, and AI is an extra you can ignore or wire to a local model.
If you try it, start with the compose file in this article, add your languages to OCR, close registration and store the KEK before uploading the first document. And if you want more tools you can host yourself, see OpenSEO, the open source alternative to Semrush and Ahrefs or Itsaplan as a Linear and Jira alternative.
// source code
Help us grow
codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.
- Share it with someone who'll find it usefulWhatsAppLinkedInXFacebook
- Meet our sponsorSafe Build Labs
More on Self-hosting

guide · Paymenter guide: what it is, installation and setup · #3
- Run it on your server
- Step-by-step tutorials

guide · Paymenter guide: what it is, installation and setup · #2
- Run it on your server
- Step-by-step tutorials

guide · Paymenter guide: what it is, installation and setup · #1
- Free alternatives to paid apps
- Run it on your server