Gestión Documental

Paperless-ngx: Sistema de gestión documental con OCR e IA

Transforma tus documentos físicos en un archivo digital consultable con búsqueda full-text, clasificación automática y soporte para modelos de lenguaje

Vídeo tutorial en YouTube

Mira el vídeo completo sobre cómo instalar y usar Paperless-ngx: Sistema de gestión documental con OCR e IA en el canal GENBYTE:

Clickea la miniatura para ir a YouTube

¿Qué es Paperless-ngx: Sistema de gestión documental con OCR e IA?

Paperless-ngx es un sistema de gestión documental (DMS) comunitario que permite escanear, indexar y archivar documentos físicos convirtiéndolos en un repositorio digital con capacidad de búsqueda. Es el sucesor oficial de Paperless y Paperless-ng, diseñado para distribuir el mantenimiento entre un equipo de colaboradores. La aplicación procesa documentos mediante OCR (Tesseract), extrae metadatos, aplica clasificación automática mediante reglas y aprendizaje automático, y expone una interfaz web desarrollada en Angular junto a una API REST basada en Django REST Framework. El proyecto está licenciado bajo GPL-3.0 y cuenta con más de 46.000 estrellas en GitHub.

Incluye OCR multiidioma, clasificación automática con reglas y ML, API REST completa, interfaz web responsiva y despliegue nativo con Docker Compose.

Características principales

OCR multiidioma

Soporte para Tesseract con paquetes de idioma inglés, alemán, francés, italiano y español; integra OCRmyPDF para generación de PDF/A con capa de texto buscable.

Clasificación automática

Motor de reglas basado en expresiones regulares y coincidencia difusa (rapidfuzz) junto a clasificación mediante embeddings (sentence-transformers) y modelos LLM locales (Ollama) o remotos (OpenAI-compatible).

Interfaz web y API

Frontend Angular con vistas de tarjetas, lista y tabla; API REST documentada con OpenAPI (drf-spectacular) y autenticación mediante django-allauth (MFA, OAuth2, LDAP).

Gestión de correspondencia

Módulo paperless-mail para importar correos desde IMAP, aplicar reglas y adjuntar documentos al archivo.

Búsqueda avanzada

Backend Tantivy con índices invertidos, búsqueda por similitud, filtros por etiquetas, correspondientes, tipos, fechas y campos personalizados.

Despliegue contenerizado

Imagen Docker multi-arquitectura (amd64/arm64) con s6-overlay, healthcheck HTTP, volúmenes persistentes para datos, media, consume y export.

Soporte multi-base de datos

Compatible con PostgreSQL (psycopg) y MariaDB/MySQL (mysqlclient); SQLite para desarrollo y pruebas.

Procesamiento asíncrono

Cola de tareas Celery con Redis (channels-redis para WebSockets), Flower para monitorización y workers escalables.

Internacionalización

Traducciones gestionadas en Crowdin; interfaz disponible en múltiples idiomas.

Seguridad y auditoría

django-guardian para permisos por objeto, django-auditlog para trazabilidad, cifrado GPG opcional para archivos exportados.

Requisitos del sistema

Docker Engine y Docker Compose v2
Host con arquitectura amd64 o arm64
Mínimo 2 GB RAM recomendados (4 GB para modelos de embeddings/LLM)
Espacio en disco según volumen de documentos (mínimo 5 GB para aplicación + datos)
Puertos 8000 (HTTP) y opcionalmente 443 (TLS reverse proxy)
Base de datos PostgreSQL 14+ o MariaDB 10.6+ (contenedores incluidos en compose)
Redis 7+ (contenedor incluido en compose)
Zona horaria configurada en el host (tzdata)

Instalación con Docker Compose

Instalación rápida con script oficial

El proyecto proporciona un script que genera la estructura docker-compose.yml, .env y directorios de volúmenes. Ejecuta como usuario con permisos docker:

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Despliegue manual con docker compose

