Respuesta actual: no uses el fallo de instalación de la beta 1.4.2 como modelo de configuración de Paperless-ngx para 2026
La instalación original se detuvo en el 83 % en ZimaOS 1.4.2-beta2, e IceWhale indicó que esa versión había cambiado la tecnología de origen/proxy para la instalación de aplicaciones y que el problema se estaba solucionando. El ZimaOS actual ya publica un procedimiento específico para instalar Paperless-ngx, y el proyecto upstream cuenta con una ruta madura mediante Docker Compose. Considera el bloqueo de 2025 como un error histórico del instalador, no como una prueba de que Paperless-ngx sea fundamentalmente incompatible con ZimaOS.
Comienza con la configuración actual de la tienda de aplicaciones de ZimaOS
Las instrucciones actuales de ZimaOS utilizan Paperless-ngx desde la tienda de aplicaciones con la instalación personalizada, para que puedas configurar la ruta de consumo, las credenciales del administrador, los idiomas de OCR y los valores de URL de confianza antes del primer inicio. La configuración de Paperless en ZimaOS es la referencia específica actual del producto.
Los requisitos de Paperless-ngx ayudan a dimensionar la aplicación antes de ejecutar trabajos de OCR grandes.
Coloca los datos persistentes en un almacenamiento que puedas respaldar
Paperless tiene varios tipos de estado: datos de la base de datos, datos de la aplicación, archivos multimedia/documentos, archivos exportados y la carpeta de consumo. Mantén esas rutas persistentes fuera de la capa desechable del contenedor. Si eliminas AppData durante la depuración, también podrías borrar las pruebas o el estado necesarios para entender por qué falló la instalación anterior.
La configuración de Paperless con Docker define los servicios upstream y la implementación recomendada de PostgreSQL.
Entiende la cuestión de Tika y Gotenberg
Paperless puede ejecutarse sin Tika/Gotenberg para su flujo principal de documentos PDF e imágenes. Tika y Gotenberg son servicios opcionales que se utilizan cuando necesitas procesar archivos de Office y correos electrónicos. Si un paquete presenta un fallo relacionado con Tika, decide primero si realmente necesitas esa función antes de bloquear toda la instalación por ese motivo.
La configuración de Tika de Paperless enumera los endpoints y las variables de activación.
Si la instalación se detiene en un porcentaje, observa los contenedores en lugar de esperar durante horas
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redisLos nombres exactos de los contenedores dependen del paquete de la tienda de aplicaciones. Busca fallos al descargar imágenes, problemas de disponibilidad de la base de datos, permisos, configuración de CSRF o un servicio atrapado en un ciclo de reinicio. El “83 %” es un síntoma de la interfaz; los registros de los contenedores identifican el componente que falla.
Corrige la propiedad de la carpeta de consumo antes de culpar al OCR
Paperless debe poder leer y mover archivos desde el directorio de consumo. La configuración upstream de Docker admite USERMAP_UID/USERMAP_GID para ajustar los permisos del host. Si los archivos aparecen en la carpeta de consumo del host, pero Paperless nunca los procesa, comprueba la propiedad, la ruta montada y las notificaciones del sistema de archivos.
Los requisitos de las aplicaciones de ZimaOS ayudan a evitar que un archivo documental en crecimiento ocupe una unidad pequeña del sistema operativo.
Configura correctamente la URL externa
Cuando accedas a Paperless mediante una dirección del host de ZimaOS o un proxy inverso, configura los orígenes de confianza y la URL pública con la dirección que realmente abren los usuarios. Una configuración incorrecta del origen suele manifestarse después como un error 403 de CSRF, aunque todos los contenedores estén funcionando correctamente.
Haz copias de seguridad de la base de datos y los documentos juntos
Los archivos de documentos sin la base de datos de Paperless pierden las etiquetas, los corresponsales, los campos personalizados y el estado del flujo de trabajo; la base de datos sin los archivos multimedia pierde los documentos reales. Haz copias de seguridad de ambos como una única unidad de recuperación y prueba una restauración antes de realizar actualizaciones importantes.
La copia de seguridad de ZimaOS proporciona la capa de recuperación a nivel de NAS.
Preguntas frecuentes
¿Por qué Paperless-ngx se detuvo en el 83 % en ZimaOS?
En el caso original, IceWhale relacionó el fallo con cambios en el origen/proxy de las aplicaciones de ZimaOS 1.4.2 beta. En un sistema actual, inspecciona los registros de los contenedores en lugar de asumir que se trata del mismo error antiguo.
¿Paperless-ngx requiere Tika?
No para la gestión principal de documentos PDF e imágenes. Tika y Gotenberg son opcionales cuando necesitas procesar documentos de Office y correos electrónicos.
¿Dónde debería estar la carpeta de consumo?
Utiliza un almacenamiento de datos persistente de ZimaOS, con una ruta clara del host y permisos que permitan al contenedor de Paperless leer y modificar los archivos.
¿Debería eliminar AppData y reinstalar?
Solo después de entender qué datos se eliminarán y de tener una copia de seguridad. Reinstalar no soluciona una ruta de volumen, unos permisos o una configuración de URL incorrectos.
¿Qué base de datos debería utilizar una instalación nueva de Paperless?
Actualmente, el proyecto upstream recomienda PostgreSQL para las instalaciones nuevas.
