Bottom Line: The App Was Fine—Docker Tried to Write Its CLI Config Into ZimaOS's Read-Only Root
The Compose stack already worked on another machine. On ZimaOS it failed with mkdir /root/.docker: read-only file system. Pointing DOCKER_CONFIG at a writable location fixed the real problem.
For a One-Off App, Use a Writable Docker Config Path
sudo -i
mkdir -p /var/lib/docker/.docker
export DOCKER_CONFIG=/var/lib/docker/.docker
docker compose up -dThe command worked in the real case because Docker no longer tried to create /root/.docker on the appliance root filesystem. Docker documents the DOCKER_CONFIG environment variable in its Docker CLI configuration.
For a Repeatable ZimaOS App, Package the Compose File Properly
Current ZimaOS uses normal Docker Compose for runtime settings and a top-level x-casaos block for app-store metadata. The ZimaOS app metadata defines the current v2 fields.
The upstream Docker Compose schema remains the runtime source of truth.
Why the UI Could Not Use the Locally Uploaded Image
The App Store install flow expects an image reference it can resolve through the app definition. A manually loaded local image may exist in Docker yet still not satisfy the store installer path. For a private household app, direct Compose is simpler; for distribution, publish the image to a registry or build a proper ZimaOS app package.
Keep Application Data on Writable Storage
Map databases, uploads and configuration to persistent host paths. The Portainer requirements is an alternative for manually managed Docker workloads.
Use the Store Protocol Only When You Need Store Behavior
If the goal is one family shopping-list app, direct Compose is enough. If the goal is installable catalog distribution with icons, metadata and updates, use the current ZimaOS v2 app-store structure. The ZimaOS app requirements provides the deployment context.