Clona el repositorio y usa los archivos de compose en docker/compose. El compose principal levanta paperless, postgres, redis y opcionalmente gotenberg, tika y nginx.

git clone https://github.com/paperless-ngx/paperless-ngx.git
cd paperless-ngx/docker/compose
cp docker-compose.env.example .env
# Edita .env con tus valores (PAPERLESS_SECRET_KEY, credenciales DB, etc.)
docker compose up -d

Variables de entorno críticas

Define al menos PAPERLESS_SECRET_KEY (clave secreta Django), PAPERLESS_ADMIN_USER/PAPERLESS_ADMIN_PASSWORD (usuario inicial), credenciales de base de datos y REDIS. Consulta paperless.conf.example para el catálogo completo.

# Ejemplo mínimo en .env
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=CambiaEstaClave
POSTGRES_USER=paperless
POSTGRES_PASSWORD=CambiaEstaClave
POSTGRES_DB=paperless
REDIS_PASSWORD=CambiaEstaClave

Acceder al proyecto

Interfaz web local

Tras el despliegue, la aplicación escucha en el puerto 8000 del contenedor. Accede vía http://<IP_HOST>:8000 (o el puerto publicado en docker-compose). Inicia sesión con el usuario administrador definido en PAPERLESS_ADMIN_USER.

Demo oficial

Disponible en https://demo.paperless-ngx.com con credenciales demo / demo. El contenido se reinicia periódicamente; no subas información confidencial.

API REST

Endpoints bajo /api/ con documentación Swagger en /api/docs/ y ReDoc en /api/redoc/. Autenticación por token (DRF) o sesión.

Consumo de documentos

Copia archivos al directorio mapeado en /usr/src/paperless/consume (volumen consume) para que el consumidor los procese automáticamente.

Casos de uso

Digitalización y archivo de facturas, contratos, recibos y correspondencia personal o empresarial
Búsqueda full-text instantánea sobre miles de documentos escaneados
Clasificación automática por tipo (factura, contrato, recibo), correspondiente, etiquetas y fechas
Extracción de metadatos (fecha, importe, IBAN, número de factura) mediante reglas y ML
Gestión de correo entrante: archivado automático de adjuntos desde cuentas IMAP
Cumplimiento normativo: generación de PDF/A-2b con firma digital y registro de auditoría
Integración con flujos de trabajo externos vía API REST y webhooks
Ejecución en entorno air-gapped o red local sin conexión a internet (modelos locales Ollama, embeddings locales)

Configuración avanzada

Configuración mediante paperless.conf

El contenedor carga variables desde /etc/paperless/paperless.conf (monta tu archivo en ese path). Permite ajustar OCR (idiomas, deskew, limpieza), consumidor (patrones, recursivo, watchdog), índice (Tantivy, Whoosh), clasificación (umbrales, modelos), almacenamiento (rutas, permisos) y rendimiento (workers, batch size).

# Ejemplo fragmento paperless.conf
PAPERLESS_OCR_LANGUAGES=spa+eng
PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_POLLING=30
PAPERLESS_TESSERACT_TIMEOUT=300
PAPERLESS_CLASSIFIER_THRESHOLD=0.35
PAPERLESS_EMBEDDINGS_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

Modelos de embeddings y LLM locales

Configura PAPERLESS_EMBEDDINGS_MODEL para usar sentence-transformers local. Para LLM, define PAPERLESS_LLM_PROVIDER=ollama y PAPERLESS_OLLAMA_BASE_URL=http://ollama:11434 con modelo en PAPERLESS_OLLAMA_MODEL. Requiere contenedor Ollama adicional con GPU para rendimiento aceptable.

# docker-compose.override.yml para Ollama
services:
ollama:
image: ollama/ollama:latest
volumes:
– ollama_data:/root/.ollama
deploy:
resources:
reservations:
devices:
– driver: nvidia
count: 1
capabilities: [gpu]
volumes:
ollama_data:

Reverse proxy con TLS (nginx/Traefik/Caddy)

Expone el puerto 8000 detrás de un proxy que termine TLS, añada cabeceras de seguridad y limite tasa. El contenedor paperless define HEALTHCHECK en / para sondas de vida.

# Ejemplo snippet nginx
server {
listen 443 ssl http2;
server_name docs.tu-dominio.com;
location / {
proxy_pass http://paperless:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
client_max_body_size 100M;
}
}

Permisos y usuarios

Usa django-guardian para permisos por objeto. Crea grupos, asigna permisos de vista/edición/eliminación por etiqueta, correspondiente o tipo. Soporta autenticación LDAP/Active Directory vía django-allauth.

Exportación y respaldo

Comando manage.py document_exporter genera ZIP con PDF/A y metadatos JSON. Programa copias de seguridad de volúmenes data, media, postgres y redis. La variable PAPERLESS_GPG_PASSPHRASE habilita cifrado de exportaciones.

Gestión y mantenimiento

Actualización de versión

Actualiza la imagen y recrea contenedores. Las migraciones de base de datos se aplican automáticamente al arranque. Revisa CHANGELOG y notas de versión para cambios breaking.

docker compose pull
docker compose up -d –remove-orphans

Respaldos programados

Realiza dump de PostgreSQL (pg_dump), snapshot de volúmenes Docker y copia de configuración (.env, paperless.conf). Prueba restauración periódicamente.

# Backup BD
docker exec -t paperless-postgres pg_dump -U paperless paperless > backup_$(date +%F).sql
# Backup volúmenes
docker run –rm -v paperless_data:/data -v $(pwd):/backup alpine tar czf /backup/data_$(date +%F).tar.gz -C /data .

Limpieza de archivos huérfanos

Comando manage.py sanity_check detecta inconsistencias entre BD y sistema de archivos. manage.py remove_orphaned_files elimina archivos sin referencia en BD (usa –dry-run primero).

docker compose exec paperless python3 manage.py sanity_check
docker compose exec paperless python3 manage.py remove_orphaned_files –dry-run

Monitorización y logs

Logs vía stdout/stderr (docker logs paperless). Flower expone puerto 5555 para colas Celery. Healthcheck HTTP en / cada 30s. Métricas Prometheus opcionales con django-prometheus.

Reindexado de búsqueda

Tras cambios masivos o actualización de motor, reconstruye índice Tantivy:

docker compose exec paperless python3 manage.py rebuild_index

Stack técnico

Python 3.11-3.15
Django 5.2 LTS
Django REST Framework 3.16
Angular 18+ (frontend)
PostgreSQL 14+ / MariaDB 10.6+ / SQLite
Redis 7+ (caché, colas, WebSockets)
Celery 5.6 + Flower
Tesseract OCR 5.x + OCRmyPDF 17.x
Tantivy 0.26 (motor búsqueda)
sentence-transformers / llama-index (embeddings)
Ollama / OpenAI-compatible (LLM opcional)
s6-overlay 3.2 (init contenedor)
uv (gestor paquetes Python)
Gotenberg / Apache Tika (conversión documentos opcional)
nginx / Traefik / Caddy (reverse proxy recomendado)

Referencias oficiales

Repositorio oficial GitHub: https://github.com/paperless-ngx/paperless-ngx
Documentación oficial: https://docs.paperless-ngx.com/
Demo en línea: https://demo.paperless-ngx.com
Script de instalación: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh
Docker Hub / GHCR imágenes: https://github.com/paperless-ngx/paperless-ngx/pkgs/container/paperless-ngx
Traducciones (Crowdin): https://crowdin.com/project/paperless-ngx
Sala Matrix comunidad: https://matrix.to/#/#paperless:matrix.org
Licencia GPL-3.0: https://github.com/paperless-ngx/paperless-ngx/blob/main/LICENSE

Apoya el canal GENBYTE

¿Te ha sido útil este contenido?

Suscríbete a YouTube
Newsletter GENBYTE
Ko-fi
Contacto: [email protected]