~/codigoagente
Self-hosting

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.

An organization dashboard: latest documents, tags and shortcuts to rules and share links · Official project screenshot (AGPL-3.0)

What Papra is and who maintains it

  • Repository: github.com/papra-hq/papra
  • Version reviewed: @papra/app 26.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

AreaWhat it includes
Document intakeWeb 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)
OrganizationOrganizations with members and invitations, tags with descriptions, per-organization custom properties, document date
Text and searchText extraction and OCR, full-text search with filters (`tag:`, `content:`, `created:`...)
AutomationCondition-based tagging rules, AI auto tagging, signed webhooks
SharingExternal links with optional expiry and password
SecurityOptional 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

A document's path from intake until it is searchable · codigoagente

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

PapraPaperless-ngx
LicenseAGPL-3.0GPL-3.0
Required servicesOne container (SQLite included)Django app + Redis, usually PostgreSQL
Original fileKept untouched, no OCR layerKeeps the original and also generates an archived PDF with text
StorageDisk, S3 or Azure BlobDisk
AI taggingBuilt in and optional (OpenAI, Anthropic, Ollama...)Its own classifier trained on your documents
MaturityYoung project, fast release cycleYears 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:

terminalsh
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:latest

Open 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:

terminalsh
mkdir -p papra/app-data/{db,documents} papra/ingestion && cd papra

Create a .env next to the compose file with your secrets and your user. PUID and PGID come from id -u and id -g:

.envsh
AUTH_SECRET=paste-openssl-rand-hex-48-here
PAPRA_KEK=paste-openssl-rand-hex-32-here
PUID=1000
PGID=1000

And the docker-compose.yml:

docker-compose.ymlyaml
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}"
terminalsh
docker compose up -d
docker compose logs -f

Three details in this setup:

  • DOCUMENTS_OCR_LANGUAGES defaults to eng. 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_URL must be the exact public URL you use (with https://). 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=false and run docker compose up -d again. 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:

StrategyWhat it usesNeeds
`internal`The project's `lecture` library + TesseractNothing (default)
`mistral-ocr`Mistral's OCR API`MISTRAL_API_KEY`
`docling`Your own Docling server`DOCLING_BASE_URL`
`azure-di`Azure Document IntelligenceEndpoint and key
`custom-http`Your own HTTP serviceURL

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:

.envsh
AI_IS_ENABLED=true
AI_DEFAULT_MODEL=ollama://qwen3:8b
OLLAMA_BASE_URL=http://ollama:11434/v1

Each 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).

Per-organization auto tagging settings · Official project screenshot (AGPL-3.0)

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:

terminalsh
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:

snippettext
tag:invoices supplier
content:"lease agreement"
created:>2026 -has:tags
name:warranty OR name:garantia

name: 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:

terminalsh
npm i -g @papra/cli
papra config init
papra config set default-org-id org_yourid
papra documents import october-invoice.pdf

Webhooks 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

Repository in this article
The code this article covers is public: browse it, star it or clone it from here.

Help us grow

codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.

// newsletter

One email a week with the repos worth your time

The week's new articles, tested against real code. No spam; unsubscribe in one click.

Self-hosting

guide · Paymenter guide: what it is, installation and setup · #3

Configure Paymenter after installing it: settings, catalog, payment gateways, tickets, roles and the MIT licence, with the real questions a small agency asks.
  • Run it on your server
  • Step-by-step tutorials
read article
Self-hosting

guide · Paymenter guide: what it is, installation and setup · #2

Run Paymenter in production on a Contabo VPS with Coolify and Docker: domain, HTTPS, MariaDB, Redis, cron, backups and real errors fixed step by step.
  • Run it on your server
  • Step-by-step tutorials
read article
Self-hosting

guide · Paymenter guide: what it is, installation and setup · #1

What Paymenter is, how it works under the hood and when to use it: MIT-licensed, self-hosted billing for hosting and subscriptions, a WHMCS alternative.
  • Free alternatives to paid apps
  • Run it on your server
read article