Este tutorial de diciembre de 2025 es una de las guías comunitarias más detalladas para Paperless-ngx en ZimaOS, pero está vinculado a un paquete específico de BigBear y a ZimaOS 1.5.3 Plus. Las partes duraderas son los conceptos de almacenamiento y configuración: asignar a la carpeta de consumo una ubicación persistente y clara, establecer correctamente la URL de la aplicación, configurar los idiomas de OCR y comprender los servicios opcionales de Tika/Gotenberg.
Algunos detalles del origen requieren una aclaración actual. La configuración de Docker de Paperless-ngx ha evolucionado; ahora se recomienda PostgreSQL para las instalaciones nuevas, los archivos Compose actuales solicitan un superusuario durante la primera configuración y Tika/Gotenberg siguen siendo opcionales, en lugar de ser obligatorios para todos los flujos de trabajo de documentos.
El tutorial de origen se probó en un modesto ZimaBoard 2
El autor documentó un sistema basado en N150 con 16 GB de RAM que ejecutaba ZimaOS 1.5.3 Plus. El objetivo era acceder desde la red local o mediante Tailscale para uso doméstico, no exponerlo directamente al público.
Ese alcance es importante porque una implementación en Internet pública requiere un plan diferente de HTTPS, proxy inverso, autenticación y seguridad.
La guía utilizó la instalación personalizada de BigBear Paperless-ngx
El flujo de trabajo de origen buscó el paquete BigBear Paperless-ngx en la tienda de aplicaciones, abrió el menú desplegable de instalación y eligió Instalación personalizada para poder editar los volúmenes y los valores del entorno antes del primer inicio.
Ese es un flujo de trabajo específico del paquete. Una definición actual de la aplicación puede añadir, eliminar o cambiar el nombre de servicios y variables.
Proporciona al directorio de consumo una ruta de host persistente y clara
/usr/src/paperless/consume como la carpeta con la que es más probable que interactúen los usuarios al introducir documentos.La documentación actual del proyecto Paperless todavía utiliza /usr/src/paperless/consume como el destino estándar del contenedor y admite explícitamente cambiar el lado del host de ese montaje enlazado.
El tutorial configuró las variables de administrador, consumidor, OCR y URL
Entre las opciones de origen clave se incluyeron:
- nombre de usuario y contraseña de administrador personalizados;
- consumo recursivo de documentos;
- eliminación de los originales de la carpeta de consumo después de una ingesta correcta;
- Limpieza de OCR y configuración del idioma;
- Origen de confianza de CSRF y URL de la aplicación;
- Endpoints de Tika/Gotenberg.
PAPERLESS_URL y los orígenes CSRF deben coincidir con la forma en que realmente accedes a Paperless
El tutorial advertía que una configuración incorrecta de la URL/origen podía provocar un error 403 de verificación CSRF. Eso sigue siendo conceptualmente correcto.
La documentación actual de Paperless indica PAPERLESS_URL debe establecerse cuando la aplicación está detrás de un proxy inverso y debe representar el dominio/URL utilizado externamente. No codifiques de forma fija la dirección LAN del autor de la fuente en otra instalación.
Los ajustes de OCR también se modificaron dentro de Paperless
Los idiomas de OCR deben corresponder a los paquetes de idiomas disponibles en el contenedor. Añadir idiomas puede aumentar el tamaño de la imagen o cambiar los requisitos de los contenedores rootless, según el paquete actual.
Reiniciar después de cada lote grande de incorporación es un consejo de la fuente, no un requisito upstream
El Paperless-ngx actual está diseñado para supervisar continuamente el directorio de consumo. La documentación upstream no indica que los lotes grandes normalmente requieran un reinicio. Si los documentos dejan de procesarse, revisa los permisos, los registros del consumidor, la compatibilidad con las notificaciones del sistema de archivos y el estado del bróker/trabajador, en lugar de convertir el reinicio en un ritual obligatorio.
La configuración upstream actual recomienda PostgreSQL para instalaciones nuevas
La configuración actual de Docker de Paperless-ngx recomienda PostgreSQL para instalaciones nuevas, aunque SQLite y MariaDB siguen disponibles en configuraciones compatibles.
Para un archivo de documentos a largo plazo, esto convierte la topología actual de Compose upstream en una mejor referencia que asumir que el servicio de base de datos exacto de BigBear de 2025 permanece sin cambios.
Tika y Gotenberg son opcionales
La documentación actual de Paperless indica que Tika y Gotenberg son necesarios para analizar documentos de Office, como DOC/XLSX/ODT, y archivos de correo electrónico. Si solo incorporas formatos compatibles con la pila principal de Paperless, esta función puede permanecer deshabilitada.
Usa la configuración actual de Paperless-ngx con Docker antes de reconstruir manualmente la pila histórica de BigBear.
Los permisos de la carpeta de consumo importan más que los reinicios repetidos
La configuración upstream actual expone USERMAP_UID y USERMAP_GID para que el contenedor pueda escribir en los montajes vinculados del host. Si Paperless detecta una carpeta consume, pero no puede procesar ni eliminar archivos, verifica la propiedad del directorio asignado y la identidad del contenedor.
En ZimaOS, verifica también que la ruta consume del host se encuentre en el almacenamiento gestionado previsto y no en una asignación de volumen de solo lectura.
Eliminar los originales de /consume no equivale a eliminar los documentos archivados
El autor original habilitó PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Esto controla qué ocurre con el archivo de entrada del directorio consume después de una ingestión correcta. El documento archivado gestionado por Paperless permanece en su almacenamiento multimedia.
Prueba este comportamiento con documentos desechables antes de apuntar un escáner automatizado o un servicio de sincronización a una carpeta de producción.
Las respuestas sobre Paperless-AI corresponden a una integración independiente
Las respuestas posteriores analizaron cómo Paperless-AI leía documentos mediante la API de Paperless, pero no podía analizar ni escribir etiquetas con la configuración integrada de OpenAI. Los usuarios informaron que Mistral funcionaba y que la configuración manual de OpenAI solucionaba el problema.
Esas respuestas no demuestran que la instalación principal de Paperless-ngx esté averiada. Paperless-AI es una integración independiente de terceros con su propia configuración de proveedor/API.
Los errores 500 posteriores y las preguntas sobre contraseñas no se resolvieron en el hilo
En febrero de 2026, un usuario informó de un error HTTP 500 durante la carga, y en mayo de 2026 otro usuario no pudo hacer funcionar las contraseñas esperadas. El hilo público no contiene diagnósticos finales para esos casos.
No conviertas las credenciales de ejemplo del tutorial original en una receta de inicio de sesión universal para versiones posteriores de BigBear.
Exporta los datos de Paperless antes de realizar cambios importantes en los paquetes
La versión actual de Paperless incluye un exportador de documentos que incluye documentos, miniaturas, metadatos e información derivada de la base de datos para flujos de migración o copias de seguridad. Antes de reemplazar la base de datos o la pila de Compose, utiliza una exportación compatible con la aplicación junto con copias de seguridad normales del almacenamiento.
Preguntas frecuentes sobre Paperless-ngx en ZimaOS
¿Tika es obligatorio para todas las instalaciones de Paperless-ngx?
No. Es opcional y se necesita principalmente para documentos de Office y el análisis de correos electrónicos.
¿Normalmente los lotes grandes de consumo requieren un reinicio?
El autor original lo recomendó basándose en su experiencia, pero la documentación actual del proyecto no indica que reiniciar sea un requisito habitual.
¿Qué base de datos recomienda actualmente Paperless para las nuevas instalaciones?
PostgreSQL es el backend recomendado para las nuevas implementaciones de Docker.
¿Paperless-AI forma parte del propio Paperless-ngx?
No. Es una integración independiente de terceros que se analiza más adelante en el hilo.
