From 6b0f28cf743fbc39c4c7ea57732832dc1bac4cde Mon Sep 17 00:00:00 2001 From: Benny Date: Mon, 21 Sep 2026 21:08:03 -0400 Subject: [PATCH] docs(deploy): note the /data uid/gid-mismatch trap on first start MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hit this deploying to the real Unraid host: the container runs as a fixed non-root uid/gid (999), not root and not Unraid's usual nobody:users (99:100). A freshly-created appdata directory is owned by nobody:users with no write access for anyone else, so the container starts but uvicorn fails immediately with "unable to open database file" — not obvious from the error alone, worth documenting once rather than re-debugging it later. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01R2ZKeWkZV7ehf7fivrAkkG --- deploy/README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/deploy/README.md b/deploy/README.md index 1d8a844..fa00fd2 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -63,6 +63,13 @@ the same values, there's no separate migration-time config anymore (docs/DECISIO |---|---| | `/data` | The SQLite database file. Will also hold the content-addressed blob store once Phase 1 builds ingestion. This is the only thing that needs backing up. | +The container runs as a fixed non-root user (uid/gid `999`), not root and not Unraid's usual +`nobody:users` (99:100). If `/data`'s host directory doesn't already exist, Docker/Unraid creates +it owned by `nobody:users` with no write access for other users — the container starts, but +uvicorn fails immediately with `sqlite3.OperationalError: unable to open database file`, since it +can't create the SQLite file inside a directory it can't write to. Fix once, before first start: +`chown -R 999:999 ` (e.g. `/mnt/user/appdata/velodrome` on Unraid). + ## Unraid Import `unraid-template.xml` from the Docker tab's "Add Container" template picker — it exposes