Machine.save intentionally invalidates the process cache so config edits are visible immediately. Keep a local instance through host refresh, sanitation, and file reconciliation, then publish the completed instance to the cache. Explain why invalidation must remain and why reading the global after save can return None.
Add a real CLI regression that ages persisted machine rows, runs archivebox status, and verifies successful refresh without changing machine identities. Confirmed failing before the fix; 13 targeted tests and Ruff checks pass.
Fixes#1876.
## Root cause
`restart: unless-stopped` repeated the startup failure; it did not
create it. The Docker entrypoint created required directories as
container root first and swallowed failures before checking them as the
application user. On NFS `root_squash` and filesystems with synthetic
ownership, root can be unable to create or change a path that the
intended non-root identity can use. That led to the reported `cannot
write to /data/logs` failure.
## What changed
- Honor Docker `PUID`/`PGID` when supplied, otherwise retain
collection-owner detection and the `911:911` fallback. ArchiveBox and
Chrome remain non-root; `PGID=0` remains supported.
- Check and create required paths as the final non-root identity first.
If a collection path is inaccessible, repair only that path's own
metadata as root and recheck. Runtime/cache trees can receive one-time
recursive repair only after their access check fails.
- Use real create/delete probes for logs, archive output, and the Chrome
profile. Writable NFS/synthetic-permission mounts avoid repeated
metadata operations.
- Never recursively scan or change `data/archive`, regardless of byte
size. The cost is driven by file count and filesystem latency, so even
measuring a 2 GiB threshold would be undesirable at startup.
- Clean up only known browser lock files at persona profile roots,
without traversing large profiles.
- Keep the shipped Compose restart policy, and test fresh
initialization, non-root execution, restarts, root-squashed NFS, and
explicit `PGID=0` with real containers.
- Wait for a newly started Sonic worker to answer on its search port
before querying. An explicit `SONIC_BINARY` (absolute path or relative
executable name) now takes precedence over a persisted Machine config
value before plugin hydration; absolute paths are pinned in Supervisor
rather than routed through a mutable `lib/env/bin/sonic` projection.
Sonic releases have incompatible on-disk KV encodings. A real CLI
regression test checks both override forms, the generated Supervisor
command, and the listener guard. Backend failures now include child
stderr and the Sonic worker log in test output.
## Verification
- `uv run pytest archivebox/tests/test_permissions.py -q` (15 passed)
- `bash -n bin/docker_entrypoint.sh bin/validate_docker_uid_gid.sh`
- Targeted pre-commit hooks for all changed files
- Real Docker checks for distinct PUID/PGID, explicit `PGID=0`, PUID 0
fallback, shallow collection repair, and unchanged nested archive
ownership
- Fresh Compose initialization and non-root writes succeeded; a restart
returned healthy
- Five warm starts on the same Docker Desktop host: previous entrypoint
1.48s, changed entrypoint 1.50s (within run-to-run noise)
- Live Sonic search matrix passed locally on Linux ARM and in native
x86_64 CI
- Real CLI regressions for absolute and relative Sonic binary overrides
over persisted config passed locally on Linux ARM
- Full CI workflow passed on the final PR commit
Nick Sweeting