docs(claude.md): sync with current project state
All checks were successful
Build images / check-docker (push) Successful in 3s
Build images / build-and-push (push) Successful in 5m4s

Update architecture (remove webui reference), file structure (add setup.sh,
launch.sh, launch.bat, hooks/), auth (credentials now in ~/.claude), and
development workflow (use setup.sh instead of manual .env copy).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
docker-claude 2026-04-16 10:17:49 +02:00
parent 3aff92bd41
commit cf50570733

View file

@ -13,25 +13,31 @@ Two containers managed by Docker Compose:
- **`claude`** — Claude Code CLI (`node:20-alpine`), runs as the built-in `node` user (UID 1000), isolated to an internal-only Docker network
- **`proxy`** — Squid forward proxy (`alpine:3.21`), `squid` user, bridges the internal network to the internet with an egress allowlist
Key Docker network property: `claude-internal` has `internal: true`, meaning Docker adds no default gateway. The `claude` and `webui` containers physically cannot reach the internet without going through the `proxy` container.
Key Docker network property: `claude-internal` has `internal: true`, meaning Docker adds no default gateway. The `claude` container physically cannot reach the internet without going through the `proxy` container.
Auth supports three modes (checked at startup by `claude.sh`):
- `ANTHROPIC_API_KEY` — API key
- `CLAUDE_CODE_OAUTH_TOKEN` — 1-year token from `claude setup-token` (headless-friendly)
- Neither set — Claude Code prompts for browser login on first run; port 54545 is published for the OAuth callback. Credentials persist in the `claude-config` named volume.
- Neither set — Claude Code prompts for browser login on first run; port 54545 is published for the OAuth callback. Credentials persist in `~/.claude` on the host.
## File Structure
```
docker-claude/
├── claude.sh # Control script: start/stop/run/update/logs/status/shell
├── claude.sh # Control script: start/stop/update/logs/status/shell
├── setup.sh # First-time setup wizard (Docker check + auth config)
├── launch.sh # Folder-picker launcher for macOS/Linux
├── launch.bat # Folder-picker launcher for Windows
├── build.sh # Build images locally (development)
├── docker-compose.yml # Service definitions and network topology
├── claude/
│ └── Dockerfile # Claude Code (node:20-alpine, UID 1000)
│ └── Dockerfile # Claude Code stable release (node:20-alpine, UID 1000)
├── proxy/
│ ├── Dockerfile # Squid proxy sidecar (alpine:3.21, squid user)
│ └── squid.conf # Squid ACL config — egress allowlist lives here
├── .env.example # Template for ANTHROPIC_API_KEY, WEBUI_PASSWORD, etc.
├── hooks/
│ └── pre-commit # Enforces executable bit on shell scripts
├── .env.example # Template for credentials and options
├── .gitignore # Excludes .env and logs
├── .dockerignore # Keeps .env out of build context
└── README.md # User documentation
@ -40,8 +46,7 @@ docker-claude/
## Development Workflow
```bash
chmod +x claude.sh build.sh
cp .env.example .env # set ANTHROPIC_API_KEY
./setup.sh # first-time: configure Docker check + auth
cd /path/to/project && ./claude.sh start # start proxy + launch Claude (pulls images, mounts CWD)
./claude.sh update # pull latest images from registry
./build.sh # build images locally (development)
@ -49,7 +54,7 @@ cd /path/to/project && ./claude.sh start # start proxy + launch Claude (pulls i
## Git Hooks
A pre-commit hook lives in `hooks/` and enforces the executable bit on `claude.sh` and `build.sh`. Activate it once after cloning:
A pre-commit hook lives in `hooks/` and enforces the executable bit on all shell scripts. Activate it once after cloning:
```bash
git config core.hooksPath hooks