diff --git a/README.md b/README.md index 052ee2f..c9a0e2a 100644 --- a/README.md +++ b/README.md @@ -1,341 +1,221 @@ -# Claude Code + Agents UI Stack - Complete Package +# Claude Code + Agents UI Stack -## 📦 What's Included - -This package contains everything needed to deploy a complete Claude Code + Agents UI Docker stack to your TrueNAS SCALE instance. - -### Files Overview - -``` -claude-code-stack/ -├── QUICKSTART.md # Start here! -├── DEPLOYMENT_GUIDE.md # Comprehensive guide -├── docker-compose.yml # Main Docker Compose configuration -├── claude-agents-ui-Dockerfile # Custom Docker image combining UI + Claude Code -├── nginx.conf # Reverse proxy configuration -├── claude-code-stack.env # Environment variables template -├── deploy-ssh.sh # Automated SSH deployment script (RECOMMENDED) -├── deploy-mcp.py # MCP-based deployment script -└── README.md # This file -``` - -## 🚀 Quick Start (30 seconds) - -```bash -# 1. Set your API key -export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here" - -# 2. Run the deployment script -chmod +x deploy-ssh.sh -./deploy-ssh.sh 192.168.1.100 root tank - -# 3. Access the UI -# Open: http://192.168.1.100:3000 -``` - -## 📋 What Each File Does - -### QUICKSTART.md -**Start here if you're in a hurry!** -- 3 deployment methods -- Quick setup instructions -- Troubleshooting tips -- Common commands - -### DEPLOYMENT_GUIDE.md -**Complete reference guide** -- Detailed architecture -- Step-by-step setup -- Configuration options -- Monitoring & maintenance -- Security hardening -- Performance tuning - -### docker-compose.yml -**Main orchestration file** -Includes: -- Claude Code Agents UI (Nuxt 3 frontend) -- Claude Code Runtime (code execution) -- PostgreSQL (data persistence) -- Redis (caching) -- Nginx (reverse proxy) - -All services with: -- Health checks -- Volume management -- Network configuration -- Resource limits - -### claude-agents-ui-Dockerfile -**Optional: Combined image** -Builds a single Docker image containing: -- Agents UI (Nuxt 3) -- Claude Code CLI -- Required dependencies -- Non-root user for security - -Use this if you prefer building a custom image instead of using pre-built images. - -### nginx.conf -**Reverse proxy configuration** -- Load balancing -- SSL/TLS support -- Rate limiting -- Security headers -- WebSocket support -- Static file caching - -### claude-code-stack.env -**Environment variables template** -Configure: -- Anthropic API key (REQUIRED) -- Database credentials -- API ports and hosts -- Security settings -- Storage options -- Agent configuration - -### deploy-ssh.sh -**Automated SSH deployment** ⭐ RECOMMENDED -- One-command setup -- Validates prerequisites -- Tests SSH connection -- Creates directories -- Uploads files -- Configures environment -- Starts services -- Verifies deployment -- Sets up monitoring - -### deploy-mcp.py -**MCP-based deployment** -For advanced users with MCP server running: -- Deploys via MCP protocol -- Async/await operation -- Progress indicators -- Error handling - -## 🎯 Deployment Flowchart - -``` -Start - │ - ├─→ Choose Method - │ ├─→ SSH (recommended) → deploy-ssh.sh - │ ├─→ MCP (advanced) → deploy-mcp.py - │ └─→ Manual → Use docker-compose.yml directly - │ - ├─→ Prerequisites - │ ├─→ API Key ✓ - │ ├─→ SSH access ✓ - │ └─→ Docker on TrueNAS ✓ - │ - ├─→ Deploy Stack - │ ├─→ Create directory - │ ├─→ Upload files - │ ├─→ Configure .env - │ ├─→ Pull images - │ └─→ Start services - │ - ├─→ Verify - │ ├─→ Check service status - │ ├─→ Test port 3000 - │ └─→ View logs - │ - └─→ Access UI - └─→ http://your-truenas-ip:3000 -``` - -## 🏗️ Architecture - -``` -Your Computer - │ - │ (SSH or MCP) - ▼ -TrueNAS SCALE - │ - ├─→ docker-compose - │ - └─→ Services: - ├─→ Claude Code Agents UI (Port 3000) - │ └─→ Web interface for agent management - │ - ├─→ Claude Code Backend (Port 5000) - │ └─→ Code execution environment - │ - ├─→ PostgreSQL (Port 5432) - │ └─→ Agent data persistence - │ - ├─→ Redis (Port 6379) - │ └─→ Caching & sessions - │ - └─→ Nginx (Port 80/443) - └─→ Reverse proxy -``` - -## 🔐 Security Features - -- ✓ Non-root user execution -- ✓ Health checks on all services -- ✓ Security headers via Nginx -- ✓ Rate limiting -- ✓ SSL/TLS support (optional) -- ✓ Environment variable isolation -- ✓ Volume isolation -- ✓ Network isolation - -## 📊 Resource Requirements - -### Minimum -- RAM: 2GB allocated to Docker -- CPU: 2 cores -- Disk: 10GB free - -### Recommended -- RAM: 4GB allocated to Docker -- CPU: 4 cores -- Disk: 20GB free - -### Optimal -- RAM: 8GB+ allocated to Docker -- CPU: 8+ cores -- Disk: 50GB+ free - -## 🚦 Deployment Status - -After running `deploy-ssh.sh`, you'll see: - -``` -[INFO] Checking prerequisites... -[INFO] Testing SSH connection... -[INFO] Creating project directory on TrueNAS... -[INFO] Uploading Docker configuration files... -[INFO] Configuring environment variables... -[INFO] Deploying Docker stack... -[INFO] Verifying deployment... -======================================== - Claude Code Stack Deployed! -======================================== - -Access the Agents UI at: - http://192.168.1.100:3000 -``` - -## 📝 Next Steps - -1. **Deploy**: Run `./deploy-ssh.sh your-truenas-ip` -2. **Access**: Open http://your-truenas-ip:3000 -3. **Configure**: Set up API keys and workspace -4. **Create**: Build your first agent -5. **Test**: Execute and monitor agent tasks - -## 🆘 Common Issues - -### Q: SSH connection fails -**A:** Check TrueNAS IP, SSH is enabled, and you have correct credentials. - -### Q: Port 3000 not responding -**A:** Wait 30 seconds for startup. Check logs: `docker-compose logs agents-ui` - -### Q: API key not recognized -**A:** Verify in .env file and restart: `docker-compose restart` - -### Q: PostgreSQL connection fails -**A:** Check credentials match in .env. Run: `docker-compose logs postgres` - -See DEPLOYMENT_GUIDE.md for more troubleshooting. - -## 📚 Documentation - -- **QUICKSTART.md** - Start here for quick setup -- **DEPLOYMENT_GUIDE.md** - Complete reference guide -- **Claude Code Docs** - https://docs.anthropic.com/ -- **GitHub Repo** - https://github.com/Ngxba/claude-code-agents-ui - -## 🎓 Learning Resources - -### Getting Started with Claude Code -```bash -claude --help -claude "What's in the current directory?" -``` - -### Creating Agents -Use the Agents UI at http://your-truenas-ip:3000 to: -- Create agents -- Configure models -- Set instructions -- Build workflows - -### Using Agents -```bash -# View available agents -claude list-agents - -# Run an agent -claude run agent-name "prompt" - -# Interactive mode -claude chat agent-name -``` - -## 🔄 Update & Maintenance - -### Pull Latest Images -```bash -docker-compose pull -docker-compose up -d -``` - -### View Logs -```bash -docker-compose logs -f [service] -``` - -### Backup Data -```bash -docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz -``` - -### Clean Up -```bash -docker system prune -a -docker volume prune -``` - -## 📞 Support - -For issues or questions: - -1. Check **DEPLOYMENT_GUIDE.md** troubleshooting section -2. Review **QUICKSTART.md** for common solutions -3. Check Docker logs: `docker-compose logs` -4. Visit: https://github.com/Ngxba/claude-code-agents-ui/issues -5. See: https://docs.anthropic.com/ - -## 📄 License - -This deployment package is provided as-is. - -- **Claude Code** - Use your Anthropic API key -- **Agents UI** - MIT License (https://github.com/Ngxba/claude-code-agents-ui) -- **Docker Components** - Various open-source licenses - -## 🎉 Success! - -Once deployed, you'll have: -- ✓ Web interface for agent management -- ✓ Claude Code execution environment -- ✓ Persistent storage with PostgreSQL -- ✓ Caching layer with Redis -- ✓ Reverse proxy with Nginx -- ✓ All integrated and running on TrueNAS - -Happy coding! 🚀 +A self-hosted Docker stack that combines the [claude-code-agents-ui](https://github.com/Ngxba/claude-code-agents-ui) frontend with the Claude Code CLI runtime, designed for TrueNAS SCALE deployment. --- -**Version**: 1.0.0 -**Last Updated**: 2026-04-04 -**Compatibility**: TrueNAS SCALE, Docker Compose 3.8+ +## What's Included + +| File | Purpose | +|------|---------| +| `claude-agents-ui-Dockerfile` | Multi-stage image: builds the Nuxt 3 UI + installs Claude Code CLI | +| `claude-code-stack-docker-compose.yml` | Orchestrates all services (UI, runtime, Postgres, Redis, Nginx) | +| `claude-code-stack.env` | Environment variable template — copy to `.env` before deploying | +| `nginx.conf` | Reverse-proxy config (SSL-ready) | +| `deploy-ssh.sh` | One-command SSH deployment to TrueNAS ⭐ recommended | +| `deploy-mcp.py` | MCP-based deployment (advanced) | +| `QUICKSTART.md` | 5-minute setup guide | +| `DEPLOYMENT_GUIDE.md` | Full reference | +| `CHECKLIST.md` | Pre/post-deployment checklist | + +--- + +## Quick Start + +```bash +# 1. Set your Anthropic API key (get one at https://console.anthropic.com/) +export ANTHROPIC_API_KEY="sk-ant-..." + +# 2. Deploy to TrueNAS +chmod +x deploy-ssh.sh +./deploy-ssh.sh 192.168.1.100 root tank + +# 3. Open the UI +open http://192.168.1.100:3000 +``` + +--- + +## Authentication + +Claude Code requires authentication to execute prompts. This stack implements **non-interactive auth** so no manual `claude auth login` step is needed. + +### How it works + +1. You provide your `ANTHROPIC_API_KEY` in `.env` (or via environment variable). +2. The `agents-ui` container entrypoint writes `~/.claude/.credentials.json` containing your API key on first start. +3. The Claude Code CLI reads this file and is ready to execute without any interactive login step. +4. The `claude-code-backend` container uses `ANTHROPIC_API_KEY` directly at runtime. + +### Manual auth (optional) + +If you prefer OAuth-based login (tied to a Claude.ai subscription rather than pay-per-token API): + +```bash +# SSH into TrueNAS +ssh root@192.168.1.100 + +# Run interactive login inside the container +cd /mnt/tank/docker/claude-code-stack +docker-compose exec agents-ui claude auth login +``` + +The credentials are stored in the `claude-config` Docker volume and persist across restarts. + +### Auth status check + +```bash +docker-compose exec agents-ui claude auth status +``` + +--- + +## Architecture + +``` +Your Browser + │ + ▼ + Nginx :80/:443 + │ + ├──► Agents UI (Nuxt 3) :3000 ──► ~/.claude/ volume + │ │ + │ └──► Claude Code Backend :5000 + │ + ├──► PostgreSQL :5432 + └──► Redis :6379 +``` + +All services share two Docker volumes: +- `claude-config` — Claude credentials, agents, commands, skills, workflows +- `workspace` — Project files for agent execution + +--- + +## Configuration + +Copy the env template and fill in your values: + +```bash +cp claude-code-stack.env .env +nano .env # Set ANTHROPIC_API_KEY and change POSTGRES_PASSWORD / SESSION_SECRET +``` + +### Key variables + +| Variable | Required | Description | +|----------|----------|-------------| +| `ANTHROPIC_API_KEY` | **Yes** | Your Anthropic API key | +| `CLAUDE_MODEL` | No | Model to use (default: `claude-sonnet-4-6`) | +| `POSTGRES_PASSWORD` | **Yes** | Change from default before production | +| `SESSION_SECRET` | **Yes** | Random string — run `openssl rand -base64 32` | + +Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001` + +--- + +## Deployment Methods + +### Method 1: SSH (recommended) + +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +./deploy-ssh.sh 192.168.1.100 root tank +``` + +The script: +- Validates prerequisites +- Tests SSH connectivity +- Creates project directory on TrueNAS +- Uploads all files +- Writes `.env` with auto-generated secrets +- Builds and starts all services +- Verifies Claude auth inside containers + +### Method 2: Manual + +```bash +# SSH into TrueNAS +ssh root@192.168.1.100 + +mkdir -p /mnt/tank/docker/claude-code-stack +cd /mnt/tank/docker/claude-code-stack + +# Upload files, then: +cp claude-code-stack.env .env +cp claude-code-stack-docker-compose.yml docker-compose.yml +cp claude-agents-ui-Dockerfile Dockerfile +nano .env # Set your API key + +docker-compose build +docker-compose up -d +``` + +### Method 3: MCP + +```bash +pip install httpx +python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank +``` + +--- + +## Useful Commands + +```bash +# View all logs +docker-compose logs -f + +# View just the UI logs +docker-compose logs -f agents-ui + +# Check auth status +docker-compose exec agents-ui claude auth status + +# Re-authenticate (interactive OAuth) +docker-compose exec agents-ui claude auth login + +# Restart a service +docker-compose restart agents-ui + +# Pull latest images +docker-compose pull && docker-compose up -d + +# Stop everything +docker-compose down + +# Stop and remove volumes (WARNING: deletes all data) +docker-compose down -v +``` + +--- + +## Resource Requirements + +| Tier | RAM | CPU | Disk | +|------|-----|-----|------| +| Minimum | 2 GB | 2 cores | 10 GB | +| Recommended | 4 GB | 4 cores | 20 GB | +| Optimal | 8 GB+ | 8+ cores | 50 GB+ | + +--- + +## Security Notes + +- Change `POSTGRES_PASSWORD` from the default before production +- Generate a proper `SESSION_SECRET`: `openssl rand -base64 32` +- The `.env` file is chmod 600 — never commit it to version control +- The `claude-config` volume contains your API credentials — back it up securely +- Consider restricting Nginx to internal network access only + +--- + +## Links + +- [Agents UI source](https://github.com/Ngxba/claude-code-agents-ui) +- [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code) +- [Anthropic console](https://console.anthropic.com/) + +--- + +**Version:** 1.1.0 | **Updated:** 2026-04-04 | **Compatibility:** TrueNAS SCALE, Docker Compose 3.8+