Paperless-ngx: Digitaliza Documentos con IA en tu Homelab (Guía Completa 2025)

⏱️ Tiempo de lectura: 15 minutos

📅 Actualizado: Noviembre 2025

TL;DR

Paperless-ngx es un sistema de gestión documental open source que transforma tu homelab en un archivo digital inteligente. Con OCR integrado (Tesseract), clasificación automática mediante IA y búsqueda full-text, puedes digitalizar facturas, contratos y documentos sin depender de Google Drive o servicios cloud. En esta guía instalamos el stack completo con Docker Compose, configuramos OCR en español, automatizamos la clasificación y lo integramos con tu infraestructura existente.

—

📚 Tabla de Contenidos

1. ¿Qué es Paperless-ngx?
2. Arquitectura y Componentes
3. Requisitos del Sistema
4. Instalación con Docker Compose
5. Configuración del OCR
6. Flujos de Consumo de Documentos
7. Clasificación Automática con IA
8. Integración con tu Homelab
9. Comparativa: Paperless-ngx vs Alternativas
10. Mejores Prácticas
11. Troubleshooting
12. Preguntas Frecuentes
13. Conclusión

—

¿Qué es Paperless-ngx?

Paperless-ngx es un sistema de gestión documental (DMS) de código abierto que convierte documentos físicos y digitales en un archivo completamente buscable. Es el fork comunitario de Paperless-ng, mantenido activamente desde 2022 con actualizaciones constantes.

Características principales

• OCR multilingüe: Tesseract extrae texto de imágenes y PDFs escaneados en más de 100 idiomas
• Búsqueda full-text: Encuentra cualquier palabra dentro de tus documentos
• Clasificación automática: La IA aprende de tus documentos y sugiere tags, correspondientes y tipos
• Interfaz web moderna: Dashboard responsive con drag-and-drop
• Multi-usuario: Permisos granulares para equipos y familias
• API REST completa: Integración con n8n, Home Assistant y cualquier sistema

¿Por qué self-hosted?

A diferencia de Google Drive o Dropbox, Paperless-ngx te ofrece:

—

Arquitectura y Componentes

Paperless-ngx utiliza una arquitectura modular basada en contenedores Docker:

┌─────────────────────────────────────────────────────────────┐
│                      PAPERLESS-NGX                          │
├─────────────────────────────────────────────────────────────┤
│  FRONTEND                                                   │
│  └── Django + React (interfaz web)                          │
├─────────────────────────────────────────────────────────────┤
│  BACKEND SERVICES                                           │
│  ├── Consumer (procesa documentos nuevos)                   │
│  ├── Scheduler (tareas programadas)                         │
│  └── Gunicorn (servidor web)                                │
├─────────────────────────────────────────────────────────────┤
│  EXTERNAL SERVICES                                          │
│  ├── PostgreSQL (base de datos)                             │
│  ├── Redis (cola de tareas + caché)                         │
│  ├── Tesseract (motor OCR)                                  │
│  ├── Tika (extracción texto Office) [opcional]              │
│  └── Gotenberg (conversión docs) [opcional]                 │
└─────────────────────────────────────────────────────────────┘

Flujo de procesamiento

1. Entrada: Documento llega (carpeta, email, API, web)
2. Consumer: Detecta el archivo y lo encola
3. OCR: Tesseract extrae texto de imágenes/PDFs
4. Clasificación: IA sugiere metadatos basándose en contenido
5. Indexación: Texto se guarda en base de datos
6. Almacenamiento: Original + thumbnail + texto

—

Requisitos del Sistema

Hardware mínimo

Software necesario

• Docker y Docker Compose
• Linux (Debian, Ubuntu, Proxmox, TrueNAS)
• Acceso a puertos 8000 (web) o reverse proxy

Estimación de almacenamiento

• 1 página escaneada ≈ 100 KB (después de OCR)
• 1.000 documentos ≈ 1-2 GB
• Thumbnails: +20% adicional

—

Instalación con Docker Compose

Paso 1: Preparar el entorno

# Crear directorio
mkdir -p ~/paperless && cd ~/paperless
# Crear carpetas necesarias
mkdir -p consume export

Paso 2: Crear docker-compose.yml

