Paperless-ngx: Gestión Digital de Documentos con OCR
Paperless-ngx es un sistema de gestión de documentos digitales que transforma tus documentos escaneados y PDFs en archivos con texto indexado y búsqueda completa mediante OCR (reconocimiento óptico de caracteres). Con etiquetado automático, correspondientes, flujos de trabajo de consumo y un motor de búsqueda potente, Paperless-ngx es la solución definitiva para quienes quieren dejar de acumular papel y centralizar su documentación en un servidor propio.
Requisitos Previos
- Servidor con Ubuntu 20.04+, Debian 11+ o CentOS 8+
- Docker y Docker Compose instalados
- Mínimo 2 GB de RAM (4 GB recomendados para OCR intensivo)
- 2+ núcleos de CPU
- Almacenamiento SSD para la base de datos y documentos
- Puerto 8000 disponible
Instalación con Docker Compose
# Crear directorio de instalación
mkdir -p ~/paperless && cd ~/paperless
# Descargar el docker-compose oficial
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres-tika.yml \
-O docker-compose.yml
# Descargar el archivo de variables de entorno
wget https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env.example \
-O .env
Editar el archivo .env:
nano ~/paperless/.env
# URL de la aplicación (importante para los enlaces en notificaciones)
PAPERLESS_URL=https://docs.tu-dominio.com
# Zona horaria
PAPERLESS_TIME_ZONE=Europe/Madrid
# Idioma principal para OCR (esp para español)
PAPERLESS_OCR_LANGUAGE=spa
# Idiomas adicionales para OCR (si tienes documentos en múltiples idiomas)
PAPERLESS_OCR_LANGUAGES=spa eng
# Contraseña secreta de Django (generar una aleatoria)
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
# Número de trabajadores paralelos para OCR
PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=2
# Configuración de la base de datos
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=contrasena-bd-segura
# Directorio de consumo de documentos (dentro del contenedor)
PAPERLESS_CONSUMPTION_DIR=/usr/src/paperless/consume
# Directorio de datos (archivos de documentos procesados)
PAPERLESS_DATA_DIR=/usr/src/paperless/data
# Directorio de medios (documentos originales y versiones procesadas)
PAPERLESS_MEDIA_ROOT=/usr/src/paperless/media
Ajustar el docker-compose.yml para montar directorios locales:
# Los servicios que incluye la configuración postgres-tika:
# - broker (Redis)
# - db (PostgreSQL)
# - webserver (Paperless-ngx)
# - gotenberg (conversión de Office a PDF)
# - tika (extracción de texto avanzada)
# Crear los directorios locales
mkdir -p ~/paperless/{consume,data,media,pgdata,export}
# Iniciar los servicios
docker compose up -d
# Ver el progreso de inicio
docker compose logs -f webserver
Crear el usuario administrador:
# Crear usuario administrador de Paperless
docker exec -it paperless-webserver-1 python3 manage.py createsuperuser
# Introducir username, email y contraseña cuando se pida
Configuración de OCR
Paperless-ngx usa Tesseract para OCR. Configurar el idioma y calidad:
# Variables de entorno para OCR en .env
# Idioma principal (lista: https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions.html)
PAPERLESS_OCR_LANGUAGE=spa
# Modo OCR:
# skip - no realizar OCR si ya tiene texto
# redo - realizar OCR siempre (más lento pero más completo)
# force - forzar OCR en todos los documentos
PAPERLESS_OCR_MODE=skip
# Rotación automática de páginas
PAPERLESS_OCR_AUTO_ROTATE_PAGES=true
# Umbral de rotación (0-100)
PAPERLESS_OCR_AUTO_ROTATE_PAGES_THRESHOLD=12
# Desactivar invalidación de archivos (para compatibilidad)
PAPERLESS_OCR_CLEAN=clean
# Calidad del PDF de salida
PAPERLESS_OCR_OUTPUT_TYPE=pdfa
# Resolución mínima de imagen para OCR (en DPI)
PAPERLESS_OCR_DESKEW=true
Reiniciar con la nueva configuración:
docker compose down && docker compose up -d
Flujos de Trabajo de Consumo
Paperless-ngx monitoriza el directorio de consumo y procesa automáticamente los archivos nuevos:
# Agregar documentos al directorio de consumo
cp factura-enero.pdf ~/paperless/consume/
# Paperless los procesa automáticamente:
# 1. OCR del documento
# 2. Extracción de fecha y correspondiente
# 3. Aplicación de etiquetas automáticas (según reglas)
# 4. Indexación para búsqueda
# Ver el progreso del consumo
docker logs paperless-webserver-1 2>&1 | grep -i "consumed\|error"
# Para escáner físico, configurar la carpeta de consumo como destino
# La mayoría de escáneres soportan SMB o FTP
Configurar Samba para escáner de red:
# Instalar Samba
sudo apt install -y samba
# Configurar compartido para el directorio de consumo
sudo tee -a /etc/samba/smb.conf << 'EOF'
[paperless-consume]
path = /home/usuario/paperless/consume
writable = yes
create mask = 0664
directory mask = 0775
valid users = usuario
EOF
# Reiniciar Samba
sudo systemctl restart smbd
sudo smbpasswd -a usuario
Sistema de Etiquetado y Correspondientes
# Crear etiquetas y correspondientes desde el panel web
# Panel > Configuración > Etiquetas > Agregar etiqueta
# Ejemplos de etiquetas útiles:
# - Facturas, Contratos, Banco, Impuestos, Médico, Seguros
# Correspondientes (personas o empresas que emiten documentos):
# - Empresa Eléctrica, Banco X, Gestor Fiscal, etc.
# Tipos de documento:
# - Factura, Contrato, Extracto Bancario, Carta, etc.
Crear reglas de asignación automática (Panel > Reglas de asignación):
# Ejemplo de regla automática:
# Si el título contiene "FACTURA" → asignar tipo "Factura"
# Si el correspondiente es "EMPRESA ELÉCTRICA" → asignar etiqueta "Electricidad"
# Si la fuente contiene "banco" → asignar etiqueta "Banco"
# Las reglas se crean desde el panel web con interfaz gráfica
# Configuración > Reglas de asignación > Agregar regla
Búsqueda de Texto Completo
# La búsqueda full-text se realiza desde la interfaz web
# Búsquedas de ejemplo:
# "factura electricidad enero 2024"
# "contrato alquiler"
# tipo:factura fecha:2024
# Búsqueda avanzada con operadores:
# content:"número de cuenta" → buscar en el texto del documento
# tag:banco → filtrar por etiqueta
# correspondent:empresa-x → filtrar por correspondiente
# created:[2024-01 TO 2024-12] → filtrar por rango de fechas
Integración con Email
Configurar Paperless-ngx para consumir documentos desde un buzón de email:
# Agregar en .env
PAPERLESS_EMAIL_HOST=imap.tu-dominio.com
PAPERLESS_EMAIL_PORT=993
PAPERLESS_EMAIL_USE_SSL=true
Desde el panel web: Configuración > Cuentas de correo > Agregar cuenta:
- Servidor IMAP:
imap.tu-dominio.com - Puerto:
993(IMAP SSL) - Usuario y contraseña del buzón
- Carpeta:
INBOXo carpeta dedicada comoPaperless
Reglas de correo (Panel > Reglas de correo):
- Asunto contiene "factura" → consumir adjuntos y mover a carpeta
- Remitente es "[email protected]" → asignar correspondiente automáticamente
Proxy Inverso con Nginx
# Obtener certificado SSL
sudo certbot --nginx -d docs.tu-dominio.com
# Configuración de Nginx para Paperless
sudo tee /etc/nginx/sites-available/paperless << 'EOF'
server {
listen 443 ssl http2;
server_name docs.tu-dominio.com;
ssl_certificate /etc/letsencrypt/live/docs.tu-dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/docs.tu-dominio.com/privkey.pem;
# Subida máxima para documentos grandes
client_max_body_size 100M;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_read_timeout 600s;
}
}
EOF
sudo ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
Backup y Restauración
# Exportar todos los documentos y metadatos
docker exec paperless-webserver-1 document_exporter /usr/src/paperless/export
# Copiar la exportación al host
docker cp paperless-webserver-1:/usr/src/paperless/export ~/paperless/export/
# Crear un backup comprimido
tar -czf paperless-backup-$(date +%Y%m%d).tar.gz ~/paperless/export/
# Restaurar desde backup
# 1. Iniciar Paperless limpio
docker compose up -d
# 2. Importar los documentos exportados
docker exec paperless-webserver-1 document_importer /usr/src/paperless/export
# Backup de la base de datos PostgreSQL
docker exec paperless-db-1 pg_dump -U paperless paperless | \
gzip > ~/backups/paperless-db-$(date +%Y%m%d).sql.gz
Solución de Problemas
Los documentos no se procesan:
# Ver los logs del consumo
docker logs paperless-webserver-1 2>&1 | tail -50
docker logs paperless-webserver-1 2>&1 | grep -i "error\|failed\|consumed"
# Verificar que el directorio de consumo está montado correctamente
docker exec paperless-webserver-1 ls /usr/src/paperless/consume/
# Comprobar permisos
ls -la ~/paperless/consume/
El OCR no reconoce el idioma español:
# Verificar que el paquete de idioma está instalado en el contenedor
docker exec paperless-webserver-1 tesseract --list-langs
# Si "spa" no aparece, verificar la variable PAPERLESS_OCR_LANGUAGE
docker exec paperless-webserver-1 env | grep OCR
Paperless no conecta con la base de datos:
# Verificar el estado de los servicios
docker compose ps
# Ver logs de la base de datos
docker compose logs db --tail 30
# Probar la conexión a la base de datos manualmente
docker exec paperless-webserver-1 python3 manage.py dbshell
Conclusión
Paperless-ngx transforma la gestión documental en una tarea eficiente y organizada. Con OCR multilingüe, búsqueda de texto completo y etiquetado automático, elimina el tiempo invertido en buscar documentos físicos y crea un archivo digital seguro y duradero. Alojado en tu propio servidor, mantiene la privacidad total de tus documentos personales y empresariales.


