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: INBOX o carpeta dedicada como Paperless

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.