version: "3.8"
services:
  # Redis para cola de tareas
  broker:
    image: redis:7-alpine
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
  # PostgreSQL para base de datos
  db:
    image: postgres:15-alpine
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${PAPERLESS_DBPASS:-paperless}
  # Aplicación principal
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      - broker
      - db
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    environment:
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${PAPERLESS_DBPASS:-paperless}
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_TIME_ZONE: Europe/Madrid
      PAPERLESS_OCR_LANGUAGE: spa+eng
      PAPERLESS_ADMIN_USER: ${PAPERLESS_ADMIN_USER:-admin}
      PAPERLESS_ADMIN_PASSWORD: ${PAPERLESS_ADMIN_PASSWORD:-changeme}
      USERMAP_UID: 1000
      USERMAP_GID: 1000
volumes:
  redis_data:
  pgdata:
  data:
  media:

Paso 3: Configurar variables de entorno

Crea un archivo .env:

# Zona horaria
TZ=Europe/Madrid
# Base de datos
PAPERLESS_DBPASS=password_segura_aqui
# Administrador
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=otra_password_segura

Paso 4: Iniciar el stack

docker compose up -d
# Ver logs
docker compose logs -f webserver

Paso 5: Acceder a la interfaz

Abre http://localhost:8000 e inicia sesión con las credenciales configuradas.

—

Configuración del OCR

Idiomas disponibles

Paperless-ngx usa Tesseract OCR con soporte para más de 100 idiomas:

Configurar múltiples idiomas

# En docker-compose.yml o .env
PAPERLESS_OCR_LANGUAGE=spa+eng+cat

Modos de OCR

# skip_noarchive: Solo procesa si no tiene texto (recomendado)
PAPERLESS_OCR_MODE=skip_noarchive
# force: Siempre ejecuta OCR (más lento)
PAPERLESS_OCR_MODE=force
# skip: Nunca ejecuta OCR
PAPERLESS_OCR_MODE=skip

Optimizar reconocimiento

Para documentos con tipografías difíciles:

# Aumentar calidad de preprocesamiento
PAPERLESS_OCR_DESKEW=true
PAPERLESS_OCR_ROTATE_PAGES=true
PAPERLESS_OCR_CLEAN=true

—

Flujos de Consumo de Documentos

1. Carpeta de consumo (Consume Folder)

La forma más sencilla: deja documentos en la carpeta ./consume/ y Paperless los procesa automáticamente.

# Configuración
PAPERLESS_CONSUMER_POLLING=30        # Revisar cada 30 segundos
PAPERLESS_CONSUMER_RECURSIVE=true    # Incluir subcarpetas

Formatos soportados: PDF, PNG, JPG, JPEG, TIFF, GIF, WEBP, TXT

2. Interfaz web (Drag & Drop)

Desde el dashboard, arrastra archivos directamente a la zona de carga.

3. Email IMAP

Configura una cuenta de correo para que Paperless importe adjuntos automáticamente:

PAPERLESS_EMAIL_HOST=imap.gmail.com
PAPERLESS_EMAIL_PORT=993
PAPERLESS_EMAIL_HOST_USER=tu_email@gmail.com
PAPERLESS_EMAIL_HOST_PASSWORD=tu_app_password
PAPERLESS_EMAIL_INBOX_FOLDER=INBOX

Consejo: Crea una cuenta dedicada y reenvía facturas automáticamente.

4. API REST

Ideal para integración con n8n o scripts:

curl -X POST http://localhost:8000/api/documents/post_document/ \
  -H "Authorization: Token TU_TOKEN_API" \
  -F "document=@factura.pdf" \
  -F "title=Factura Noviembre"

5. Apps móviles

Escanea documentos con tu móvil y envíalos directamente:

• Genius Scan: Exporta a carpeta de consumo vía SMB/WebDAV
• Microsoft Lens: Envía por email a la cuenta configurada
• SwiftScan: Integración directa con servidores

—

Clasificación Automática con IA

Paperless-ngx incluye un sistema de aprendizaje automático que mejora con el uso.

Conceptos clave

• Tags: Etiquetas para categorizar (factura, contrato, personal)
• Correspondientes: Emisor del documento (Vodafone, Hacienda, Amazon)
• Tipos de documento: Clasificación por tipo (factura, recibo, carta)

Algoritmos de matching

Crear un tag automático

1. Ve a Administración → Tags
2. Crea un tag (ej: «Facturas»)
3. En Matching algorithm, selecciona auto
4. Paperless aprenderá de los documentos que etiquetes manualmente

Entrenamiento del modelo

Cuantos más documentos etiquetes manualmente, mejor será la clasificación automática. Después de ~50 documentos por categoría, las sugerencias son muy precisas.

—

