Skip to content

CLAUDE.md

Latest commit

 

History

History
223 lines (161 loc) · 6.91 KB

CLAUDE.md

File metadata and controls

223 lines (161 loc) · 6.91 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a reusable DevContainer template that provides a secure, isolated Python 3.13 development environment with:

  • Claude Code CLI pre-installed
  • Playwright browser automation (Chromium, Firefox, WebKit)
  • uv (fast Python package manager)
  • Node.js 20.x and npm
  • Optional network firewall restrictions for security-sensitive development
  • Enhanced shell with ZSH, Powerline10k, and fzf for fuzzy searching

This template can be easily copied to any project using the create-devcontainer.sh script.

Using This Template

To use this template in your project:

  1. Clone or have access to this template repository
  2. Run the creation script: 
    ./create-devcontainer.sh /path/to/your/project
  3. Optional: Customize with flags: 
    ./create-devcontainer.sh --timezone "UTC" --name "MyApp" /path/to/your/project
  4. Open your project in VS Code with the Dev Containers extension
  5. VS Code will automatically detect .devcontainer/ and prompt to reopen in container

Available Script Options

  • --timezone TZ: Set container timezone (default: America/Los_Angeles)
  • --name NAME: Custom container name (default: derived from directory name)
  • --dry-run: Preview changes without applying them
  • --help: Show usage information

Testing the Template

This template includes a comprehensive test suite in devcontainer_tests/ that validates:

  • File visibility across container boundaries
  • Python CLI execution
  • Playwright browser automation
  • All development tools

Note: These tests are for validating the template itself and are not meant to be copied to projects using the template.

To run the test suite:

# From inside the devcontainer:
cd devcontainer_tests/
./setup_tests.sh
./run_tests.sh

# From outside (host machine):
cd devcontainer_tests/
./test_from_host.sh

See devcontainer_tests/TESTING.md for detailed test documentation.

Key Architecture

DevContainer Structure

The .devcontainer/ directory contains the complete container configuration:

  • devcontainer.json: Main configuration defining the container build, VS Code extensions, port forwarding, and lifecycle hooks
  • Dockerfile: Creates a Python 3.13 environment with all developer tools
  • init-firewall.sh: Network security script that restricts outbound connections to whitelisted domains only
  • post-create.sh: Post-creation validation script that displays installed tool versions

Network Security Model

The firewall script (init-firewall.sh) implements a whitelist-based security model:

  1. Flushes all existing iptables rules while preserving Docker DNS resolution
  2. Whitelists specific domains by resolving their IPs and adding to an ipset:
    • GitHub (web, api, git)
    • npm registry
    • Claude API (api.anthropic.com)
    • Statsig (analytics)
    • VS Code marketplace and updates
  3. Blocks all other outbound connections using DROP policy with REJECT for immediate feedback
  4. Validates configuration by confirming example.com is blocked and api.github.com is accessible

The firewall must be manually enabled with sudo /usr/local/bin/init-firewall.sh after container creation.

Container Privileges

The container requires elevated network capabilities (NET_ADMIN, NET_RAW) to configure iptables, specified in devcontainer.json via runArgs.

Development Commands

Starting the Environment

Open the project in VS Code with the Dev Containers extension installed. VS Code will automatically build and start the container.

Running the Firewall

To enable network security restrictions after the container starts:

sudo /usr/local/bin/init-firewall.sh

Python Package Management

This environment uses uv as the primary Python package manager for speed:

uv pip install <package>
uv pip list
uv venv  # Create virtual environment

Standard pip is also available:

pip install <package>

Playwright Browser Automation

Playwright browsers are pre-installed at /ms-playwright:

playwright --version
python -c "from playwright.sync_api import sync_playwright"

Claude Code CLI

The Claude Code CLI is globally installed:

claude --version
claude  # Start interactive session

Git and Developer Tools

Enhanced git diffs with git-delta:

git diff  # Automatically uses delta for syntax-highlighted diffs

Fuzzy file/history search with fzf:

# Press Ctrl+R for fuzzy command history search
# Press Ctrl+T for fuzzy file search (if configured)

Container Management

Rebuild the DevContainer when Dockerfile changes:

  • In VS Code: Command Palette → "Dev Containers: Rebuild Container"
  • Or rebuild without cache: "Dev Containers: Rebuild Container Without Cache"

View current firewall rules:

sudo iptables -L -v -n

Temporarily disable firewall for debugging:

sudo iptables -P OUTPUT ACCEPT  # Allow all outbound traffic
sudo iptables -F OUTPUT         # Flush OUTPUT chain rules

To re-enable, run the firewall script again: sudo /usr/local/bin/init-firewall.sh

Important Configuration Details

  • Timezone: Set via TZ build arg (default: America/Los_Angeles)
  • Shell: ZSH with Powerline10k theme for enhanced developer experience
  • Command History: Persisted in Docker volume python3-devcontainer-commandhistory
  • User: Non-root user vscode with sudo access
  • Port Forwarding: Ports 8000, 8080, and 3000 are forwarded by default
  • Workspace: Mounted at /workspaces/python3-devcontainer

Modifying the Configuration

Adding Allowed Domains to Firewall

To whitelist additional domains, edit init-firewall.sh and add the domain to the loop at line 67:

for domain in \
    "registry.npmjs.org" \
    "api.anthropic.com" \
    "statsig.anthropic.com" \
    "statsig.com" \
    "your-new-domain.com"; do

Changing Python or Node Versions

Edit the Dockerfile:

  • Python version: Change the base image on line 2 (FROM python:3.13-slim-bookworm)
  • Node.js version: Change the setup script version on line 64 (setup_20.x)

Adding VS Code Extensions

Add extension IDs to the extensions array in devcontainer.json at line 28.

Troubleshooting

Network Requests Failing After Firewall Setup

If legitimate requests are blocked:

  1. Check current firewall rules: sudo iptables -L -v -n
  2. Check kernel messages for rejected connections: dmesg | tail -20
  3. Add the domain to the whitelist in init-firewall.sh at line 67
  4. Re-run the firewall script: sudo /usr/local/bin/init-firewall.sh

Playwright Browsers Not Found

Browsers are installed during image build. If missing, rebuild the container or manually run:

playwright install chromium firefox webkit

Permission Issues with iptables

Ensure the container has NET_ADMIN and NET_RAW capabilities in devcontainer.json.