From 9d1f8d0661b270335d3993e9a3317adbc4b47d57 Mon Sep 17 00:00:00 2001 From: Vishal Jain Date: Wed, 18 Jun 2025 13:54:58 +0100 Subject: [PATCH] Add git user configuration support Add required git user configuration to enable commits from within the container. This change ensures proper attribution of git commits made inside the container by: - Adding GIT_USER_NAME and GIT_USER_EMAIL to .env.example - Configuring git user globally during Docker build - Adding documentation for git configuration requirements - Updating README with clearer setup instructions and requirements The configuration is now required as part of the initial setup to prevent issues with unattributed commits when using git inside the container. --- .env.example | 4 ++ Dockerfile | 12 ++++++ README.md | 35 +++++++--------- commit_diff_summary.txt | 13 ++++++ plan.md | 84 +++++++++++++++++++++++++++++++++++++ scripts/startup.sh | 7 ++++ task_log.md | 82 ++++++++++++++++++++++++++++++++++++ templates/.claude/CLAUDE.md | 50 ++++++++++++++++++---- 8 files changed, 261 insertions(+), 26 deletions(-) create mode 100644 commit_diff_summary.txt create mode 100644 plan.md create mode 100644 task_log.md diff --git a/.env.example b/.env.example index e1e10a4..2255671 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,10 @@ # Copy this file to .env and fill in your credentials # The .env file will be baked into the Docker image during build +# Required: Git configuration for commits made inside the container +GIT_USER_NAME=Your Name +GIT_USER_EMAIL=your.email@example.com + # Optional: Twilio credentials for SMS notifications TWILIO_ACCOUNT_SID=your_twilio_account_sid TWILIO_AUTH_TOKEN=your_twilio_auth_token diff --git a/Dockerfile b/Dockerfile index cfd0b2d..973eb6d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -82,6 +82,18 @@ RUN bash -c 'source /app/.env && \ echo "No Twilio credentials found, skipping MCP configuration"; \ fi' +# Configure git user during build +RUN bash -c 'source /app/.env && \ + if [ -n "$GIT_USER_NAME" ] && [ -n "$GIT_USER_EMAIL" ]; then \ + echo "Configuring git user: $GIT_USER_NAME <$GIT_USER_EMAIL>" && \ + git config --global user.name "$GIT_USER_NAME" && \ + git config --global user.email "$GIT_USER_EMAIL" && \ + echo "Git configuration complete"; \ + else \ + echo "Warning: GIT_USER_NAME and GIT_USER_EMAIL not set in .env"; \ + echo "Git commits will require manual configuration"; \ + fi' + # Set working directory to mounted volume WORKDIR /workspace diff --git a/README.md b/README.md index ad92ed5..1cf7497 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,13 @@ ls ~/.claude.json ~/.claude/ - **Docker Desktop**: https://docs.docker.com/get-docker/ - Ensure Docker daemon is running before proceeding -### 3. Twilio Account (Optional - for SMS notifications) +### 3. Git Configuration (Required) +For any git commits made inside the container, you'll need to provide: +- Your name and email address +- These will be configured in the `.env` file +- Used for `git config --global user.name` and `git config --global user.email` + +### 4. Twilio Account (Optional - for SMS notifications) If you want SMS notifications when tasks complete: - Create free trial account: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account - Get your Account SID and Auth Token from the Twilio Console @@ -69,6 +75,10 @@ claude-docker # Required ANTHROPIC_API_KEY=your_anthropic_key +# Required - Git configuration for commits +GIT_USER_NAME=Your Name +GIT_USER_EMAIL=your.email@example.com + # Optional - SMS notifications TWILIO_ACCOUNT_SID=your_twilio_sid TWILIO_AUTH_TOKEN=your_twilio_auth_token @@ -179,8 +189,7 @@ This workflow gives you: ### 🐳 Clean Environment - Each session runs in fresh Docker container -- Container auto-removes on exit -- No system pollution or conflicts +- Only current working directory mounted (along with conda directories specified in `.env`). ## How It Works @@ -194,7 +203,7 @@ This workflow gives you: ``` claude-docker/ -├── Dockerfile # Main container definition +├── Dockerfile # Main container definition ├── .env.example # Template for environment variables ├── scripts/ │ ├── claude-docker.sh # Wrapper script for container @@ -202,7 +211,7 @@ claude-docker/ │ └── startup.sh # Container startup script └── templates/ └── .claude/ - └── CLAUDE.md # Claude behavior instructions + └── CLAUDE.md # Claude behavior instructions ``` ## Configuration @@ -242,10 +251,10 @@ For custom conda installations (common in academic/lab environments), add these ```bash # Main conda installation -CONDA_PREFIX=/vol/biomedic3/username/miniconda3 +CONDA_PREFIX=/vol/lab/username/miniconda3 # Additional conda directories (space-separated) -CONDA_EXTRA_DIRS="/vol/biomedic3/username/.conda/envs /vol/biomedic3/username/conda_envs /vol/biomedic3/username/.conda/pkgs /vol/biomedic3/username/conda_pkgs" +CONDA_EXTRA_DIRS="/vol/lab/username/.conda/envs /vol/lab/username/conda_envs /vol/lab/username/.conda/pkgs /vol/lab/username/conda_pkgs" ``` **How it works:** @@ -270,20 +279,8 @@ SYSTEM_PACKAGES="libopenslide0" SYSTEM_PACKAGES="libopenslide0 libgdal-dev libproj-dev libopencv-dev" ``` -**Common packages:** -- `libopenslide0` - OpenSlide for whole slide imaging -- `libgdal-dev` - GDAL for geospatial data -- `libproj-dev` - PROJ for cartographic projections -- `libopencv-dev` - OpenCV for computer vision -- `libfftw3-dev` - FFTW for fast Fourier transforms - **Note:** Adding system packages requires rebuilding the Docker image (`docker rmi claude-docker:latest`). -## Requirements - -- Docker installed and running -- Anthropic API key (or Claude subscription) -- (Optional) Twilio account with API Key/Secret for SMS notifications ## Next Steps diff --git a/commit_diff_summary.txt b/commit_diff_summary.txt new file mode 100644 index 0000000..df43967 --- /dev/null +++ b/commit_diff_summary.txt @@ -0,0 +1,13 @@ +Write a commit message for the changes in the following git diff: +Follow the following instructions when writing the commit message: +Subject line: Max 50 chars, imperative mood, capitalized, no period +Skip a line between subject and body +Body text: Wrap at 72 chars per line +Explain what and why, not how +Reference issue numbers when applicable +Format: (): + +=== GIT DIFF SUMMARY FOR COMMIT === + + +=== END OF DIFF SUMMARY === diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..6bfa406 --- /dev/null +++ b/plan.md @@ -0,0 +1,84 @@ +# README Update and Repository Preparation Plan + +## Objective +Update the claude-docker README to be production-ready for public release, with clear setup instructions, proper attribution, and comparison to Anthropic's devcontainer implementation. + +## Current Script Inventory (Post-Cleanup) +Based on our recent pruning, these are the active scripts: +- **claude-docker.sh**: Main wrapper script that handles Docker container lifecycle, mounts projects, copies templates +- **install.sh**: One-time installation script that builds Docker image and creates system-wide alias +- **startup.sh**: Container entrypoint that loads environment and starts Claude Code with MCP + +## Tasks + +### 1. Research Phase +- Fetch and analyze Anthropic's .devcontainer implementation files: + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/devcontainer.json + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/Dockerfile + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/init-firewall.sh +- Understand their approach to: + - Authentication handling + - Firewall/security implementation + - Environment setup + - Persistence mechanisms + +### 2. README Prerequisites Update +- Add clear warning that Claude Code must be pre-authenticated on host +- Link to official Claude Code installation docs: https://docs.anthropic.com/en/docs/claude-code +- Link to Twilio setup documentation +- Make it ultra-clear what needs to be done BEFORE using claude-docker + +### 3. Add Comparison Section +Create "How This Differs from Anthropic's DevContainer" section highlighting: +- **Authentication Persistence**: Our approach vs theirs +- **Conda Environment Management**: Full conda mounting and path preservation +- **Project Mounting**: Plug-and-play for any project directory +- **Twilio MCP Integration**: Built-in SMS notifications +- **Use Case**: Standalone tool vs VSCode-integrated development + +### 4. Simplify Setup Instructions +Transform current setup into numbered CLI commands: +```bash +1. git clone https://github.com/VishalJ99/claude-docker.git +2. cd claude-docker +3. cp .env.example .env +4. nano .env # Add your API keys +5. ./scripts/install.sh +6. claude-docker # Run from any project +``` + +### 5. Add Proper Attribution +- Link to Twilio MCP server we use: @yiyang.1i/sms-mcp-server +- Credit Anthropic's claude-code project +- Add links to all external dependencies + +### 6. Remove Legacy Content +- Remove references to setup-env.sh (already deleted) +- Update directory structure section to reflect current scripts +- Update any stale examples + + +## Key Differentiators to Emphasize + +1. **Standalone Docker** vs DevContainer (VSCode-specific) +2. **Persistent Authentication** - login once, use everywhere +3. **Conda Integration** - preserves conda environments and works with custom env and pkg dirs +4. **SMS Notifications** - autonomous execution with status updates +5. **Zero Configuration Per Project** - just run claude-docker +6. **Detach/Reattach Workflow** - long-running sessions + +## Links to Include + +- Claude Code Setup: https://docs.anthropic.com/en/docs/claude-code +- Twilio Account Setup: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account +- Docker Installation: https://docs.docker.com/get-docker/ +- Our Repository: https://github.com/VishalJ99/claude-docker +- Anthropic's DevContainer: https://github.com/anthropics/claude-code/tree/main/.devcontainer + +## Success Criteria +- New user can go from zero to running claude-docker in < 5 minutes +- Clear understanding of what this tool provides vs alternatives +- All external dependencies properly attributed +- No legacy or confusing content remains +- Prerequisites are crystal clear +- Directory structure accurately reflects current codebase \ No newline at end of file diff --git a/scripts/startup.sh b/scripts/startup.sh index df8e253..5fdd3aa 100755 --- a/scripts/startup.sh +++ b/scripts/startup.sh @@ -34,6 +34,13 @@ else echo "No Twilio credentials found - SMS notifications disabled" fi +# Configure git for the mounted workspace +if [ -n "$GIT_USER_NAME" ] && [ -n "$GIT_USER_EMAIL" ]; then + echo "✓ Configuring git: $GIT_USER_NAME <$GIT_USER_EMAIL>" + git config --global user.name "$GIT_USER_NAME" + git config --global user.email "$GIT_USER_EMAIL" +fi + # Start Claude Code with permissions bypass echo "Starting Claude Code..." exec claude --dangerously-skip-permissions "$@" \ No newline at end of file diff --git a/task_log.md b/task_log.md new file mode 100644 index 0000000..733c68c --- /dev/null +++ b/task_log.md @@ -0,0 +1,82 @@ +# Task Execution Log + +## Task Overview +Update the claude-docker README to be production-ready for public release, with clear setup instructions, proper attribution, and comparison to Anthropic's devcontainer implementation. + +## Implementation Overview +This task involves: +1. Researching Anthropic's .devcontainer implementation +2. Updating README prerequisites with clear warnings and links +3. Adding comparison section between our approach and Anthropic's +4. Simplifying setup instructions into numbered CLI commands +5. Adding proper attribution for all dependencies +6. Removing legacy content and updating directory structure + +## Checklist +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze devcontainer.json +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze Dockerfile +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze init-firewall.sh +- [x] Create task_log.md to document execution process +- [x] Update README Prerequisites section with clear warnings and links +- [x] Add 'How This Differs from Anthropic's DevContainer' comparison section +- [x] Simplify Setup Instructions into numbered CLI commands +- [x] Add Proper Attribution section with all external dependencies +- [x] Remove legacy content and update directory structure +- [x] Verify README completeness against success criteria +- [x] Test README instructions for clarity and accuracy +- [x] Commit changes with appropriate message +- [ ] Send completion notification via Twilio + +## Assumptions Made +- The README.md file exists in the project root +- The current script inventory mentioned in plan.md is accurate +- External URLs for Anthropic's devcontainer files are accessible + +## Problems Encountered +- Research phase completed successfully. Key findings: + - Anthropic's devcontainer uses a restrictive firewall approach + - They use VSCode-specific devcontainer.json configuration + - Authentication is handled differently (not persisted like ours) + - Their approach is more security-focused but less flexible + +## Verification Against Success Criteria +✅ New user can go from zero to running claude-docker in < 5 minutes + - Simplified to 4 clear command blocks + - All prerequisites clearly stated with links + +✅ Clear understanding of what this tool provides vs alternatives + - Detailed comparison table with Anthropic's DevContainer + - Clear "When to Use Each" section + +✅ All external dependencies properly attributed + - New Attribution section with all dependencies + - Links to Claude Code, Twilio MCP, Docker, and references + +✅ No legacy or confusing content remains + - Verified no references to deleted scripts + - Directory structure is accurate + +✅ Prerequisites are crystal clear + - Dedicated Prerequisites section with warnings + - Links to all setup documentation + +✅ Directory structure accurately reflects current codebase + - Shows only the 3 active scripts + - No mention of removed scripts + +## Deviations from Plan +- Found that scratchpad.md template referenced in scripts doesn't exist +- Updated README to remove scratchpad.md references and corrected directory structure +- Fixed inaccuracies discovered during testing phase + +## Final Status +SUCCESS - All tasks completed successfully + +Summary of changes: +- Enhanced README with comprehensive prerequisites section +- Added detailed comparison with Anthropic's DevContainer approach +- Simplified setup to 4 clear CLI commands +- Added proper attribution for all dependencies +- Fixed directory structure inaccuracies +- Removed references to non-existent scratchpad.md +- Committed changes with hash: 7b50165 \ No newline at end of file diff --git a/templates/.claude/CLAUDE.md b/templates/.claude/CLAUDE.md index f33ccab..dc69938 100644 --- a/templates/.claude/CLAUDE.md +++ b/templates/.claude/CLAUDE.md @@ -27,9 +27,15 @@ If ANY Twilio variables are missing, skip SMS notifications and continue task ex ## Required Workflow ### 1. Task Initialization -- **FIRST**: Check for `claude.md` in project root - if exists, read it to understand project-specific context and requirements -- Read and understand the complete specification/plan written in `plan.md`. -- **ULTRA THINK**: ultrathink about the execution approach - analyse potential pitfalls, complications, technical challenges, and validate that your planned approach will actually work and properly implement the specification. +- **FIRST**: Set up Git branch: + ```bash + git stash -u # Stash any uncommitted changes including untracked files + git checkout -b claude-docker || git checkout claude-docker # Create branch or switch to it + git stash apply # Apply stashed changes if any + ``` +- Check for `claude.md` in project root - if exists, read it to understand project-specific context and requirements +- Read and understand the complete specification/plan written in `plan.md` +- **ULTRA-THINK**: Analyze potential pitfalls, complications, technical challenges, and validate that your planned approach will actually work and properly implement the specification - Create a detailed checklist using TodoWrite breaking down all steps - Create `task_log.md` in project root to document the execution process - Begin systematic execution @@ -89,17 +95,46 @@ Upon successful task completion: 3. Complete final documentation in `task_log.md` 4. Make git commits following the commit message rules below 5. If Twilio is configured (all env vars present), send completion message to `$TWILIO_TO_NUMBER` with summary +6. Completion msg MUST include a remote url link. See below for generation instructions. + +### Constructing Remote Git URLs +When you need to create GitHub commit URLs, use these commands to extract repository information: +```bash +REMOTE_URL=$(git config --get remote.origin.url) +COMMIT_SHA=$(git rev-parse HEAD) +``` + +Parse the remote URL to construct GitHub commit links: +- For HTTPS URLs like `https://github.com/username/repo.git`: Extract username and repo from path +- For SSH URLs like `git@github.com:username/repo.git`: Extract username and repo after the colon +- Final URL format: `https://github.com/username/repo/commit/COMMIT_SHA` + +Example extraction logic: +```bash +# Remove .git suffix and extract parts +if [[ $REMOTE_URL == *"github.com:"* ]]; then + # SSH format: git@github.com:username/repo.git + REPO_PATH=${REMOTE_URL#*:} + REPO_PATH=${REPO_PATH%.git} +elif [[ $REMOTE_URL == *"github.com/"* ]]; then + # HTTPS format: https://github.com/username/repo.git + REPO_PATH=${REMOTE_URL#*github.com/} + REPO_PATH=${REPO_PATH%.git} +fi +GITHUB_URL="https://github.com/${REPO_PATH}/commit/${COMMIT_SHA}" +``` + ## Environment & Tools ### Python/Conda Environment -- ALWAYS use conda binary at `/vol/biomedic3/vj724/miniconda3/bin/conda` +- ALWAYS use conda binary at `$CONDA_PREFIX/bin/conda` - ALWAYS use this format for script execution: ```bash -/vol/biomedic3/vj724/miniconda3/bin/conda run --live-stream -n ENVIRONMENT_NAME python -u your_script.py [args] +$CONDA_PREFIX/bin/conda run --live-stream -n ENVIRONMENT_NAME python -u your_script.py [args] ``` - ALWAYS include --live-stream and -u flags for real-time output -- You will be told the conda env name to use in the `plan.md` +- You will be TOLD the conda env name to use in the `plan.md`, if not told, log this as termination reason in `task_log.md` and if twilio configured, text to the user. ### Sandbox Environment - You have full file system access within the container @@ -141,6 +176,7 @@ Upon successful task completion: ### When to Commit - Commit after completing each major step in your checklist - Use execution context, not git diff, to write messages +- Always push to origin after commits: git push -u origin claude-docker ### Commit Message Format **Subject Line:** @@ -180,7 +216,7 @@ See task_log.md for details **Successful Completion:** ``` TASK COMPLETED: [Brief summary] -Files modified: [Key files changed] +GIT_COMMIT_URL: [Remote Git URL] See task_log.md for full details ```