Correção do erro do erro EACCES: permission denied (#14910)

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.
This commit is contained in:
Matheus de Jesus
2026-10-18 10:12:25 -03:00
committed by GitHub
parent 62a1d20bc3
commit ebbc7bd215
4 changed files with 92 additions and 0 deletions

View File

@@ -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)

View File

@@ -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:

View File

@@ -317,6 +317,37 @@ Raise `OMNIROUTE_MEMORY_MB` in `.env` (e.g. `4096`), then
[Sizing the container](#sizing-the-container).
</details>
<details>
<summary><code>EACCES: permission denied</code> writing to <code>/app/data</code></summary>
`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 .
```
</details>
<details>
<summary>Web-cookie providers (Gemini Web, Claude Turnstile) fail with
<code>Executable doesn't exist at .../ms-playwright/chromium</code></summary>

View File

@@ -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 <code>\/app\/data/);
assert.match(guide, /chown -R 1000:1000 \.\/data/);
assert.match(guide, /named volume starts \*\*empty\*\*/);
});