La instalación de Paperless-ngx desde la tienda de aplicaciones de ZimaOS falló en una etapa avanzada del proceso: primero apareció un error de autorización al descargar una imagen de Tika desde GitHub Container Registry y, posteriormente, un fallo de DNS al intentar acceder a un espejo del registro. Esto hace que el problema sea más complejo que afirmar que «Paperless está averiado»: el componente que fallaba era una ruta opcional del servicio o la imagen de Tika, y el punto de acceso al registro cambió entre los intentos.
El hilo público nunca llegó a una solución confirmada para la tienda de aplicaciones de ZimaOS. Un usuario cambió la imagen de Tika por la imagen de Apache y logró completar la instalación al 100 %, pero la pila aún no se ejecutaba. La documentación actual de Paperless-ngx ofrece ahora un camino más claro: usar las plantillas de Docker Compose mantenidas y habilitar la variante con Tika/Gotenberg solo cuando se necesiten esos formatos de documentos.
El primer fallo fue un error de autorización de GHCR
El error original apareció aproximadamente al 80 %:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedEliminar las imágenes locales de Docker y reinstalar no cambió el resultado, lo que apunta a que no se trataba simplemente de una imagen local obsoleta.
El siguiente intento falló al resolver el DNS
Dos días después, el error cambió a un fallo de resolución DNS para el nombre de host de un espejo del registro. Por ello, un miembro de la comunidad sugirió comprobar la resolución de nombres, la conectividad HTTPS básica, el filtrado DNS, el funcionamiento de la VPN o el proxy y la descarga manual de la imagen.
Esas fueron comprobaciones de diagnóstico propuestas por la comunidad, no una causa raíz confirmada por IceWhale.
Tika es opcional en las versiones actuales de Paperless-ngx
La documentación actual de Paperless-ngx indica que Tika y Gotenberg son servicios opcionales que se utilizan para documentos de Office, como DOC/XLSX/ODT, y para analizar correos electrónicos. Si no se necesitan esos formatos, no es necesario habilitar Tika.
Si son necesarios, utiliza la variante de Compose mantenida que incluye Tika y Gotenberg, en lugar de una referencia antigua a una imagen de la tienda de aplicaciones.
Docker Compose oficial actual es la mejor referencia
La guía de configuración actual de Paperless-ngx recomienda Docker para la mayoría de los usuarios y proporciona archivos Compose mantenidos. Para las instalaciones nuevas se recomienda utilizar PostgreSQL, y las plantillas con Tika se ofrecen por separado.
Utiliza el modelo actual de instalación de Paperless-ngx con Docker Compose si el paquete de la tienda de aplicaciones de ZimaOS está obsoleto o hace referencia a una imagen auxiliar que no está disponible.
Cambiar únicamente la imagen de Tika puede no ser suficiente
Un participante sustituyó la imagen de Tika por apache/tika:latest. La instalación llegó al 100 %, pero la aplicación siguió fallando después del inicio.
Este resultado negativo es importante porque Paperless necesita que el punto de acceso del servicio, la función habilitada y la integración con Gotenberg coincidan con la configuración de Compose. Sustituir una imagen de contenedor no equivale necesariamente a migrar toda la pila.
Coloca los datos persistentes de Paperless en el espacio de almacenamiento principal
Paperless puede crecer debido a los documentos almacenados, las miniaturas, los datos de OCR, los índices de búsqueda y la base de datos. La versión actual de ZimaOS recomienda trasladar los datos de las aplicaciones fuera de la unidad del sistema antes de instalar aplicaciones que consuman mucho almacenamiento.
El modelo actual de rutas de almacenamiento de aplicaciones de ZimaOS es especialmente relevante para Paperless, ya que el espacio que ocupan sus datos puede crecer mucho más que el tamaño de la imagen de Docker.
Los permisos son importantes para la carpeta de consumo
La documentación actual de Paperless-ngx expone USERMAP_UID y USERMAP_GID para que el contenedor pueda escribir en las carpetas montadas del equipo anfitrión. Si la pila se instala pero no puede importar documentos, verifica estos valores y los permisos de las carpetas del equipo anfitrión en lugar de volver a investigar el registro.
No confundas el nombre de host de un espejo del registro con la aplicación Paperless
El segundo error original hacía referencia a un nombre de host con formato de espejo, en lugar del punto de acceso principal ghcr.io. Esta distinción es importante: un paquete de aplicación puede ser perfectamente válido mientras el espejo de imágenes configurado, el servidor DNS o la ruta regional del registro no estén disponibles.
Si una descarga manual desde el registro oficial funciona, pero la tienda de aplicaciones sigue intentando utilizar un espejo defectuoso, el problema corresponde a la capa del paquete o del enrutamiento del registro, no a Paperless.
Distingue entre un fallo al descargar la imagen y un fallo al iniciar el contenedor
El primer intento original nunca terminó de descargar todas las imágenes necesarias. El experimento posterior con Apache Tika alcanzó el 100 % de la instalación, pero después falló al iniciarse. Son dos etapas de fallo diferentes y requieren evidencias distintas.
- Etapa de descarga: autenticación del registro, DNS, disponibilidad del espejo y etiqueta de la imagen.
- Etapa de inicio: variables de entorno, conectividad con la base de datos, puntos de acceso de Tika/Gotenberg, volúmenes, permisos y comprobaciones de estado.
Haz una copia de seguridad de una instancia funcional de Paperless antes de sustituir la pila de la tienda de aplicaciones
Si Paperless ya está en uso, no cambies las plantillas de Compose únicamente para corregir un servicio auxiliar sin proteger primero los documentos y la base de datos. La versión oficial actual de Paperless incluye un exportador específico para realizar copias de seguridad y migraciones.
Para una instalación nueva, es más sencillo comenzar con el archivo Compose oficial mantenido; para una instalación existente, conserva las rutas actuales de la base de datos y de los archivos multimedia antes de reescribir la pila.
Preguntas frecuentes sobre la instalación de Paperless-ngx
¿El fallo de 2025 fue definitivamente un problema de DNS?
No. El hilo mostró errores de autorización y de DNS, y no se publicó ningún diagnóstico final oficial.
¿Tika es necesario para todas las instalaciones de Paperless-ngx?
No. Es opcional y se necesita principalmente para documentos de Office y para analizar correos electrónicos.
¿Cambiar a apache/tika resolvió por completo el caso original?
No. Un usuario logró completar la instalación al 100 %, pero la aplicación siguió sin ejecutarse.
