Papra: el gestor documental open source para archivar facturas y contratos en tu propio servidor
Papra es un gestor documental open source pensado para una tarea concreta: guardar facturas, contratos, garantías y recibos durante años y encontrarlos en segundos cuando hacen falta. Lo instalas en tu propio servidor con un solo contenedor Docker, subes los archivos (o los reenvías por correo, o los dejas caer en una carpeta) y Papra extrae el texto con OCR, los indexa para búsqueda y los etiqueta solo, con reglas o con un modelo de IA si lo activas.
Para una pyme o una agencia es la versión ligera de un archivo digital: sin licencias por usuario y sin entregar tus documentos a un SaaS. En este artículo leemos su código (aplicación 26.7.1, rama main del 31 de octubre de 2026) para contarte qué hace de verdad, cómo está construido, cómo desplegarlo bien a la primera y qué fallos vas a encontrarte.
Qué es Papra y quién lo mantiene
- Repositorio: github.com/papra-hq/papra
- Versión analizada:
@papra/app26.7.1. Usa versiones por año (AA.MENOR.PARCHE): 26.x son las publicadas en 2026, y solo se parchea la última, así que hay que actualizar para recibir correcciones de seguridad. - Licencia: AGPL-3.0 (la vemos abajo).
- Autor: Corentin Thomasset, con contribuciones externas. Se financia con patrocinios.
- Stack: SolidJS + UnoCSS en el cliente, Hono + Drizzle + Better Auth en el servidor, SQLite (libSQL) como base de datos y un monorepo con pnpm.
- Idiomas de la interfaz: 17, español incluido.
- Inspiración declarada: Paperless-ngx, el gestor documental self-hosted más conocido.
Una nota sobre la licencia
En codigoagente solemos tratar proyectos MIT; Papra no lo es. La AGPL-3.0 te deja usarlo gratis, también dentro de tu empresa y para gestionar documentos de clientes. La obligación aparece si modificas el código y ofreces esa versión a otros por red (por ejemplo, como SaaS para terceros): entonces tienes que publicar tus cambios con la misma licencia. Si lo despliegas tal cual para tu equipo, no tienes que hacer nada.
Qué hace Papra: funciones de la versión 26.7.1
| Área | Qué incluye |
|---|---|
| Entrada de documentos | Subida web, correo de ingesta (dirección generada por organización), carpeta vigilada, API REST, SDK (`@papra/api-sdk` 1.4.0) y CLI (`@papra/cli` 0.2.6) |
| Organización | Organizaciones con miembros e invitaciones, etiquetas con descripción, propiedades personalizadas por organización, fecha del documento |
| Texto y búsqueda | Extracción de texto y OCR, búsqueda de texto completo con filtros (`tag:`, `content:`, `created:`...) |
| Automatización | Reglas de etiquetado por condiciones, etiquetado automático con IA, webhooks firmados |
| Compartir | Enlaces externos con caducidad y contraseña opcionales |
| Seguridad | Cifrado de archivos AES-256-GCM opcional, cifrado de la base de datos opcional, OAuth (GitHub, Google o proveedores propios), 2FA |
| Administración | Panel `/admin` (solo lectura por ahora) y primer usuario como administrador |
El monorepo también incluye una app móvil en React Native con Expo (apps/mobile, versión 1.1.0), aunque el README todavía la cita como "quizá algún día". No comprobamos su disponibilidad en las tiendas.
Cómo funciona por dentro
Tres decisiones de diseño lo distinguen de alternativas más pesadas.
1. Nunca modifica el archivo original. El principio "no mutation" está documentado y se cumple en el código: Papra no convierte formatos, no inyecta metadatos ni superpone una capa de OCR sobre los PDF escaneados. Lo que subes es exactamente lo que descargas. El texto extraído vive en la base de datos, no dentro del archivo. Para un archivo legal o contable es justo lo que quieres.
2. Deduplicación por contenido. Al subir un archivo calcula su hash SHA-256 mientras lo recibe en streaming. La base de datos tiene un índice único (organization_id, original_sha256_hash), así que el mismo PDF no se guarda dos veces en una organización, aunque cambie de nombre. Si el duplicado estaba en la papelera, lo restaura en lugar de crear otro.
3. Un solo proceso y SQLite. No necesita PostgreSQL ni Redis. Por defecto la base de datos es un archivo SQLite (libSQL), la búsqueda usa el índice FTS5 de SQLite y la cola de tareas en segundo plano (CadenceMQ, del mismo equipo) persiste en memoria o en libSQL. Si un día crece, puede separar la API y los workers con PROCESS_MODE=web y PROCESS_MODE=worker, y conectarse a Turso u otro libSQL remoto con DATABASE_URL y DATABASE_AUTH_TOKEN.
Papra frente a Paperless-ngx
| Papra | Paperless-ngx | |
|---|---|---|
| Licencia | AGPL-3.0 | GPL-3.0 |
| Servicios necesarios | Un contenedor (SQLite incluido) | Aplicación Django + Redis, y normalmente PostgreSQL |
| Archivo original | Se guarda intacto, sin capa de OCR | Guarda el original y genera además una versión archivada en PDF con texto |
| Almacenamiento | Disco, S3 o Azure Blob | Disco |
| Etiquetado con IA | Integrado y opcional (OpenAI, Anthropic, Ollama...) | Clasificador propio entrenado con tus documentos |
| Madurez | Proyecto joven, ciclo de versiones rápido | Años en producción y un ecosistema amplio |
Si ya tienes Paperless-ngx funcionando y te sirve, no hay una razón fuerte para migrar. Papra encaja mejor cuando quieres algo que se despliega en cinco minutos, ocupa poco y guarda los originales en S3.
Instalar Papra con Docker
La prueba rápida es un comando, pero el AUTH_SECRET tiene que tener al menos 32 caracteres; genera el tuyo con openssl rand -hex 48:
docker run -d \
--name papra \
--restart unless-stopped \
--env APP_BASE_URL=http://localhost:1221 \
--env AUTH_SECRET=<tu-auth-secret> \
-p 1221:1221 \
ghcr.io/papra-hq/papra:latestAbre http://localhost:1221 y crea tu cuenta: con AUTH_FIRST_USER_AS_ADMIN=true (valor por defecto) el primer usuario registrado se convierte en administrador. Sin volúmenes, los datos desaparecen al borrar el contenedor, así que esto sirve solo para probar.
La imagen latest es la variante *rootless* (recomendada). Hay también latest-root y etiquetas por versión, y una réplica en Docker Hub (corentinth/papra) si GHCR te da problemas. Nosotros descargamos la imagen desde Docker Hub sin incidencias.
Docker Compose para producción
Esta es la configuración que recomendamos para un VPS: datos persistentes, OCR en español, cifrado de archivos, carpeta de ingesta y registro cerrado tras crear tu cuenta. Crea la estructura:
mkdir -p papra/app-data/{db,documents} papra/ingestion && cd papraCrea un .env junto al compose con tus secretos y tu usuario. Los valores de PUID y PGID salen de id -u e id -g:
AUTH_SECRET=pega-aqui-openssl-rand-hex-48
PAPRA_KEK=pega-aqui-openssl-rand-hex-32
PUID=1000
PGID=1000Y el 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.tudominio.com
- AUTH_SECRET=${AUTH_SECRET}
- DOCUMENTS_OCR_LANGUAGES=spa,eng
- 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 -fTres detalles de esta configuración:
DOCUMENTS_OCR_LANGUAGESvaleengpor defecto. Si tus documentos están en español, añadespao el OCR de los escaneos saldrá lleno de errores. Admite cualquier idioma de Tesseract separado por comas.APP_BASE_URLtiene que ser la URL pública exacta con la que entras (conhttps://). Papra valida el origen de cada petición contra CSRF y te rechazará el login si no coincide.- Cierra el registro cuando tengas tu cuenta: añade
AUTH_IS_REGISTRATION_ENABLED=falsey vuelve a lanzardocker compose up -d. Por defecto el registro está abierto y cualquiera con la URL puede crear una cuenta en tu instancia.
Para ponerlo detrás de un dominio con HTTPS, cualquier proxy inverso sirve. Si ya usas Coolify, el procedimiento es el mismo que seguimos en la instalación de Paymenter en un VPS con Coolify: recurso de tipo Docker Compose, dominio en el servicio y Coolify se encarga del certificado.
Configurarlo: cifrado, OCR, IA e ingesta
Cifrado de documentos
Con el cifrado activado, cada documento recibe su propia clave aleatoria de 256 bits (DEK) y se cifra con AES-256-GCM. Esa clave se guarda en la base de datos envuelta con tu clave maestra (KEK, la variable DOCUMENT_STORAGE_DOCUMENT_KEY_ENCRYPTION_KEYS). Quien robe solo el almacenamiento (el bucket S3, por ejemplo) no puede leer nada sin la base de datos y la variable de entorno.
Dos avisos: activar el cifrado no cifra los documentos que ya tenías (para eso está la guía de migración de almacenamiento del proyecto) y, si pierdes la KEK, los archivos son irrecuperables. Guárdala en tu gestor de contraseñas el mismo día. La variable admite varias claves con versión para rotarlas.
Extracción de texto y OCR
CONTENT_EXTRACTION_STRATEGY acepta una lista de estrategias en orden de preferencia; si la primera falla o no admite el tipo de archivo, prueba la siguiente:
| Estrategia | Qué usa | Necesita |
|---|---|---|
| `internal` | Librería `lecture` del proyecto + Tesseract | Nada (por defecto) |
| `mistral-ocr` | API de OCR de Mistral | `MISTRAL_API_KEY` |
| `docling` | Servidor Docling propio | `DOCLING_BASE_URL` |
| `azure-di` | Azure Document Intelligence | Endpoint y clave |
| `custom-http` | Tu propio servicio HTTP | URL |
Deja internal siempre al final, como red de seguridad: CONTENT_EXTRACTION_STRATEGY=mistral-ocr,internal. Ten en cuenta que con las estrategias externas el contenido del documento sale de tu servidor hacia ese proveedor.
Etiquetado automático con IA
Viene apagado. Necesitas AI_IS_ENABLED=true y un modelo con la nomenclatura <adaptador>://<modelo>. Hay adaptadores para OpenAI, Anthropic, Mistral, DeepSeek, OpenRouter, Ollama, LM Studio, vLLM y cualquier API compatible con OpenAI. Para que los documentos no salgan de tu red, la opción natural es un modelo local:
AI_IS_ENABLED=true
AI_DEFAULT_MODEL=ollama://qwen3:8b
OLLAMA_BASE_URL=http://ollama:11434/v1Después, cada organización lo activa en sus ajustes y decide si la IA puede crear etiquetas nuevas y cuántas aplica como máximo por documento (5 por defecto).
El modelo decide a partir del nombre y la descripción de cada etiqueta, así que escribir descripciones claras ("Facturas de proveedores con IVA, no recibos de tarjeta") mejora mucho el resultado. Si prefieres algo determinista y sin coste, las reglas de etiquetado aplican etiquetas por condiciones sobre el nombre o el contenido, y tienen un botón para aplicarlas a los documentos que ya existen.
Carpeta de ingesta y correo
Con INGESTION_FOLDER_IS_ENABLED=true, Papra vigila /app/ingestion. Cada organización tiene su subcarpeta con su ID (el org_... que ves en la URL); los archivos sueltos en la raíz se ignoran:
mkdir -p ingestion/org_tuidentificador
cp ~/escaner/*.pdf ingestion/org_tuidentificador/Por defecto borra el archivo tras importarlo; con INGESTION_FOLDER_POST_PROCESSING_STRATEGY=move lo mueve a ingestion-done/. Si la importación falla, lo deja en ingestion-error/ para no perder nada. Es la forma más cómoda de conectar un escáner de red o una carpeta sincronizada.
La ingesta por correo genera una dirección por organización y necesita un servicio que reciba los correos y los entregue por webhook: OwlRelay o un Email Worker de Cloudflare, ambos documentados en el proyecto.
Buscar documentos
La búsqueda combina texto libre con filtros, operadores lógicos y paréntesis:
tag:facturas proveedor
content:"contrato de arrendamiento"
created:>2026 -has:tags
name:garantia OR name:warrantyname: y content: buscan por "contiene", no por coincidencia exacta. -has:tags es útil para revisar cada semana los documentos que se quedaron sin etiquetar.
API, CLI y webhooks
Desde los ajustes de usuario creas una clave de API, y con ella puedes usar el CLI:
npm i -g @papra/cli
papra config init
papra config set default-org-id org_tuidentificador
papra documents import factura-octubre.pdfLos webhooks avisan a otro sistema con los eventos document:created, document:updated, document:deleted, document:tag:added y document:tag:removed, con firma para verificar el origen. Así puedes, por ejemplo, avisar a tu sistema contable cuando llega un documento con la etiqueta "facturas". El servidor trae protección contra SSRF en las URL de webhook activada por defecto: si tu destino está en la red interna, añádelo a WEBHOOK_URL_ALLOWED_HOSTNAMES en lugar de desactivar la protección.
Errores frecuentes
bash: UID: readonly variable y The "UID" variable is not set. Defaulting to a blank string. La documentación propone lanzar el compose con UID=$(id -u) GID=$(id -g) docker compose up -d. En bash UID es de solo lectura y no se exporta: lo probamos en bash 5.2 con Docker Compose 5.6 y el resultado es user: :0 (sin usuario, grupo root). Por eso nuestro compose usa PUID y PGID en el .env, o puedes escribir el número directamente (user: "1000:1000").
Error: EACCES: permission denied, mkdir './app-data/db'. La imagen rootless corre con tu usuario y no puede crear las carpetas si el directorio montado pertenece a otro. Crea app-data/db y app-data/documents antes de arrancar y comprueba que el propietario coincide con PUID:PGID.
Please provide an auth secret using the AUTH_SECRET environment variable o In production, the auth secret must not be the default one. Falta el secreto, tiene menos de 32 caracteres o has dejado el valor por defecto. Genera uno con openssl rand -hex 48.
Error de origen inválido al iniciar sesión. APP_BASE_URL no coincide con la URL del navegador (http frente a https, otro subdominio o un puerto distinto). Corrígela o añade el origen extra en TRUSTED_ORIGINS, separado por comas.
Document already exists. No es un fallo: ese contenido exacto ya está en la organización con otro nombre. Búscalo con name: o revisa la papelera.
Document size too large. El límite por defecto es 25 MB. Súbelo con DOCUMENT_STORAGE_MAX_UPLOAD_SIZE (en bytes) y revisa también el límite de tu proxy inverso.
El OCR devuelve texto sin sentido en documentos en español. Falta spa en DOCUMENTS_OCR_LANGUAGES. Tras cambiarlo, puedes volver a procesar los documentos existentes: la versión 26.7.0 añadió el reprocesado (DOCUMENT_REPROCESSING_ENABLED, activo por defecto).
Preguntas frecuentes
¿Papra es gratis? Sí. El código es AGPL-3.0 y la versión self-hosted no tiene límites de pago. El proyecto tiene planes de pago para su instancia gestionada, pero en tu servidor no aplican.
¿Papra es una alternativa a Paperless-ngx? Cubre el mismo caso (archivar y buscar documentos con OCR) con un enfoque más ligero: un contenedor, SQLite y originales intactos. Paperless-ngx es más maduro y tiene más ecosistema.
¿Mis documentos salen de mi servidor? No, salvo que actives estrategias de extracción externas (Mistral, Azure, Docling remoto) o un modelo de IA en la nube. Con internal y Ollama todo se queda en tu máquina.
¿Puedo guardar los archivos en S3 o en un bucket compatible? Sí. DOCUMENT_STORAGE_DRIVER admite filesystem, s3 y azure-blob. Para MinIO, Cloudflare R2 o similares usa el driver s3 con DOCUMENT_STORAGE_S3_ENDPOINT y, si hace falta, DOCUMENT_STORAGE_S3_FORCE_PATH_STYLE=true.
¿Cómo hago copias de seguridad? Copia app-data/ completo (base de datos SQLite y documentos) y guarda aparte el .env con AUTH_SECRET y la KEK. Sin la KEK, una copia de documentos cifrados no sirve de nada.
¿Sirve para un despacho o una empresa con varios usuarios? Sí, mediante organizaciones con miembros e invitaciones. Dentro de una organización hay tres roles (propietario, administrador y miembro); si necesitas permisos finos por carpeta o por documento, todavía no los tiene.
Conclusión
Papra hace pocas cosas y las hace bien: guarda el original tal cual, evita duplicados, extrae el texto y te deja encontrarlo todo con una búsqueda. Que funcione en un solo contenedor con SQLite lo hace muy fácil de desplegar y mantener en un VPS pequeño, y la IA es un extra que puedes ignorar o conectar a un modelo local.
Si lo vas a probar, empieza con el compose de este artículo, activa spa en el OCR, cierra el registro y guarda la KEK antes de subir el primer documento. Y si te interesan más herramientas que puedes alojar tú mismo, mira OpenSEO, la alternativa open source a Semrush y Ahrefs o Itsaplan como alternativa a Linear y Jira.
// código fuente
Nos ayuda a crecer
codigoagente es gratis y sin muros de pago. Si este artículo te sirvió, cualquiera de estas cosas mantiene el blog en marcha.
- Compártelo con alguien a quien le sirvaWhatsAppLinkedInXFacebook
- Conoce a nuestro patrocinadorSafe Build Labs
Más sobre Self-hosting

guía · Guía de Paymenter: qué es, instalación y configuración · #3
- Instálalo en tu servidor
- Tutoriales paso a paso

guía · Guía de Paymenter: qué es, instalación y configuración · #2
- Instálalo en tu servidor
- Tutoriales paso a paso

guía · Guía de Paymenter: qué es, instalación y configuración · #1
- Alternativas gratis a apps de pago
- Instálalo en tu servidor