diff --git a/changelog.d/fixes/14910-selfhost-eacces-docs.md b/changelog.d/fixes/14910-selfhost-eacces-docs.md
new file mode 100644
index 00000000000..9412bcc562c
--- /dev/null
+++ b/changelog.d/fixes/14910-selfhost-eacces-docs.md
@@ -0,0 +1 @@
+- **docs(docker):** document the `EACCES: permission denied` fix for `/app/data` on self-host (chown to the `node` UID 1000, or an opt-in named volume with its empty-volume/backup caveats); `docker-compose.selfhost.yml` keeps the `./data` bind mount as the active default (#14910 — thanks @matheusgcdj)
diff --git a/docker-compose.selfhost.yml b/docker-compose.selfhost.yml
index edea9d3a11e..960ae184a7f 100644
--- a/docker-compose.selfhost.yml
+++ b/docker-compose.selfhost.yml
@@ -49,7 +49,20 @@ services:
- "${APP_BIND_HOST:-127.0.0.1}:${API_PORT:-20129}:${API_PORT:-20129}"
- "${APP_BIND_HOST:-127.0.0.1}:${LIVE_WS_PORT:-20132}:${LIVE_WS_PORT:-20132}"
volumes:
+ # Default: bind-mount ./data on the host (what bin/snapshot-data.sh and
+ # bin/restore-data.sh back up and restore). Keep this line active so an
+ # existing install keeps reading the same data after pulling this file.
- ./data:/app/data
+ # EACCES on the first write to /app/data? Some managed-deploy platforms
+ # run the Docker daemon as root while the container runs as the
+ # unprivileged `node` user (UID 1000), so a root-owned ./data is not
+ # writable. Either `chown -R 1000:1000 ./data` on the host, or opt into
+ # a Docker-managed named volume: comment the bind mount above, uncomment
+ # the line below AND the `omniroute-data:` entry under `volumes:` at the
+ # bottom. A named volume starts EMPTY and is not seen by the ./data
+ # backup scripts — see docs/getting-started/SELF_HOST_GUIDE.md
+ # ("Common issues") before switching an existing install.
+ # - omniroute-data:/app/data
depends_on:
redis:
condition: service_healthy
@@ -62,3 +75,5 @@ services:
volumes:
redis-data:
+ # Only needed if you opted into the named-volume alternative above.
+ # omniroute-data:
diff --git a/docs/getting-started/SELF_HOST_GUIDE.md b/docs/getting-started/SELF_HOST_GUIDE.md
index 515b576de38..977d56c6152 100644
--- a/docs/getting-started/SELF_HOST_GUIDE.md
+++ b/docs/getting-started/SELF_HOST_GUIDE.md
@@ -317,6 +317,37 @@ Raise `OMNIROUTE_MEMORY_MB` in `.env` (e.g. `4096`), then
[Sizing the container](#sizing-the-container).
+
+EACCES: permission denied writing to /app/data
+
+`docker-compose.selfhost.yml` bind-mounts `./data:/app/data` by default, so
+the container inherits the host directory's ownership. Some managed-deploy
+platforms run the Docker daemon as root while the container process runs as
+an unprivileged user, which can cause `EACCES` on the first write.
+
+Two ways to fix it, without changing the documented default:
+
+- **`chown` the host dir** to the container's user so the bind mount is
+ writable. The image runs as the `node` user (UID/GID 1000):
+ `sudo chown -R 1000:1000 ./data`.
+- **Opt into a Docker-managed named volume** instead of the bind mount: in
+ `docker-compose.selfhost.yml`, comment out the `- ./data:/app/data` line
+ and uncomment the `- omniroute-data:/app/data` alternative right below it,
+ plus the `omniroute-data:` entry under the top-level `volumes:`. Note that
+ this changes where your data lives:
+ - a new named volume starts **empty** — on an existing install, copy
+ `./data` into it first, or OmniRoute will boot as a fresh instance;
+ - `bin/snapshot-data.sh` and `bin/restore-data.sh` read/write `./data` on
+ the host directly, so they will not see a named volume's contents unless
+ you back it up separately, for example:
+
+ ```bash
+ docker run --rm -v omniroute-data:/data -v "$PWD":/backup alpine \
+ tar czf /backup/omniroute-data.tar.gz -C /data .
+ ```
+
+
+
Web-cookie providers (Gemini Web, Claude Turnstile) fail with
Executable doesn't exist at .../ms-playwright/chromium
diff --git a/tests/unit/docker-compose-selfhost-data-volume-14910.test.ts b/tests/unit/docker-compose-selfhost-data-volume-14910.test.ts
new file mode 100644
index 00000000000..580824961cd
--- /dev/null
+++ b/tests/unit/docker-compose-selfhost-data-volume-14910.test.ts
@@ -0,0 +1,45 @@
+// #14910: the self-host compose file must keep the ./data bind mount as the
+// ACTIVE data volume. Switching the default to a named volume would make every
+// existing self-host install boot on an empty volume after pulling the new
+// compose file (looks like data loss), and bin/snapshot-data.sh /
+// bin/restore-data.sh only operate on ./data. The named volume stays available
+// as a commented, opt-in alternative for platforms that hit EACCES.
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const compose = fs.readFileSync(path.join(root, "docker-compose.selfhost.yml"), "utf8");
+const lines = compose.split("\n");
+
+/** Active (uncommented) YAML lines only. */
+const activeLines = lines.filter((line) => !/^\s*#/.test(line));
+
+test("self-host compose keeps the ./data bind mount as the active /app/data volume", () => {
+ const dataMounts = activeLines.filter((line) => /:\/app\/data\s*$/.test(line));
+ assert.deepEqual(
+ dataMounts.map((line) => line.trim()),
+ ["- ./data:/app/data"],
+ "exactly one active /app/data mount, and it must be the ./data bind mount"
+ );
+});
+
+test("the named-volume alternative is documented but stays opt-in (commented)", () => {
+ assert.ok(
+ lines.some((line) => /^\s*#\s*-\s*omniroute-data:\/app\/data\s*$/.test(line)),
+ "the commented omniroute-data alternative must stay discoverable in the compose file"
+ );
+ assert.ok(
+ !activeLines.some((line) => /^\s*omniroute-data:\s*$/.test(line)),
+ "the top-level omniroute-data volume must not be declared by default"
+ );
+});
+
+test("the self-host guide documents the EACCES workaround for /app/data", () => {
+ const guide = fs.readFileSync(path.join(root, "docs/getting-started/SELF_HOST_GUIDE.md"), "utf8");
+ assert.match(guide, /EACCES: permission denied<\/code> writing to \/app\/data/);
+ assert.match(guide, /chown -R 1000:1000 \.\/data/);
+ assert.match(guide, /named volume starts \*\*empty\*\*/);
+});