Integración con tu Homelab

Reverse Proxy con Traefik

# Añade estas labels al servicio webserver
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.paperless.rule=Host(`docs.tudominio.com`)"
  - "traefik.http.routers.paperless.tls.certresolver=letsencrypt"
  - "traefik.http.services.paperless.loadbalancer.server.port=8000"

Reverse Proxy con Nginx Proxy Manager

1. Añade un nuevo Proxy Host
2. Domain: docs.tudominio.com
3. Forward Hostname: IP de tu servidor
4. Forward Port: 8000
5. Activa SSL con Let’s Encrypt

Backup con TrueNAS

Configura volúmenes Docker en un dataset ZFS para snapshots automáticos:

volumes:
  - /mnt/pool/paperless/data:/usr/src/paperless/data
  - /mnt/pool/paperless/media:/usr/src/paperless/media

Automatización con n8n

Crea workflows para:

• Notificar cuando se procesa un documento nuevo
• Clasificar documentos basándose en reglas externas
• Exportar automáticamente a backup mensual

Acceso remoto con Tailscale

Si usas Tailscale en tu homelab, Paperless estará accesible desde cualquier dispositivo de tu red mesh sin exponer puertos.

—

Comparativa: Paperless-ngx vs Alternativas

¿Cuándo elegir Paperless-ngx?

• ✅ Tienes homelab con Docker
• ✅ Valoras la privacidad
• ✅ Quieres control total sobre tus datos
• ✅ No quieres pagar suscripciones mensuales

¿Cuándo considerar alternativas?

• ❌ Necesitas colaboración en tiempo real (Google Docs)
• ❌ Requieres cumplimiento normativo empresarial (DocuWare)
• ❌ No tienes infraestructura para self-hosting

—

Mejores Prácticas

Estructura de tags eficiente

📁 Por tipo
├── 📄 Facturas
├── 📋 Contratos
├── 🏥 Médico
└── 🏠 Hogar

📁 Por estado
├── ⏳ Pendiente
├── ✅ Procesado
└── 📦 Archivado

📁 Por año
├── 2024
└── 2025

Naming conventions

Paperless puede renombrar archivos automáticamente:

# Formato: fecha-correspondiente-titulo
PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{created}-{title}

Resultado: 2025/Amazon/2025-11-27-Pedido-12345.pdf

Estrategia de backup (Regla 3-2-1)

1. 3 copias: Original + 2 backups
2. 2 medios diferentes: SSD + NAS
3. 1 offsite: Cloud cifrado o disco externo

Script de backup incluido en los ejemplos:

./scripts/backup.sh ./backups

Seguridad

• Usuarios separados: Crea cuentas por persona/función
• Permisos granulares: Limita acceso por tags/correspondientes
• 2FA: Activa autenticación de dos factores
• Reverse proxy: Siempre HTTPS, nunca expongas el puerto 8000 directamente

—

Troubleshooting

OCR no reconoce texto

Síntoma: Documentos se procesan pero no son buscables.

Solución:

# Verificar idiomas instalados
docker compose exec webserver tesseract --list-langs
# Si falta español:
docker compose exec webserver apt-get update
docker compose exec webserver apt-get install -y tesseract-ocr-spa

Documentos duplicados

Síntoma: El mismo documento aparece varias veces.

Solución: Paperless usa hash MD5 para detectar duplicados. Si tienes duplicados, probablemente los archivos tienen diferencias mínimas (metadatos, compresión).

# Buscar duplicados manualmente
docker compose exec webserver python manage.py document_fuzzy_match

Consumo lento de carpetas

Síntoma: Los documentos tardan mucho en procesarse.

Solución:

# Aumentar workers
PAPERLESS_TASK_WORKERS=4
# Reducir frecuencia de polling
PAPERLESS_CONSUMER_POLLING=60

Errores de permisos Docker

Síntoma: Permission denied al acceder a carpetas.

Solución:

# Verificar UID/GID de tu usuario
echo $UID && id -g
# Actualizar en docker-compose.yml
environment:
  - USERMAP_UID=1000
  - USERMAP_GID=1000
# Ajustar permisos
sudo chown -R 1000:1000 ./consume ./export

PDFs grandes fallan

Síntoma: Error de memoria con documentos pesados.

Solución:

PAPERLESS_OCR_MAX_IMAGE_PIXELS=500000000
PAPERLESS_MEMORY_LIMIT=4G

—

Preguntas Frecuentes

¿Paperless-ngx funciona con documentos escaneados?

