diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md deleted file mode 100644 index 9386903..0000000 --- a/DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,504 +0,0 @@ -# Claude Code + Agents UI Docker Stack Deployment Guide - -## Overview - -This guide covers deploying a complete Docker stack on your TrueNAS SCALE instance that combines: -- **Claude Code Agents UI** (Nuxt 3 frontend for agent orchestration) -- **Claude Code Runtime** (Backend for code execution) -- **PostgreSQL** (Optional: for agent data persistence) -- **Redis** (Optional: for caching) -- **Nginx** (Optional: reverse proxy) - -## Prerequisites - -### System Requirements -- TrueNAS SCALE with Docker/Portainer running -- Minimum 4GB RAM allocated to Docker -- At least 20GB free disk space -- Anthropic API key (get from https://console.anthropic.com/) - -### Network Requirements -- Port 3000 (Agents UI) -- Port 5000 (Claude Code API - optional) -- Port 80/443 (Nginx - optional) -- Port 5432 (PostgreSQL - optional) -- Port 6379 (Redis - optional) - -## Deployment Methods - -### Method 1: SSH Deployment (Recommended for TrueNAS) - -#### Step 1: SSH into your TrueNAS system - -```bash -ssh root@your-truenas-ip -# or use your specific TrueNAS user -``` - -#### Step 2: Create project directory - -```bash -mkdir -p /mnt/pool-name/docker/claude-code-stack -cd /mnt/pool-name/docker/claude-code-stack -``` - -#### Step 3: Clone/create Docker files - -Option A: Clone the entire repo with compose file: -```bash -git clone https://github.com/Ngxba/claude-code-agents-ui.git -cd claude-code-agents-ui -``` - -Option B: Copy the provided docker-compose.yml (recommended for your setup): -```bash -# Copy the provided files to this directory -# - docker-compose.yml -# - claude-code-stack.env -# - nginx.conf -# - Dockerfile (if using combined image) -``` - -#### Step 4: Configure environment variables - -```bash -cp claude-code-stack.env .env -nano .env # or vim .env -``` - -Update these critical variables: -```env -ANTHROPIC_API_KEY=sk-ant-your-actual-key-here -POSTGRES_PASSWORD=your-secure-password -SESSION_SECRET=your-random-session-secret -``` - -#### Step 5: Deploy with Docker Compose - -```bash -# Pull latest images -docker-compose pull - -# Build custom image (if using combined Dockerfile) -docker-compose build --no-cache - -# Start all services -docker-compose up -d - -# Check status -docker-compose ps -``` - -#### Step 6: Verify deployment - -```bash -# Check logs -docker-compose logs -f agents-ui -docker-compose logs -f claude-code-backend - -# Test Claude Code UI -curl http://localhost:3000 - -# Test Claude Code API -curl http://localhost:5000/health 2>/dev/null || echo "API not yet responsive" -``` - -### Method 2: TrueNAS MCP Deployment - -If you have the TrueNAS MCP server configured: - -```javascript -// Example: Using TrueNAS MCP to deploy - -await mcp.call('truenas:create_dataset', { - parent: 'pool-name', - name: 'docker/claude-code-stack' -}); - -await mcp.call('truenas:list_directory', { - path: '/mnt/pool-name/docker/claude-code-stack' -}); - -// Write Docker Compose file via MCP -// (Use ssh_ssh_exec for Docker commands) -``` - -### Method 3: Portainer UI Deployment - -If using Portainer on TrueNAS: - -1. **Open Portainer** at `https://your-truenas-ip:9000` -2. **Go to: Stacks > Add Stack** -3. **Upload or paste** the docker-compose.yml content -4. **Set environment variables** via the Web Editor -5. **Deploy** - -## Stack Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ Claude Code Stack │ -├─────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────────┐ ┌────────────────────┐ │ -│ │ Nginx (Port 80) │◄───────►│ Agents UI │ │ -│ │ (optional) │ │ (Port 3000) │ │ -│ └──────────────────┘ ├────────────────────┤ │ -│ │ - Agent Management │ │ -│ │ - Chat Interface │ │ -│ ┌──────────────────┐ │ - Workflow Builder │ │ -│ │ Claude Code │ └────────────────────┘ │ -│ │ Backend (5000) │ │ -│ │ │ ┌────────────────────┐ │ -│ │ - Code Execution │◄───────►│ PostgreSQL │ │ -│ │ - File Access │ │ (Port 5432) │ │ -│ │ - Shell Commands │ │ (optional) │ │ -│ └──────────────────┘ └────────────────────┘ │ -│ │ │ │ -│ └──────────────┬───────────────┘ │ -│ │ │ -│ ┌─────▼──────┐ │ -│ │ Redis │ │ -│ │ (6379) │ │ -│ │ (optional) │ │ -│ └────────────┘ │ -│ │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ Shared Volumes │ │ -│ │ - /workspace (projects) │ │ -│ │ - /root/.claude (config) │ │ -│ └────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Post-Deployment Setup - -### 1. Initialize Claude Code Configuration - -```bash -docker-compose exec claude-code-backend bash - -# Inside container: -claude auth login -# Follow the authentication flow - -# Create initial .claude directory structure -mkdir -p ~/.claude/agents ~/.claude/skills ~/.claude/commands -cd ~/.claude -``` - -### 2. Configure Agents UI - -The Agents UI will automatically detect: -- Your Claude configuration at `~/.claude` -- Available agents and commands -- Environment setup - -Access it at: `http://your-truenas-ip:3000` - -### 3. Set Up Project Workspace - -```bash -# Create workspace structure -docker-compose exec agents-ui bash -c "mkdir -p /workspace/{projects,agents,tools}" - -# Mount your projects (example) -docker-compose exec agents-ui bash -c "ln -s /mnt/shared/projects /workspace/projects" -``` - -### 4. Configure SSH Keys (Optional but Recommended) - -For agents to perform git operations: - -```bash -docker-compose exec claude-code-backend bash - -# Inside container: -ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N "" - -# Copy public key to your GitHub/GitLab: -cat ~/.ssh/id_rsa.pub -``` - -## Common Operations - -### Start/Stop Stack - -```bash -# Start -docker-compose up -d - -# Stop -docker-compose down - -# Stop with volume preservation -docker-compose down --remove-orphans - -# Full reset (CAUTION: removes volumes) -docker-compose down -v -``` - -### View Logs - -```bash -# All services -docker-compose logs -f - -# Specific service -docker-compose logs -f agents-ui -docker-compose logs -f claude-code-backend - -# Follow errors only -docker-compose logs -f --tail=100 | grep -i error -``` - -### Execute Commands in Container - -```bash -# Access Agents UI shell -docker-compose exec agents-ui sh - -# Access Claude Code shell -docker-compose exec claude-code-backend bash - -# Run Claude Code directly -docker-compose exec claude-code-backend claude "your prompt here" -``` - -### Backup and Restore - -```bash -# Backup volumes -docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > claude-backup.tar.gz - -# Backup workspace -tar czf workspace-backup.tar.gz workspace/ - -# Restore -tar xzf claude-backup.tar.gz -C workspace/ -``` - -## Troubleshooting - -### Issue: Connection refused on port 3000 - -```bash -# Check if service is running -docker-compose ps - -# Check service logs -docker-compose logs agents-ui - -# Restart service -docker-compose restart agents-ui -``` - -### Issue: ANTHROPIC_API_KEY not recognized - -```bash -# Verify .env file exists and has correct key -cat .env | grep ANTHROPIC_API_KEY - -# Pass key directly in docker-compose command -ANTHROPIC_API_KEY=your-key docker-compose up -d -``` - -### Issue: PostgreSQL connection fails - -```bash -# Check if postgres is ready -docker-compose exec postgres pg_isready -U claude - -# Check credentials in .env -grep POSTGRES .env - -# View postgres logs -docker-compose logs postgres -``` - -### Issue: Agents UI can't find Claude config - -```bash -# Verify mount -docker-compose exec agents-ui ls -la /root/.claude/ - -# Check permissions -docker-compose exec agents-ui stat /root/.claude - -# Ensure volume is created -docker volume ls | grep claude -``` - -## Performance Tuning - -### Increase Resource Limits - -Edit docker-compose.yml: - -```yaml -services: - agents-ui: - deploy: - resources: - limits: - cpus: '2' - memory: 2G - reservations: - cpus: '1' - memory: 1G -``` - -### Enable Redis Caching - -```bash -# Uncomment Redis in docker-compose.yml -# Set REDIS_HOST=redis in .env -docker-compose up -d redis -``` - -### Database Optimization - -```bash -# Increase PostgreSQL max connections -docker-compose exec postgres psql -U claude -c "ALTER SYSTEM SET max_connections = 200;" -docker-compose restart postgres -``` - -## Security Hardening - -### 1. Enable SSL/TLS - -```bash -# Generate self-signed certificate (for testing) -openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes - -# Or use Let's Encrypt with certbot -mkdir -p certs -# Place your cert.pem and key.pem in ./certs/ -``` - -Update docker-compose.yml to mount certs. - -### 2. Restrict Network Access - -```bash -# Allow only specific IPs to Nginx -# In nginx.conf, add to each location: -allow 192.168.1.0/24; -deny all; -``` - -### 3. Regular Backups - -```bash -#!/bin/bash -# backup.sh - -BACKUP_DIR="/mnt/backup/claude-code-stack" -mkdir -p $BACKUP_DIR - -# Backup volumes -docker run --rm \ - -v claude_config:/data \ - -v $BACKUP_DIR:/backup \ - alpine tar czf /backup/claude-config-$(date +%Y%m%d).tar.gz -C /data . - -echo "Backup complete: $BACKUP_DIR" -``` - -## Monitoring - -### Health Checks - -```bash -# Manual health check -curl http://localhost:3000/health - -# Monitor with watch -watch -n 5 'docker-compose ps && echo "---" && curl -s http://localhost:3000/health' -``` - -### Logging and Metrics - -```bash -# View resource usage -docker stats - -# Monitor over time -docker-compose up -d && \ -sleep 60 && \ -docker stats --no-stream -``` - -## Updating and Maintenance - -### Update Images - -```bash -# Pull latest images -docker-compose pull - -# Rebuild custom image -docker-compose build --no-cache - -# Restart services -docker-compose up -d -``` - -### Clear Disk Space - -```bash -# Remove unused images -docker image prune -a - -# Remove unused volumes -docker volume prune - -# Remove unused networks -docker network prune -``` - -## Support and Resources - -- **Claude Code Agents UI**: https://github.com/Ngxba/claude-code-agents-ui -- **Claude Code Docs**: https://docs.anthropic.com/en/docs/build-with-claude -- **Docker Docs**: https://docs.docker.com/ -- **TrueNAS Documentation**: https://www.truenas.com/docs/ - -## Quick Reference Commands - -```bash -# Start stack -docker-compose up -d - -# Check status -docker-compose ps - -# View logs -docker-compose logs -f - -# Stop stack -docker-compose down - -# Execute command -docker-compose exec agents-ui command - -# Access shell -docker-compose exec agents-ui sh - -# Update -docker-compose pull && docker-compose up -d - -# Backup -docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz - -# Restore database -psql -h localhost -U claude -d claude_agents < backup.sql -``` - ---- - -**Last Updated**: 2026-04-04 -**Stack Version**: 1.0.0 -**Docker Compose Version**: 3.8+