From ebbc7bd215def58a41ace35c3ea2d45fcf7c3a84 Mon Sep 17 00:00:00 2001 From: Matheus de Jesus Date: Sun, 18 Oct 2026 10:12:25 -0300 Subject: [PATCH] =?UTF-8?q?Corre=C3=A7=C3=A3o=20do=20erro=20do=20erro=20EA?= =?UTF-8?q?CCES:=20permission=20denied=20(#14910)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merged via /merge-batch (2026-10-18, uplift round). Thanks @matheusgcdj for the idea and the original implementation! Maintainer rework on top of the contributor's commits (owner-approved uplift; default runtime behavior unchanged unless noted, every behavior change behind its own default-off feature flag): - fix(docker): keep the ./data bind mount active in the self-host compose Evidence: validated on a combined board of the 34 reworked PRs over release/v3.8.52 (typecheck core/open-sse/API, complexity + cognitive-complexity within baseline, boundary 774/774, dead-code, i18n new-key coverage, changelog-integrity, docs-sync, docs-counts, 894 focused node tests + 41 UI + 104 autoCombo green), then re-validated on the current tip: unit pass=3 fail=0 and boundary/changelog/complexity/file-size/skills gates green. Remaining CI reds are the inherited base-red #15306. --- .../fixes/14910-selfhost-eacces-docs.md | 1 + docker-compose.selfhost.yml | 15 +++++++ docs/getting-started/SELF_HOST_GUIDE.md | 31 +++++++++++++ ...compose-selfhost-data-volume-14910.test.ts | 45 +++++++++++++++++++ 4 files changed, 92 insertions(+) create mode 100644 changelog.d/fixes/14910-selfhost-eacces-docs.md create mode 100644 tests/unit/docker-compose-selfhost-data-volume-14910.test.ts 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\*\*/); +});