Remove unneeded file: QUICKSTART.md
This commit is contained in:
parent
072e65cbff
commit
65236a11f2
1 changed files with 0 additions and 419 deletions
419
QUICKSTART.md
419
QUICKSTART.md
|
|
@ -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! 🚀
|
|
||||||
Loading…
Reference in a new issue