diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 2562045..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,419 +0,0 @@ -# Claude Code + Agents UI Stack - Quick Start Guide - -## 📋 Prerequisites - -- TrueNAS SCALE system running -- Docker and Docker Compose installed on TrueNAS -- Anthropic API Key (get from https://console.anthropic.com/) -- SSH access to TrueNAS (for SSH deployment method) - -## 🚀 Deployment Options - -### Option 1: SSH Deployment (Easiest for TrueNAS) - -This is the recommended method for deploying to TrueNAS. - -#### Setup - -```bash -# 1. Make the deployment script executable -chmod +x deploy-ssh.sh - -# 2. Set your API key -export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here" - -# 3. Deploy to your TrueNAS -./deploy-ssh.sh 192.168.1.100 root tank - -# Parameters: -# 192.168.1.100 = Your TrueNAS IP address -# root = SSH username (default: root) -# tank = Pool name (default: tank) -``` - -That's it! The script will: -- ✓ Create the project directory -- ✓ Upload Docker configuration -- ✓ Configure environment variables -- ✓ Start all services -- ✓ Verify deployment - -#### Access the UI - -Once deployed, access the Agents UI at: -``` -http://192.168.1.100:3000 -``` - ---- - -### Option 2: MCP Deployment (For Advanced Users) - -If you have the TrueNAS MCP server running at `mcp.wilddragon.net`: - -#### Setup - -```bash -# 1. Install dependencies -pip install httpx - -# 2. Make the script executable -chmod +x deploy-mcp.py - -# 3. Deploy via MCP -export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here" -python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank -``` - ---- - -### Option 3: Manual Docker Compose Deployment - -For complete control: - -#### Step 1: SSH into TrueNAS - -```bash -ssh root@192.168.1.100 -``` - -#### Step 2: Create project directory - -```bash -mkdir -p /mnt/tank/docker/claude-code-stack -cd /mnt/tank/docker/claude-code-stack -``` - -#### Step 3: Copy docker-compose.yml - -Create and edit the file: -```bash -cat > docker-compose.yml << 'EOF' -# Paste the content from docker-compose.yml -EOF -``` - -#### Step 4: Configure environment - -```bash -cat > .env << 'EOF' -ANTHROPIC_API_KEY=sk-ant-your-key-here -POSTGRES_PASSWORD=secure-password -NODE_ENV=production -EOF -``` - -#### Step 5: Start services - -```bash -docker-compose up -d -``` - -#### Step 6: Verify - -```bash -docker-compose ps -curl http://localhost:3000 -``` - ---- - -## 📊 Services Overview - -### What Gets Deployed - -| Service | Port | Purpose | Required | -|---------|------|---------|----------| -| **Agents UI** | 3000 | Web interface for agent management | ✓ Yes | -| **Claude Code** | 5000 | Code execution backend | ✓ Yes | -| **PostgreSQL** | 5432 | Data persistence | Optional | -| **Redis** | 6379 | Caching & sessions | Optional | -| **Nginx** | 80/443 | Reverse proxy | Optional | - ---- - -## 🎮 Using the Stack - -### Access the UI - -``` -http://your-truenas-ip:3000 -``` - -### View Logs - -```bash -# SSH into TrueNAS -ssh root@your-truenas-ip - -# Navigate to project -cd /mnt/tank/docker/claude-code-stack - -# View logs -docker-compose logs -f agents-ui -docker-compose logs -f claude-code-backend -``` - -### Run Claude Code Directly - -```bash -# Execute a prompt -docker-compose exec claude-code-backend claude "What files are in the workspace?" - -# Access the CLI -docker-compose exec claude-code-backend bash -``` - -### Stop Services - -```bash -docker-compose down -``` - -### Restart Services - -```bash -docker-compose restart -``` - ---- - -## 🔧 Configuration - -### Environment Variables - -Edit `.env` file to customize: - -```bash -# Your Anthropic API key (REQUIRED) -ANTHROPIC_API_KEY=sk-ant-xxx - -# Database password -POSTGRES_PASSWORD=secure-password - -# Node environment -NODE_ENV=production - -# Claude Code settings -CLAUDE_MODEL=claude-opus-4-1 -RUN_CLAUDE_CODE=true -``` - -### Port Changes - -Want different ports? Edit `docker-compose.yml`: - -```yaml -ports: - - "8000:3000" # Access UI at port 8000 instead -``` - -Then restart: -```bash -docker-compose down && docker-compose up -d -``` - ---- - -## 🐛 Troubleshooting - -### Issue: "Connection refused" on port 3000 - -**Solution:** -```bash -# Check if service is running -docker-compose ps - -# View logs -docker-compose logs agents-ui - -# Restart -docker-compose restart agents-ui - -# Wait a few seconds for startup -sleep 10 -curl http://localhost:3000 -``` - -### Issue: API key not recognized - -**Solution:** -```bash -# Verify .env file -cat .env | grep ANTHROPIC_API_KEY - -# Update if needed -nano .env - -# Restart services -docker-compose restart -``` - -### Issue: Database connection fails - -**Solution:** -```bash -# Check PostgreSQL -docker-compose logs postgres - -# Verify credentials in .env -grep POSTGRES .env - -# Restart database -docker-compose restart postgres -``` - -### Issue: Cannot SSH to TrueNAS - -**Solution:** -```bash -# Check IP address -ping your-truenas-ip - -# Test SSH connection -ssh -v root@your-truenas-ip - -# Check if SSH is enabled on TrueNAS -# System Settings > Services > SSH > Start Automatically -``` - ---- - -## 📈 Performance Tips - -### Increase Memory Allocation - -Edit `docker-compose.yml`: - -```yaml -services: - agents-ui: - deploy: - resources: - limits: - memory: 2G - reservations: - memory: 1G -``` - -### Enable Caching with Redis - -Redis is included in the stack and automatically started. - -### Database Optimization - -```bash -# Increase PostgreSQL connections -docker-compose exec postgres psql -U claude -c "ALTER SYSTEM SET max_connections = 200;" -docker-compose restart postgres -``` - ---- - -## 🔒 Security Recommendations - -### 1. Change Default Passwords - -```bash -# Edit .env -nano .env - -# Change: -# POSTGRES_PASSWORD=changeMe123! -# SESSION_SECRET=your-random-secret -``` - -### 2. Enable SSL/TLS - -Create self-signed certificate: -```bash -openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -``` - -Update `docker-compose.yml` to mount certs. - -### 3. Restrict Network Access - -In TrueNAS, configure firewall to allow only trusted IPs. - -### 4. Regular Backups - -```bash -# Backup configuration -docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > claude-backup.tar.gz - -# Backup database -docker-compose exec postgres pg_dump -U claude claude_agents > backup.sql -``` - ---- - -## 🎯 Next Steps - -1. **Access the UI**: http://your-truenas-ip:3000 -2. **Configure API key**: Check that ANTHROPIC_API_KEY is set -3. **Create your first agent**: Use the Agents UI to create and test agents -4. **Set up workspace**: Mount your projects in `/workspace` -5. **Configure SSH keys**: For git operations (optional) - ---- - -## 📚 Resources - -- **Claude Code Agents UI**: https://github.com/Ngxba/claude-code-agents-ui -- **Claude Documentation**: https://docs.anthropic.com/ -- **Docker Compose Reference**: https://docs.docker.com/compose/compose-file/ -- **TrueNAS Documentation**: https://www.truenas.com/docs/ - ---- - -## 💡 Common Commands - -```bash -# View running services -docker-compose ps - -# Follow logs -docker-compose logs -f - -# Stop everything -docker-compose down - -# Restart everything -docker-compose restart - -# Execute command in container -docker-compose exec agents-ui command - -# Access shell in container -docker-compose exec agents-ui sh - -# Update and restart -docker-compose pull && docker-compose up -d - -# Clean up disk space -docker system prune -a -``` - ---- - -## 🆘 Getting Help - -If you encounter issues: - -1. **Check the logs**: `docker-compose logs -f` -2. **Verify configuration**: `cat .env` -3. **Check connectivity**: `docker-compose exec agents-ui ping -c 1 claude-code-backend` -4. **Review the full guide**: See `DEPLOYMENT_GUIDE.md` - ---- - -**Deployed successfully?** 🎉 - -Next, configure your agents: -1. Open http://your-truenas-ip:3000 -2. Create a new agent -3. Set up your workspace -4. Start automating! - -Happy coding! 🚀