fix: make Docker container UID/GID configurable

[comzine]

Summary

• Add UID and GID build arguments to Dockerfile and Dockerfile.dev
• Update all docker-compose files to pass these args from environment
• Add documentation for fixing file permission issues

Problem

When mounting host directories into the container, files created by the container are owned by UID 1001 (the hardcoded container user). This causes permission mismatches when the host user has a different UID (e.g., 1000), making it difficult to debug or manually edit files created by Automaker.

Solution

Make the container user's UID/GID configurable via build arguments, defaulting to 1001 for backward compatibility:

UID=$(id -u) GID=$(id -g) docker-compose build

Test plan

• Build image with default UID/GID, verify container user is 1001
• Build image with custom UID/GID, verify container user matches
• Mount host directory, create files in container, verify ownership matches host user

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added "Fixing File Permission Issues" section with rebuild instructions to resolve file ownership conflicts in mounted volumes.
  • Added troubleshooting entry for file permission errors.

• Chores

  • Updated Docker configuration files to support configurable user and group ID values for container environments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request adds configurable build-time UID and GID arguments (defaulting to 1001) across Dockerfiles and docker-compose configurations to enable mapping container user IDs to host user IDs for mounted volumes. User creation commands are updated to use these dynamic values. Documentation is added explaining how to override these arguments during rebuild to fix file permission issues.

Changes

Cohort / File(s)	Summary
Dockerfile modifications Dockerfile, Dockerfile.dev	Introduce ARG UID and ARG GID with defaults of 1001; update groupadd and useradd commands to use -o flag and dynamic UID/GID values for non-root automaker user creation
Docker Compose build args docker-compose.yml, docker-compose.dev.yml, docker-compose.dev-server.yml	Add UID and GID build arguments to service configurations with defaults of 1001; includes explanatory comments about build-time overrides
Documentation docs/docker-isolation.md	Add "Fixing File Permission Issues" section with rebuild workflow using UID=$(id -u) and GID=$(id -g); add troubleshooting table row for file permission errors

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: Add Docker containerization for secure, isolated execution #179 — Modifies Docker-related build configuration and docker-isolation documentation with containerization changes
• refactor: update Dockerfiles for server and UI to streamline dependen… #302 — Updates Dockerfile production stages for non-root user creation, directly related to the UID/GID handling patterns introduced here

Suggested labels

Bug, Testers-Requested

Suggested reviewers

• webdevcody

Poem

🐰 A rabbit digs through Docker files with glee,
UID and GID now dance so wild and free!
No more permission fights in mounted lands,
The automaker user takes matching hands,
File ownership aligned beneath the moon! 🌙

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately and concisely describes the main change: making Docker container UID/GID configurable to fix permission issues.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[gemini-code-assist]

Summary of Changes

Hello @comzine, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves a common pain point in Docker development where file ownership conflicts arise when host directories are mounted into containers. By making the container's user and group IDs configurable, users can now easily synchronize these IDs with their host system, eliminating permission errors and streamlining workflows that involve shared volumes. This enhancement significantly improves the developer experience by ensuring consistent file access and modification capabilities.

Highlights

• Configurable Docker Container User IDs: Introduced UID and GID build arguments in both Dockerfile and Dockerfile.dev, allowing the user ID and group ID of the automaker user within the Docker containers to be configured at build time. These arguments default to 1001 for backward compatibility.
• Docker Compose Integration: Updated all docker-compose files (docker-compose.dev-server.yml, docker-compose.dev.yml, docker-compose.yml) to pass UID and GID environment variables as build arguments to their respective services. This enables matching the container user's IDs with the host user's IDs.
• Documentation for Permission Issues: Added a new section to docs/docker-isolation.md titled 'Fixing File Permission Issues', providing clear instructions on how to rebuild Docker images with the host's UID/GID to resolve common permission mismatches when using mounted volumes. The troubleshooting guide was also updated to reference this new section.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a great improvement for handling file permissions with mounted volumes by making the container's UID/GID configurable. The changes to the docker-compose files and the documentation are well-implemented and clear. My main feedback is to improve the robustness of the user creation logic in the Dockerfile and Dockerfile.dev. The current implementation can fail for common UIDs (like 1000) that conflict with existing users in the base image. I've provided suggestions to handle this gracefully, ensuring the build process is more reliable for developers.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docker-compose.dev-server.yml (1)

20-24: Consider UID shell variable conflict on some systems.

On bash shells, UID is a read-only built-in variable. While this works when using UID=$(id -u) inline (which creates a subshell assignment), users attempting export UID=... will encounter errors. The current inline example in the comment is correct, but this could cause confusion.

This is a minor ergonomic concern—the documented usage pattern works fine.

Dockerfile (1)

87-94: Implementation handles ID collisions correctly.

The use of -o flag is appropriate for this use case where the container user needs to match the host user's UID/GID. This correctly handles potential collisions with existing IDs in the base image (e.g., the node user/group at 1000).

Minor note: the comment mentions GID 1000 collision, but UID 1000 could also collide with the node user in node:22-slim. Consider updating the comment to mention both:

📝 Suggested comment improvement

 # Uses UID/GID build args to match host user for mounted volume permissions
-# Use -o flag to allow non-unique IDs (GID 1000 may already exist as 'node' group)
+# Use -o flag to allow non-unique IDs (UID/GID 1000 may already exist as 'node' user/group)

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 299b838 and aa8caea.

📒 Files selected for processing (6)

• Dockerfile
• Dockerfile.dev
• docker-compose.dev-server.yml
• docker-compose.dev.yml
• docker-compose.yml
• docs/docker-isolation.md

🔇 Additional comments (7)

docker-compose.dev.yml (2)

21-25: LGTM!

Build args correctly propagate UID/GID with appropriate defaults and clear documentation comment.

---

102-104: LGTM!

UI service correctly mirrors the server service's UID/GID configuration, ensuring consistent user mapping across both containers.

Dockerfile.dev (1)

30-42: LGTM! Good use of -o flag for ID flexibility.

The implementation correctly:

• Places ARGs after expensive operations to optimize layer caching
• Uses -o flag to handle existing IDs (e.g., node group at GID 1000)
• Documents the rationale for non-unique IDs

One edge case to be aware of: if a user passes UID=0, the container user would effectively become root. This is likely acceptable since it requires explicit action, but consider documenting this behavior or adding validation if stricter security is needed.

docs/docker-isolation.md (2)

60-73: Clear and helpful documentation.

The section effectively explains the permission mismatch problem and provides a straightforward solution. The commands are correct and the explanation is concise.

---

134-134: LGTM!

Good addition to the troubleshooting table with a clear cross-reference to the detailed section.

docker-compose.yml (1)

31-35: LGTM! Intentional consistency difference noted.

The server service correctly receives UID/GID build args to create the non-root automaker user for mounted volume permissions. The ui service doesn't include these args because it uses the standard nginx:alpine image, which doesn't require user ID matching—it only serves static files and doesn't mount host volumes.

This design is correct: only services that create custom non-root users for volume access need the UID/GID args.

Dockerfile (1)

62-65: LGTM!

The build arguments are well-documented with sensible defaults (1001) that maintain backward compatibility. The inline comment clearly shows how to override at build time.