Publicado por
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:
¿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 consultable. 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, permite búsquedas avanzadas y ofrece una interfaz web desarrollada en Angular. Incluye capacidades de inteligencia artificial para clasificación automática, extracción de entidades y consultas en lenguaje natural mediante integración con Ollama, OpenAI y otros proveedores LLM.
Características principales
OCR multiidioma
Incluye Tesseract con soporte para inglés, alemán, francés, italiano y español; permite añadir paquetes de idiomas adicionales mediante variables de entorno.
Búsqueda full-text y metadatos
Motor de búsqueda Tantivy con índices invertidos, filtrado por etiquetas, correspondientes, tipos de documento y fechas; búsqueda difusa y por similitud.
Clasificación automática con IA
Integración con LlamaIndex para embeddings (HuggingFace, Ollama, OpenAI-compatible) y LLMs (Ollama, OpenAI-compatible) que permiten autoetiquetado, extracción de correspondientes y respuestas en lenguaje natural sobre el corpus.
Consumo automático de documentos
Directorio de consumo monitorizado (watchfiles) que procesa PDFs, imágenes, Office, correos y más; soporta reglas de preprocesamiento (unpaper, OCRmyPDF) y plantillas de nombre de archivo.
Interfaz web responsiva
Frontend Angular con vistas de tarjetas, lista y miniatura; modo oscuro/claro, atajos de teclado, arrastrar-y-soltar, vista previa de PDF y edición masiva de metadatos.
Arquitectura contenedorizada
Imagen Docker multi-arquitectura (amd64/arm64) con s6-overlay, usuario no root, healthcheck HTTP y volúmenes persistentes para data, media, consume y export.
Soporte multi-base de datos
Compatible con PostgreSQL (psycopg3) y MariaDB/MySQL (mysqlclient); SQLite para desarrollo. Migraciones gestionadas por Django.
Gestión de usuarios y permisos
Autenticación con django-allauth (MFA, proveedores sociales), guardian para permisos por objeto, auditoría con django-auditlog y borrado lógico.
Requisitos del sistema
- Docker Engine 20.10+ y Docker Compose v2
- CPU x86_64 o ARM64
- Mínimo 2 GB RAM (4 GB recomendados para IA local)
- Espacio en disco: 5 GB base + espacio para documentos y índices
- Puertos 8000 (web), 6379 (Redis), 5432 (PostgreSQL) o 3306 (MariaDB) según configuración
- Python 3.11+ solo si se compila desde fuente (imagen Docker incluye runtime)
Instalación con Docker Compose
Instalación rápida con script oficial
El proyecto proporciona un script que genera docker-compose.yml, .env y directorios de datos con valores seguros por defecto.
Despliegue manual con Docker Compose
Clona el repositorio y usa los archivos de compose en docker/compose; el script anterior automatiza este paso.
cd paperless-ngx/docker/compose
cp docker-compose.env.example .env
# Edita .env con tus valores
sudo docker compose up -d
Variables de entorno esenciales
Configura al menos PAPERLESS_SECRET_KEY, PAPERLESS_ADMIN_USER, PAPERLESS_ADMIN_PASSWORD y credenciales de base de datos en .env antes de iniciar.
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=changeme
POSTGRES_USER=paperless
POSTGRES_PASSWORD=changeme
POSTGRES_DB=paperless
REDIS_PASSWORD=changeme
Acceder al proyecto
Acceso local
Tras iniciar los contenedores, la interfaz web está disponible en http://localhost:8000 (o el puerto configurado en PAPERLESS_PORT). Inicia sesión con el usuario y contraseña definidos en PAPERLESS_ADMIN_USER y PAPERLESS_ADMIN_PASSWORD.
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 documentados en /api/ (drf-spectacular/Swagger). Requiere autenticación por token o sesión; permite ingestar, consultar y gestionar documentos programáticamente.
Casos de uso
- Archivo personal o familiar de facturas, contratos, certificados y correspondencia
- Gestión documental en pequeñas empresas o despachos profesionales
- Digitalización de expedientes con búsqueda por contenido y metadatos
- Clasificación automática de documentos entrantes mediante IA local (Ollama) o cloud
- Cumplimiento de requisitos de conservación documental con exportación masiva
- Integración con escáneres de red y bandejas de entrada por correo (IMAP/SMTP)
Configuración avanzada
Configuración de OCR e idiomas adicionales
Define PAPERLESS_OCR_LANGUAGES con códigos ISO 639-3 separados por comas (ej. spa,eng,fra). Instala paquetes tesseract-ocr-<lang> en la imagen o usa una imagen personalizada.
PAPERLESS_OCR_MODE=skip_text
PAPERLESS_OCR_SUPER_RESOLUTION=true
Habilitar IA local con Ollama
Añade servicio Ollama en docker-compose y configura embeddings y LLM en paperless. Requiere GPU o CPU con AVX2 para rendimiento aceptable.
ollama:
image: ollama/ollama:latest
volumes:
– ollama:/root/.ollama
deploy:
resources:
reservations:
devices:
– driver: nvidia
count: 1
capabilities: [gpu]
# Variables en .env:
PAPERLESS_AI_EMBEDDING_MODEL=ollama/nomic-embed-text
PAPERLESS_AI_LLM_MODEL=ollama/llama3.1
PAPERLESS_AI_OLLAMA_BASE_URL=http://ollama:11434
Consumo por correo electrónico
Configura PAPERLESS_MAIL_* para conectar a una cuenta IMAP y procesar adjuntos automáticamente. Soporta reglas de filtrado por carpeta, asunto y remitente.
PAPERLESS_MAIL_HOST=imap.example.com
PAPERLESS_MAIL_PORT=993
[email protected]
PAPERLESS_MAIL_PASSWORD=secret
PAPERLESS_MAIL_FOLDER=INBOX
PAPERLESS_MAIL_DELETE=false
PAPERLESS_MAIL_RULES=[{"folder": "INBOX", "tag": "correo"}]
Personalización de políticas de retención y exportación
Define reglas de retención por etiqueta o correspondiente; exporta documentos con metadatos en JSON/CSV o PDF/A mediante comandos de gestión.
sudo docker compose exec webserver python3 manage.py document_exporter /usr/src/paperless/export –format json –include-metadata
Gestión y mantenimiento
Actualización de versión
Actualiza la imagen y ejecuta migraciones. El script de instalación detecta versiones nuevas y ofrece actualizar.
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
# O manualmente:
sudo docker compose pull
sudo docker compose up -d
sudo docker compose exec webserver python3 manage.py migrate
Copia de seguridad
Respalda volúmenes data (base de datos SQLite/PostgreSQL dump), media (archivos originales), consume y export. Para PostgreSQL usa pg_dump; para SQLite copia el archivo db.sqlite3.
sudo docker compose exec db pg_dump -U paperless paperless > backup_$(date +%F).sql
# Backup volúmenes
sudo tar czf paperless_backup_$(date +%F).tar.gz /path/to/data /path/to/media
Reindexado y mantenimiento de búsqueda
Reconstruye índices Tantivy y Whoosh tras migraciones o cambios masivos. Limpia archivos huérfanos y optimiza base de datos.
sudo docker compose exec webserver python3 manage.py cleanup_orphan_files
sudo docker compose exec webserver python3 manage.py clearsessions
Monitoreo y logs
Healthcheck HTTP en puerto 8000 cada 30s. Logs estructurados en stdout/stderr (concurrent-log-handler). Flower disponible en puerto 5555 para monitoreo de Celery si se habilita.
sudo docker compose logs -f webserver
# Healthcheck manual
curl -fs http://localhost:8000
Stack técnico
- Python 3.11-3.15
- Django 5.2
- Django REST Framework 3.16
- Angular 18+ (frontend)
- PostgreSQL 16 / MariaDB 11 / SQLite
- Redis 7 (caché, colas, canales)
- Celery 5.6 (tareas asíncronas)
- Tesseract OCR 5.x
- OCRmyPDF 17.x
- Tantivy 0.26 (motor búsqueda)
- LlamaIndex (IA/embeddings/LLM)
- Sentence Transformers / PyTorch (embeddings locales)
- s6-overlay 3.2 (init en contenedor)
- uv (gestor paquetes Python)
- Docker multi-arch (amd64/arm64)
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
- Comunidad Matrix: https://matrix.to/#/#paperlessngx: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]