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