419 lines
7.4 KiB
Markdown
419 lines
7.4 KiB
Markdown
# 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! 🚀
|