mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-02 02:07:25 +08:00
Devin Foley
dd1a7f5290
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Docker image persists all instance state (project checkouts, worktrees, run logs, uploads) under `PAPERCLIP_HOME`, and deployments mount a volume there for durability > - The entrypoint starts as root and drops privileges to the `node` user, but it fixes `PAPERCLIP_HOME` ownership only when it remaps the user's UID/GID > - A freshly mounted volume arrives root-owned and shadows the image's build-time `chown`, so a default-UID boot drops privileges onto an unwritable home and the server crashes on its first `mkdir` > - This pull request makes the entrypoint probe the home's ownership and chown whenever it does not match the runtime user, before the privilege drop > - The benefit is that the image works out of the box on any platform-managed volume, with the common already-correct boot staying chown-free ## Linked Issues or Issue Description No public issue exists — describing the bug inline (per the bug report template). **What happened?** Running the image with a freshly created volume mounted at `/paperclip` (a Docker named volume, a Kubernetes PV, or any platform-managed volume) and the default `USER_UID`/`USER_GID` crashes on boot: `Error: EACCES: permission denied, mkdir '/paperclip/instances/default/logs'`. **Expected behavior** The container boots and initializes its instance tree on the mounted volume, exactly as it does when `/paperclip` is the image's own (build-time chowned) directory. **Steps to reproduce** 1. `docker volume create paperclip-data` 2. `docker run -v paperclip-data:/paperclip ghcr.io/paperclipai/paperclip:<any current tag>` 3. Observe the EACCES crash on the first `mkdir` under `/paperclip`. **Root cause** `scripts/docker-entrypoint.sh` chowns `/paperclip` only inside its UID/GID remap branch (`changed=1`). A fresh volume mount is root-owned and shadows the image's build-time `chown node:node /paperclip`; with the default 1000:1000 no remap happens, so no chown happens, and `gosu node` drops onto an unwritable home. **Paperclip version or commit:** reproduces on `master` and any published image. **Deployment mode:** any; observed on managed-cloud volume mounts and reproducible with plain Docker named volumes. **Installation method:** Docker image (`ghcr.io/paperclipai/paperclip`). **Related PRs (dedup search):** no open or merged PR touches the entrypoint ownership logic; the entrypoint's privilege-handling tests were added previously and this extends them. No duplicate found. ## What Changed - `scripts/docker-entrypoint.sh`: the remap-conditional `chown` is replaced by an ownership probe — after any UID/GID remap, the entrypoint stats `PAPERCLIP_HOME` (default `/paperclip`) and runs `chown -R node:node` only when the owner does not match the runtime user, before `exec gosu node`. Covers fresh root-owned mounts and trees written under a previous UID mapping; the already-correct boot performs no chown. The unprivileged (non-root start) branch is unchanged. - `server/src/__tests__/docker-entrypoint.test.ts`: `stat` stub added to the harness; new cases for the fresh root-owned mount with default UID/GID and for `PAPERCLIP_HOME`-relative probing; the remap case now models the post-remap ownership mismatch. ## Verification - `pnpm vitest run server/src/__tests__/docker-entrypoint.test.ts` — 7 passed (5 existing behaviors unchanged, 2 new). - Live on a managed deployment: a container that crash-looped with the EACCES above boots cleanly once the home is chowned before the drop (the same effect this entrypoint change produces; forced there by a UID remap as an interim workaround). ## Risks - Low. Behavior changes only for boots where `PAPERCLIP_HOME` exists with mismatched ownership — exactly the boots that crash today. `chown -R` on a large previously-mismatched tree adds one-time boot latency; correctly-owned homes skip it entirely. Kubernetes restricted / OpenShift non-root starts keep the existing exec-directly path untouched. ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic; Claude Code CLI with extended thinking and tool use; tests executed locally via Vitest). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above (no duplicates; extends the existing entrypoint privilege tests) - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
49 lines
2.1 KiB
Bash
49 lines
2.1 KiB
Bash
#!/bin/sh
|
|
set -e
|
|
|
|
# Capture runtime UID/GID from environment variables, defaulting to 1000
|
|
PUID=${USER_UID:-1000}
|
|
PGID=${USER_GID:-1000}
|
|
|
|
# Without root we can neither remap the node user (usermod/groupmod/chown)
|
|
# nor switch users (gosu needs CAP_SETUID/CAP_SETGID), so exec directly.
|
|
# This covers Kubernetes restricted PodSecurity (runAsNonRoot + runAsUser)
|
|
# as well as platforms that assign arbitrary UIDs (e.g. OpenShift); for the
|
|
# latter a UID/GID mismatch is unfixable here, so warn instead of letting
|
|
# usermod fail cryptically and keep volume-permission issues diagnosable.
|
|
if [ "$(id -u)" -ne 0 ]; then
|
|
if [ "$(id -u)" -ne "$PUID" ] || [ "$(id -g)" -ne "$PGID" ]; then
|
|
echo "docker-entrypoint.sh: running unprivileged as $(id -u):$(id -g); cannot remap to requested ${PUID}:${PGID}" >&2
|
|
fi
|
|
exec "$@"
|
|
fi
|
|
|
|
# Adjust the node user's UID/GID if they differ from the runtime request
|
|
if [ "$(id -u node)" -ne "$PUID" ]; then
|
|
echo "Updating node UID to $PUID"
|
|
usermod -o -u "$PUID" node
|
|
fi
|
|
|
|
if [ "$(id -g node)" -ne "$PGID" ]; then
|
|
echo "Updating node GID to $PGID"
|
|
groupmod -o -g "$PGID" node
|
|
usermod -g "$PGID" node
|
|
fi
|
|
|
|
# Ensure the app home is owned by the runtime user BEFORE dropping
|
|
# privileges -- not only after a UID/GID remap. A freshly mounted volume
|
|
# (Docker named volume, Railway volume, Kubernetes PV) arrives root-owned
|
|
# and shadows the image's build-time chown, so with the default UID the old
|
|
# remap-only condition dropped privileges onto an unwritable home and the
|
|
# server crashed on its first mkdir. The probe is a first-mismatch find
|
|
# over the WHOLE tree (uid and gid): a root-owned mount or descendant
|
|
# (init containers, backup restores, files written before a remap) is
|
|
# found immediately and repaired recursively, a GID-only remap is caught,
|
|
# and a fully-correct tree costs one metadata-only walk with no chown.
|
|
home_dir="${PAPERCLIP_HOME:-/paperclip}"
|
|
if [ -d "$home_dir" ] && [ -n "$(find "$home_dir" \( ! -user node -o ! -group node \) -print -quit 2>/dev/null)" ]; then
|
|
chown -R node:node "$home_dir"
|
|
fi
|
|
|
|
exec gosu node "$@"
|