docs: Add v0.1.0 history and update reference with k3s notes
- Created history/v0.1.0.md with full deployment notes - Added k3s implementation section to reference.md - Fixed auth command: `claude` not `claude /login` - Documented issues encountered and solutions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jordan
parent
d4eb41589f
commit
179b6521ca
@ -1602,7 +1602,7 @@ claude-manage health # Run health checks
|
||||
/monorepo-info # Show structure
|
||||
|
||||
# Maintenance
|
||||
claude /login # Re-authenticate (host)
|
||||
claude # Interactive mode (triggers auth if needed)
|
||||
claude-manage restart # Restart containers
|
||||
claude-manage update # Update everything
|
||||
```
|
||||
@ -1610,3 +1610,83 @@ claude-manage update # Update everything
|
||||
For advanced configurations, refer to the individual project documentation:
|
||||
- claudebox: https://github.com/RchGrav/claudebox
|
||||
- claude-code-discord: https://github.com/zebbern/claude-code-discord
|
||||
|
||||
---
|
||||
|
||||
## rdev: K3s Implementation Notes
|
||||
|
||||
This section documents our actual implementation running on k3s instead of a standalone VM.
|
||||
|
||||
### Architecture Difference
|
||||
|
||||
The reference guide above describes a VM-based deployment with Docker Compose. Our implementation uses:
|
||||
|
||||
- **Kubernetes (k3s)** instead of Docker Compose
|
||||
- **StatefulSets** instead of standalone containers
|
||||
- **Longhorn PVCs** instead of host volume mounts
|
||||
- **GitHub Container Registry** instead of local images
|
||||
|
||||
```
|
||||
k3s cluster (orchard9-k3sf)
|
||||
└── rdev namespace
|
||||
├── claudebox-0 (StatefulSet pod)
|
||||
│ ├── Claude Code CLI
|
||||
│ ├── /workspace (PVC: 20Gi)
|
||||
│ └── /root/.claude (PVC: 1Gi)
|
||||
└── Future: discord-bot, claudebox-pantheon, claudebox-aeries
|
||||
```
|
||||
|
||||
### Key Commands
|
||||
|
||||
```bash
|
||||
# REQUIRED: Set kubeconfig before any kubectl command
|
||||
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
|
||||
|
||||
# Interactive Claude session (triggers OAuth if not authenticated)
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude
|
||||
|
||||
# Run Claude with a prompt
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude "your prompt here"
|
||||
|
||||
# Shell access
|
||||
kubectl exec -it -n rdev claudebox-0 -- bash
|
||||
|
||||
# Check status
|
||||
kubectl get pods -n rdev
|
||||
|
||||
# View logs
|
||||
kubectl logs -n rdev claudebox-0
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Claude authenticates via OAuth on first run. Auth persists in the `/root/.claude` PVC:
|
||||
|
||||
```bash
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude
|
||||
# Follow the URL to authenticate
|
||||
# Auth persists across pod restarts
|
||||
```
|
||||
|
||||
### Image
|
||||
|
||||
```
|
||||
ghcr.io/orchard9/rdev-claudebox:v0.1.0
|
||||
```
|
||||
|
||||
Built for `linux/amd64` (k3s node architecture).
|
||||
|
||||
### Differences from Reference Guide
|
||||
|
||||
| Reference Guide | rdev Implementation |
|
||||
|-----------------|---------------------|
|
||||
| VM with Docker Compose | k3s with Kustomize |
|
||||
| `docker exec` | `kubectl exec` |
|
||||
| Host volume mounts | Longhorn PVCs |
|
||||
| `~/.claude/.credentials.json` | PVC at `/root/.claude` |
|
||||
| claudebox binary | Custom Dockerfile |
|
||||
| Deno Discord bot | TBD (v0.4+) |
|
||||
|
||||
### Version History
|
||||
|
||||
See `history/` directory for detailed release notes.
|
||||
|
||||
161
history/v0.1.0.md
Normal file
161
history/v0.1.0.md
Normal file
@ -0,0 +1,161 @@
|
||||
# rdev v0.1.0 - Base Case
|
||||
|
||||
**Date**: 2026-01-24
|
||||
**Status**: Deployed and verified
|
||||
|
||||
## Summary
|
||||
|
||||
First deployment of rdev - a single claudebox pod running on k3s with Claude Code CLI.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### Container Image
|
||||
- **Image**: `ghcr.io/orchard9/rdev-claudebox:v0.1.0`
|
||||
- **Base**: Ubuntu 22.04
|
||||
- **Platform**: linux/amd64 (k3s nodes are amd64, built from arm64 Mac)
|
||||
- **Contents**:
|
||||
- Node.js 20 (required for Claude Code CLI)
|
||||
- Claude Code CLI v2.1.19
|
||||
- Git, vim, build-essential
|
||||
- Healthcheck script
|
||||
|
||||
### Kubernetes Resources
|
||||
- **Namespace**: `rdev`
|
||||
- **StatefulSet**: `claudebox` (1 replica)
|
||||
- **PVCs**:
|
||||
- `claudebox-workspace` (20Gi) - for project files
|
||||
- `claudebox-claude-config` (1Gi) - for Claude auth persistence
|
||||
- **Service**: `claudebox` (headless)
|
||||
- **Secret**: `ghcr-secret` (copied from apps namespace)
|
||||
|
||||
### Resource Limits
|
||||
```yaml
|
||||
requests:
|
||||
cpu: "500m"
|
||||
memory: "1Gi"
|
||||
limits:
|
||||
cpu: "2"
|
||||
memory: "4Gi"
|
||||
```
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### 1. GitHub Container Registry over GCP Artifact Registry
|
||||
- This is an on-prem k3s cluster, not GKE
|
||||
- Already have ghcr-secret for other images
|
||||
- No gcloud dependency
|
||||
|
||||
### 2. PVC for Claude Config instead of Secret
|
||||
- Claude credentials are too large for K8s secrets (>3MB limit)
|
||||
- Auth persists across pod restarts
|
||||
- User authenticates once via `kubectl exec`
|
||||
|
||||
### 3. Platform-specific Build
|
||||
- k3s nodes are amd64
|
||||
- Mac builds arm64 by default
|
||||
- Added `--platform linux/amd64` to docker build
|
||||
|
||||
## Authentication
|
||||
|
||||
Claude Code authenticates via OAuth. To authenticate:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude
|
||||
```
|
||||
|
||||
This opens interactive mode. First run triggers OAuth flow - follow the URL to authenticate. Auth persists in the PVC.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# Check pod status
|
||||
kubectl get pods -n rdev
|
||||
# NAME READY STATUS RESTARTS AGE
|
||||
# claudebox-0 1/1 Running 0 58s
|
||||
|
||||
# Check Claude version
|
||||
kubectl exec -n rdev claudebox-0 -- claude --version
|
||||
# 2.1.19 (Claude Code)
|
||||
|
||||
# Test Claude (after auth)
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude "say hello"
|
||||
```
|
||||
|
||||
## Files Created
|
||||
|
||||
```
|
||||
rdev/
|
||||
├── CLAUDE.md # Project instructions
|
||||
├── README.md # Setup guide
|
||||
├── Dockerfile # claudebox image
|
||||
├── .gitignore
|
||||
├── docs/
|
||||
│ └── reference.md # Original reference guide
|
||||
├── deployments/
|
||||
│ └── k8s/
|
||||
│ └── base/
|
||||
│ ├── kustomization.yaml
|
||||
│ ├── namespace.yaml
|
||||
│ ├── pvc.yaml # workspace + claude-config PVCs
|
||||
│ └── claudebox.yaml # StatefulSet + Service
|
||||
├── scripts/
|
||||
│ ├── build-push.sh # Build and push to ghcr.io
|
||||
│ ├── deploy.sh # Deploy to k3s
|
||||
│ ├── verify.sh # Verify deployment
|
||||
│ └── create-credentials-secret.sh # (deprecated - using PVC now)
|
||||
└── history/
|
||||
└── v0.1.0.md # This file
|
||||
```
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
### 1. Image Pull Failed - Wrong Platform
|
||||
- **Error**: `no match for platform in manifest: not found`
|
||||
- **Cause**: Built arm64 image on Mac, k3s nodes are amd64
|
||||
- **Fix**: Added `--platform linux/amd64` to docker build
|
||||
|
||||
### 2. Credentials Secret Too Large
|
||||
- **Error**: `Request entity too large: limit is 3145728`
|
||||
- **Cause**: ~/.claude directory is ~30MB (history, debug logs, etc.)
|
||||
- **Fix**: Switched to PVC for claude config instead of mounting from secret
|
||||
|
||||
### 3. GCP Artifact Registry Auth Failed
|
||||
- **Error**: `403 Forbidden` when pushing to us-central1-docker.pkg.dev
|
||||
- **Cause**: Wrong approach - this is k3s, not GKE
|
||||
- **Fix**: Switched to GitHub Container Registry (ghcr.io)
|
||||
|
||||
## What's Next (v0.2)
|
||||
|
||||
1. Mount real project workspaces (pantheon, aeries repos)
|
||||
2. Add SSH keys for git push/pull
|
||||
3. Multiple claudebox pods (one per project)
|
||||
4. Project-specific environment configurations
|
||||
|
||||
## Commands Reference
|
||||
|
||||
```bash
|
||||
# Set kubeconfig (REQUIRED)
|
||||
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
|
||||
|
||||
# Deploy
|
||||
kubectl apply -k deployments/k8s/base
|
||||
|
||||
# Check status
|
||||
kubectl get pods -n rdev
|
||||
|
||||
# Interactive Claude session
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude
|
||||
|
||||
# Run Claude with prompt
|
||||
kubectl exec -it -n rdev claudebox-0 -- claude "your prompt here"
|
||||
|
||||
# Shell access
|
||||
kubectl exec -it -n rdev claudebox-0 -- bash
|
||||
|
||||
# View logs
|
||||
kubectl logs -n rdev claudebox-0
|
||||
|
||||
# Restart pod
|
||||
kubectl delete pod -n rdev claudebox-0
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user