Migrar de Papermerge a Paperless-ngx

• Sin parches de seguridad: cualquier vulnerabilidad descubierta tras el archivado permanecerá abierta — FastAPI y sus dependencias publican varios avisos mensuales
• Compatibilidad Python en retroceso: las nuevas versiones de Python eliminan APIs obsoletas; una actualización del SO puede romper el entorno
• Plugins e integraciones huérfanos: los conectores de terceros no se actualizarán para seguir la evolución de la API REST de Papermerge
• Sin migraciones de esquema oficiales: si se descubre un bug de base de datos, ningún parche vendrá del repositorio archivado
• Imágenes Docker oficiales detenidas: las imágenes no oficiales introducen riesgo de cadena de suministro
• Sin cobertura de soporte contractual: ningún proveedor cubrirá una instalación sobre un proyecto archivado

• OCR multilingüe vía Tesseract: francés, árabe, español, inglés y decenas de idiomas más configurables por variable de entorno
• Etiquetas jerárquicas: organización detallada de documentos con reglas de asignación automática heredadas
• Correspondientes: identificación de remitentes/destinatarios recurrentes, asignación automática por regla
• Almacenamiento compatible S3: archivar originales en un bucket S3 o compatible (MinIO, Garage) sin modificar la interfaz
• REST API documentada: integración con flujos de trabajo externos (n8n, scripts curl) vía /api/documents/
• Carpeta de consumo: cualquier archivo depositado en /consume se ingiere automáticamente

Papermerge v3 vs Paperless-ngx

Desplace la tabla

• VPS: 2 vCPU / 2 GB RAM mínimo — 4 GB recomendados si OCR corre en paralelo durante la ingesta
• Docker y Docker Compose: Docker ≥ 24, Docker Compose ≥ 2.20 (plugin integrado, no el binario Python legacy)
• 40 GB de almacenamiento SSD mínimo para originales + datos de índice
• Dominio o subdominio con un certificado TLS válido
• Acceso root o sudo en el VPS para instalar Docker y configurar el proxy inverso
• Copia de seguridad de tu instancia Papermerge existente antes de cualquier operación: exportación de documentos + volcado de la base de datos

Migrar de Papermerge a Paperless-ngx

1. 01

   Exportar tus documentos desde Papermerge

   En la interfaz de Papermerge, ve a Documents → Export. Selecciona «Todos los documentos» e inicia la exportación. Papermerge genera un ZIP con los originales organizados por carpeta. Transfiere el archivo al VPS:

   scp papermerge-export.zip user@your-vps:/tmp/

2. 02

   Descomprimir la exportación y preparar la carpeta de consumo

   En el VPS, descomprime el archivo en un directorio temporal:

   mkdir -p /opt/paperless-import
   unzip /tmp/papermerge-export.zip -d /opt/paperless-import/

   Obtendrás una estructura de directorios y archivos. Paperless-ngx consumirá estos archivos mediante su carpeta de consumo en un paso posterior.

3. 03

   Instalar Paperless-ngx con el Docker Compose oficial

   Descarga el docker-compose.yml oficial:

   mkdir -p /opt/paperless && cd /opt/paperless
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml -o docker-compose.yml
   curl -fsSL https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/.env.example -o .env

   Edita el archivo .env: define PAPERLESS_URL, PAPERLESS_SECRET_KEY, PAPERLESS_OCR_LANGUAGE (ej. spa+eng para español + inglés) y PAPERLESS_TIME_ZONE.

4. 04

   Iniciar la instancia y crear la cuenta de administrador

   Lanza los contenedores en segundo plano:

   docker compose up -d

   Espera a que el servicio esté listo (30 a 60 segundos), luego crea el superusuario:

   docker compose exec webserver python3 manage.py createsuperuser

   Inicia sesión en http://localhost:8000 (o tu dominio) para verificar que la interfaz responde.

5. 05

   Importar los documentos exportados de Papermerge

   Copia la estructura de directorios exportada a la carpeta de consumo de Paperless-ngx:

   cp -r /opt/paperless-import/* /opt/paperless/consume/

   Paperless-ngx detectará automáticamente los nuevos archivos y los ingerirá mediante Celery. Puedes monitorizar el progreso con:

   docker compose logs -f celeryworker

6. 06

   Configurar el proxy inverso y TLS

   Expón Paperless-ngx detrás de nginx. Ejemplo de bloque mínimo:

   server {
       listen 443 ssl;
       server_name docs.your-domain.com;
       ssl_certificate /etc/letsencrypt/live/docs.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/docs.your-domain.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:8000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

   Obtén o renueva un certificado Let's Encrypt para este subdominio y recarga nginx.

7. 07

   Verificar la cobertura OCR y probar los documentos importados

   En la interfaz de Paperless-ngx, abre varios documentos importados y verifica que su contenido está indexado (barra de búsqueda funcional). Para documentos donde OCR falló, relanza el OCR mediante la interfaz o la API:

   curl -X POST http://localhost:8000/api/documents/<id>/redo_ocr/ \
     -H 'Authorization: Token <your-token>'

8. 08

   Validar y apagar la instancia Papermerge antigua

   Tras la importación completa, verifica que el número de documentos en Paperless-ngx coincide con tu exportación de Papermerge. Prueba la búsqueda de texto completo sobre términos conocidos. Una vez validado, detén la instancia Papermerge y elimina sus contenedores: docker compose down desde su directorio de despliegue.

• OCR: PAPERLESS_OCR_LANGUAGE acepta una lista de códigos de idioma Tesseract separados por + (spa+eng+fra). Si tu corpus es multilingüe, declara todos los idiomas desde el inicio
• Almacenamiento S3: define PAPERLESS_STORAGE_BACKEND=s3, PAPERLESS_S3_ACCESS_KEY, PAPERLESS_S3_SECRET_KEY y PAPERLESS_S3_BUCKET_NAME para externalizar los originales
• Reglas de asignación automática: en la interfaz, crea reglas que asignen una etiqueta, correspondiente o tipo de documento según el contenido OCR
• Tareas programadas: verifica que PAPERLESS_CONSUMER_POLLING sea 0 (inotify) o un intervalo razonable si inotify no está disponible en tu entorno Docker

• Escáner de red: configura tu escáner para enviar escaneos vía SFTP o SMB a /consume. Paperless-ngx los ingiere a su llegada sin ninguna acción manual
• Cliente de correo: el consumidor de correo (PAPERLESS_EMAIL_HOST, PAPERLESS_EMAIL_PORT) monitoriza un buzón IMAP e importa automáticamente archivos PDF adjuntos que coincidan con tus filtros
• REST API: el endpoint POST /api/documents/post_document/ acepta un archivo multipart. Desde n8n, un flujo de trabajo puede enviar cualquier adjunto recibido por correo directamente a Paperless en segundos
• App móvil: la aplicación Paperless Mobile (Android/iOS, open source) se conecta a tu instancia autoalojada mediante URL y token API

• Documentos importados sin texto OCR: verifica que el código de idioma Tesseract es correcto (PAPERLESS_OCR_LANGUAGE=spa no es). Relanza OCR en los documentos afectados mediante la interfaz o la API
• Carpeta de consumo no supervisada: si usas un volumen Docker montado desde una partición NFS o almacenamiento objeto, inotify no funciona. Configura PAPERLESS_CONSUMER_POLLING=60 para un escaneo cada 60 segundos
• Error «permission denied» en /consume: el worker de Paperless se ejecuta con UID 1000. Si los archivos copiados pertenecen a root, cambia los permisos: chown -R 1000:1000 /opt/paperless/consume/ en el host
• Importación incompleta — documentos faltantes: comprueba con find /opt/paperless-import -name '*.pdf' | wc -l y compara con el total de tu instancia Papermerge