Description

The published image does not boot under a rootful Docker daemon (Docker
Desktop on Windows/macOS, or plain Docker on Linux): supervisord fails to spawn
its children and neither the backend nor the frontend starts. The container
stays "up" but :8001 and :3782 never respond.

Root cause

The entrypoint dropped supervisord itself to the unprivileged deeptutor
user (UID 1000) via exec gosu deeptutor /usr/bin/supervisord. Supervisord
logs its programs to /dev/fd/1,2 (the container's stdout/stderr pipes).
Under a rootful daemon those pipes are owned by root, so after the gosu
drop UID 1000 cannot open them:

CRIT could not write pidfile /var/run/supervisord.pid
INFO spawnerr: unknown error making dispatchers for 'backend': EACCES
INFO spawnerr: unknown error making dispatchers for 'frontend': EACCES
INFO gave up: backend entered FATAL state, too many start retries
INFO gave up: frontend entered FATAL state, too many start retries

The gosu approach only worked under rootless podman (userns_mode: keep-id), where UID 1000 is mapped to the host user that owns those FDs.

Relation to #580 / #581

Issue #580 and PR #581 address a different, cosmetic symptom of the same
gosu hardening (PR #577): under rootless podman the pidfile CRIT appears
in the log, but children still spawn and the stack is fully functional. Their
fix (/var/run tmpfs mode=1777) is correct for that case.

This PR addresses the fatal case: under a rootful daemon the children
never spawn at all because /dev/fd/1,2 — not the pidfile — are
inaccessible to UID 1000. Changing the tmpfs mode does not help here; the
file descriptors are inherited from the container runtime, not a tmpfs path.

Fix

Run supervisord as root and drop only the app processes to deeptutor
via supervisord's own user= directive — applied to both the production and
development supervisord configs:

• entrypoint: exec /usr/bin/supervisord … (no gosu prefix)
• [supervisord] section: user=root
• [program:backend] and [program:frontend]: user=deeptutor

Root opens the log FDs and pidfile, then supervisord setuids each child —
so the backend and frontend processes stay non-root in both runtimes,
preserving the security goal of PR #577.

The dev stage also chowns /app/web/.next so next dev can write its
build cache as the unprivileged user.

Related Issues

• Related to [Bug]: supervisord CRIT "could not write pidfile /var/run/supervisord.pid" on rootless podman + keep-id + RO rootfs #580 (same root: gosu-based priv-drop from PR feat(deploy): harden image for rootless podman with read-only rootfs #577; different
  symptom and runtime)
• Related to fix(deploy): /var/run tmpfs mode 0755 → 1777 so supervisord can write pidfile as UID 1000 #581 (complementary fix for rootless podman; this PR fixes
  rootful Docker)

Module(s) Affected

• agents
• api
• config
• core
• knowledge
• logging
• services
• tools
• utils
• web (Frontend)
• docs (Documentation)
• scripts
• tests
• Other: Docker (Dockerfile / container runtime)

Checklist

• I have read and followed the contribution guidelines.
• My code follows the project's coding standards.
• I have run pre-commit run --all-files and fixed any issues.
• I have added relevant tests for my changes.
• I have updated the documentation (if necessary).
• My changes do not introduce any new security vulnerabilities.

Additional Notes

Reproduction (released image, no overrides needed):

docker run ghcr.io/hkuds/deeptutor:latest
# CRIT could not write pidfile /var/run/supervisord.pid
# INFO spawnerr: unknown error making dispatchers for 'backend': EACCES
# INFO spawnerr: unknown error making dispatchers for 'frontend': EACCES
# INFO gave up: backend entered FATAL state, too many start retries

Verification (rebuilt --target production, plain docker run, no overrides):

INFO supervisord started with pid 1
INFO spawned: 'backend' with pid 18
INFO spawned: 'frontend' with pid 19
INFO success: backend entered RUNNING state
▲ Next.js 16.2.3  ✓ Ready

GET /api/v1/auth/status → 200, GET / → 200. App processes confirmed
running as deeptutor (UID 1000) via the user= directive.

Tests: added test_supervisord_runs_as_root_with_unprivileged_children in
tests/scripts/test_docker_compose.py. Parses the Dockerfile and asserts: (1)
no gosu deeptutor before supervisord, (2) every [program:*] declares
user=deeptutor. Runs without a Docker build. pytest -q tests/scripts/test_docker_compose.py → 6 passed.

Open to any feedback — if this doesn't fit the project's direction, no worries at all, happy to discuss and rework as needed.