feat(docker): run container as host user with bind-mounted workspace by chriswritescode-dev · Pull Request #328 · chriswritescode-dev/opencode-manager

chriswritescode-dev · 2026-07-28T15:06:25Z

Summary

Adds support for running the Manager container as a host-matched user so a bind-mounted workspace stays usable from the host without root.

New scripts/lib/container-user.sh aligns the in-image node account's uid/gid to PUID/PGID at startup, with conflict detection and a workspace-ownership warning before chown.
docker-entrypoint.sh sources the helper, aligns the container user, and re-chowns /app when ids change.
docker-compose.yml exposes PUID/PGID (default 1000) and binds /workspace to OCM_WORKSPACE_HOST_PATH when set (falls back to the named volume).
.env.example documents the new OCM_WORKSPACE_HOST_PATH / PUID / PGID knobs.
New tests cover the container-user alignment script and docker-compose config; docs/configuration/docker.md and docs/getting-started/installation.md document the host-workspace flow.

Type of Change

Bug fix
New feature
Refactor
Documentation

Checklist

Code follows project style (no comments, named imports)
TypeScript types are properly defined
Tests added/updated (80% coverage target)
pnpm lint passes locally
pnpm typecheck passes locally

Summary by CodeRabbit

New Features
- Docker deployments can now map /workspace to a host directory using OCM_WORKSPACE_HOST_PATH.
- Container file ownership can be configured with PUID/PGID (default 1000), with automatic alignment at startup.
- Startup warns about existing workspace ownership mismatches and avoids/halts on UID/GID conflicts; /app ownership is only re-aligned when needed.
Documentation
- Updated Docker Compose and onboarding docs with PUID/PGID, workspace bind-mount/migration steps, and safer permission guidance.
Tests
- Added coverage for container user/group alignment, entrypoint behavior, and Docker/workspace configuration consistency.

coderabbitai · 2026-07-28T15:06:54Z

Warning

Review limit reached

@chriswritescode-dev, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 35 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7da2cf52-e249-45c1-8928-c099646fa15d

📥 Commits

Reviewing files that changed from the base of the PR and between 3ad90e5 and 026e8f1.

📒 Files selected for processing (4)

backend/test/scripts/container-user.test.ts
docs/getting-started/installation.md
scripts/docker-entrypoint.sh
scripts/lib/container-user.sh

📝 Walkthrough

Walkthrough

Docker startup now aligns the container’s node account with configurable host IDs, supports host-bound workspace mounts, warns before ownership rewrites, and documents and tests named-volume migration.

Changes

Docker workspace ownership

Layer / File(s)	Summary
Container user alignment `scripts/lib/container-user.sh`, `backend/test/scripts/container-user.test.ts`	Adds validated PUID/PGID resolution, collision checks, account alignment, change flags, workspace ownership warnings, and comprehensive shell tests.
Startup and image wiring `Dockerfile`, `scripts/docker-entrypoint.sh`, `backend/test/scripts/docker-config.test.ts`	Installs and sources the user-alignment library, aborts on alignment failure, warns before chowning, and conditionally realigns `/app`.
Workspace mount configuration `docker-compose.yml`, `.env.example`	Adds default PUID/PGID settings and makes `/workspace` selectable through `OCM_WORKSPACE_HOST_PATH`.
Documentation and migration validation `backend/test/helpers/repo-root.ts`, `docs/configuration/docker.md`, `docs/getting-started/installation.md`, `backend/test/scripts/docker-config.test.ts`	Documents host access and guarded named-volume migration, updates compose examples, adds repository-root test support, and tests configuration consistency and migration behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DockerEntrypoint
  participant ContainerUserLibrary
  participant AccountDatabase
  participant Workspace
  DockerEntrypoint->>ContainerUserLibrary: align_container_user node
  ContainerUserLibrary->>AccountDatabase: validate and align PUID/PGID
  DockerEntrypoint->>Workspace: warn_if_workspace_owner_differs
  DockerEntrypoint->>Workspace: chown workspace and app paths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly summarizes the main Docker user-mapping and bind-mounted workspace change.
Description check	✅ Passed	Description follows the template and includes summary, change type, and checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/docker-host-workspace

_{Comment @coderabbitai help to get the list of available commands.}

…from environment values' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/lib/container-user.sh`:
- Around line 83-95: Update warn_if_workspace_owner_differs to accept and
compare the workspace’s group ID against the target GID in addition to the
existing UID check, and include both ownership values in the warning when either
differs. Update the scripts/docker-entrypoint.sh call site to pass
OCM_TARGET_GID, and adjust existing tests to cover matching and mismatched GIDs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 167f49a7-9a4f-4ece-a753-01c0920870ea

📥 Commits

Reviewing files that changed from the base of the PR and between a73ac19 and 4cdd3d7.

📒 Files selected for processing (10)

.env.example
Dockerfile
backend/test/helpers/repo-root.ts
backend/test/scripts/container-user.test.ts
backend/test/scripts/docker-config.test.ts
docker-compose.yml
docs/configuration/docker.md
docs/getting-started/installation.md
scripts/docker-entrypoint.sh
scripts/lib/container-user.sh

…tests

+  spawnSync('bash', ['-c', 'set -e\nsource "$1"\neval "$2"', '--', libPath, snippet], {
+    encoding: 'utf-8',
+    env: {
+      ...process.env,
+      PUID: '',
+      PGID: '',
+      PATH: `${stubDir}:${process.env.PATH}`,
+      OCM_STUB_LOG: logPath,
+      ...env,
+    },
+  })


feat(docker): run container as host user with bind-mounted workspace

4cdd3d7

github-advanced-security AI found potential problems Jul 28, 2026

View reviewed changes

Comment thread backend/test/scripts/container-user.test.ts Fixed

Potential fix for pull request finding 'CodeQL / Shell command built …

3ad90e5

…from environment values' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

github-advanced-security AI found potential problems Jul 28, 2026

View reviewed changes

Comment thread backend/test/scripts/container-user.test.ts Fixed

coderabbitai Bot reviewed Jul 28, 2026

View reviewed changes

Comment thread scripts/lib/container-user.sh

CS added 2 commits July 28, 2026 11:21

fix(docker): warn on workspace gid mismatch as well as uid

b3394a9

fix(docker): eval snippet passed as positional arg in container-user …

8f9b2d5

…tests

github-advanced-security AI found potential problems Jul 28, 2026

View reviewed changes

docs(installation): drop stale host repository access reference

026e8f1

chriswritescode-dev merged commit 6c63539 into main Jul 28, 2026
1 of 2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docker): run container as host user with bind-mounted workspace - #328

feat(docker): run container as host user with bind-mounted workspace#328
chriswritescode-dev merged 5 commits into
mainfrom
feat/docker-host-workspace

chriswritescode-dev commented Jul 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

chriswritescode-dev commented Jul 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chriswritescode-dev commented Jul 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading