Solución de la comunidad

La pila de Portainer falla en ZimaOS: comprueba primero las rutas relativas de los volúmenes

A ZimaOS user saw an error while creating a Portainer stack and initially suspected the host filesystem was read-only. The root cause was later identified as relative volume paths in docker-compose.yml.

Este hilo comenzó como una pregunta sobre cómo deshabilitar un sistema de archivos de solo lectura en ZimaOS, pero ese no era el problema real. Después de revisar la configuración, el autor original descubrió que el archivo Compose utilizaba rutas de volúmenes relativas.

Esa distinción es importante porque cambiar los permisos del sistema de archivos del host o volver a montar rutas del sistema habría sido una solución incorrecta en este caso.

Error de implementación de una pila de Portainer que llevó al usuario a revisar las rutas de volúmenes de Docker Compose
Captura de pantalla original de la comunidad correspondiente a la implementación fallida de la pila de Portainer, antes de identificar que la causa eran los volúmenes relativos.

Comprueba el archivo Compose antes de cambiar ZimaOS

Cuando una pila de contenedores no puede crear ni escribir en una ruta, primero identifica qué monta el archivo Compose en el contenedor. Un montaje enlazado puede hacer referencia a una ruta del host, mientras que un volumen con nombre lo gestiona Docker. Las reglas actuales de volúmenes de Docker Compose indican que las rutas relativas del host se resuelven desde la ubicación del proyecto Compose.

En un NAS autogestionado, una ruta persistente explícita suele ser más fácil de interpretar que una ruta relativa ambigua, ya que puedes verificar que el directorio de origen existe realmente y permite escritura.

Por qué la suposición de solo lectura era engañosa

Un problema real de sistema de archivos de solo lectura suele afectar a más de una ruta de Compose y debe diagnosticarse a partir del estado real de los montajes y de los registros del sistema. En este hilo, el usuario no necesitaba desactivar ningún mecanismo de protección de ZimaOS. En su lugar, corrigió la configuración de los volúmenes relativos.

Qué sugirió la comunidad

Antes de conocer la causa principal, una respuesta de la comunidad sugirió abrir el modo de desarrollador de ZimaOS, usar el terminal web como usuario root y crear manualmente el directorio necesario. Esto puede ser útil cuando la ruta del host prevista realmente no existe, pero debe hacerse después de comprobar la ruta de Compose, no como sustituto de esa comprobación.

Un orden de resolución de problemas más seguro

  1. Revisa cada entrada de volumes: en el archivo Compose.
  2. Determina si cada origen es un volumen con nombre, una ruta absoluta del host o una ruta relativa.
  3. Confirma que existe el directorio esperado del host.
  4. Confirma que el contenedor no esté montado explícitamente con :ro ni con read_only: true.
  5. Investiga el estado de los montajes del sistema de archivos del host únicamente si el mismo error de escritura persiste fuera de la configuración del contenedor.

Contexto actual de Docker y Portainer

Para las implementaciones actuales de ZimaOS, los requisitos de hardware de Portainer ofrecen el contexto general sobre la persistencia y el entorno de ejecución de Portainer, mientras que la guía sobre la primera aplicación Docker explica cómo las aplicaciones de ZimaOS asignan datos persistentes a los contenedores. Si un montaje es realmente de solo lectura y no está simplemente mal direccionado, la guía para solucionar un montaje enlazado de Docker distingue entre un montaje configurado con :ro y un sistema de archivos del host que ha dejado de aceptar escrituras.

Las reglas de montajes enlazados de Docker confirman que estos montajes pueden utilizar rutas de origen del host y que el comportamiento de solo lectura se controla explícitamente con readonly o ro. El comportamiento de las pilas de Portainer define una pila de Portainer como un conjunto relacionado de servicios, por lo que se debe revisar el archivo Compose antes de cambiar el propio host de ZimaOS.

En resumen

El error registrado en la pila de Portainer no se solucionó deshabilitando un sistema de archivos de solo lectura. El usuario corrigió las rutas de volúmenes relativas en docker-compose.yml. Para errores similares de contenedores en ZimaOS, valida la definición de los montajes de Compose antes de realizar cambios en el sistema de archivos del host.