Sí, es su función principal. El motor OCR (Tesseract) extrae texto de imágenes escaneadas y las convierte en documentos buscables. Soporta PDF, PNG, JPG, TIFF y más.

¿Puedo buscar texto dentro de PDFs?

Absolutamente. Después del procesamiento OCR, todo el texto está indexado y es buscable desde la interfaz web o la API.

¿Cuánto espacio en disco necesito?

Depende del volumen de documentos. Una página escaneada ocupa ~100 KB después del procesamiento. Para 10.000 documentos, calcula unos 10-20 GB incluyendo thumbnails.

¿Es seguro para documentos confidenciales?

Sí, porque todo se almacena localmente en tu servidor. No hay conexión a servicios externos. Además, puedes configurar usuarios con permisos específicos y activar 2FA.

¿Puedo acceder desde el móvil?

La interfaz web es completamente responsive. También puedes usar apps de escaneo como Genius Scan o Microsoft Lens para enviar documentos directamente.

¿Funciona con escáneres de red?

Sí. Configura tu escáner para guardar en la carpeta de consumo vía SMB/CIFS o FTP. Paperless detectará y procesará automáticamente los nuevos archivos.

¿Cómo migro desde otro sistema?

Paperless acepta importación masiva. Copia tus PDFs a la carpeta de consumo y se procesarán automáticamente. Para metadata existente, usa la API REST o el importador CSV.

¿Puedo usar GPU para acelerar OCR?

Tesseract no aprovecha GPU directamente, pero puedes usar backends alternativos como EasyOCR con CUDA para volúmenes muy grandes.

¿Soporta firmas digitales?

Paperless preserva las firmas digitales existentes en los PDFs. No puede verificarlas ni crearlas, pero no las corrompe durante el procesamiento.

¿Cómo hago backup de todo?

Usa el script incluido que exporta base de datos + media + configuración:

./scripts/backup.sh ./backups

¿Puedo compartir documentos con otros usuarios?

Sí. Crea usuarios con permisos específicos. Puedes limitar acceso por tags, correspondientes o tipos de documento.

¿Funciona completamente offline?

Sí. Una vez instalado, no necesita conexión a internet. Toda la IA y OCR se ejecutan localmente.

¿Qué pasa si el contenedor falla?

Los datos están en volúmenes Docker persistentes. Simplemente reinicia con docker compose up -d y todo sigue funcionando.

¿Puedo editar documentos dentro de Paperless?

No directamente. Paperless es para archivo y búsqueda, no edición. Puedes descargar, editar externamente y volver a subir.

¿Hay API REST para automatización?

Sí, completa y documentada. Puedes integrar con n8n, Home Assistant, scripts Python o cualquier sistema que hable HTTP.

—

Conclusión

Paperless-ngx transforma tu homelab en un archivo digital inteligente sin depender de servicios cloud. Con OCR multilingüe, clasificación automática mediante IA y búsqueda full-text, tendrás tus documentos organizados y accesibles en segundos.

Próximos pasos

1. Instala el stack con Docker Compose siguiendo esta guía
2. Configura OCR para tus idiomas principales
3. Digitaliza tus primeros 50 documentos y etiquétalos manualmente
4. Deja que la IA aprenda y automatice la clasificación

📦 Descargar Ejemplos

Todos los archivos de configuración usados en esta guía están disponibles en:

👉 GitHub: paperless-ngx/paperless-setup

Incluye:

• docker-compose.yml – Stack completo
• docker-compose.traefik.yml – Con Traefik + SSL
• Scripts de backup/restore
• Configuración de ejemplo

—

🤝 Únete a la Comunidad

¿Tienes dudas sobre Paperless-ngx o quieres compartir tu setup? Únete a nuestra comunidad en Discord donde resolvemos dudas y compartimos configuraciones de homelab:

👉 Discord ElDiarioIA

—

Enlaces Relacionados

• TrueNAS Scale: NAS Potente con Docker y ZFS para tu Homelab
• Nginx Proxy Manager: Reverse Proxy con UI Visual y SSL Automático
• Traefik Reverse Proxy: Guía Completa para Homelab
• Immich: La Alternativa Self-Hosted a Google Photos
• Docker Compose: De 0 a Homelab Completo
• Tailscale para Homelab: VPN Mesh sin Abrir Puertos
• Uptime Kuma: Monitoreo Self-Hosted Gratis para tu Homelab
• n8n Automatización: 20 Workflows Listos para Usar