claude-code-stack/README.md

# Claude Code + Agents UI Stack - Complete Package

## 📦 What's Included

This package contains everything needed to deploy a complete Claude Code + Agents UI Docker stack to your TrueNAS SCALE instance.

### Files Overview

```
claude-code-stack/
├── QUICKSTART.md                          # Start here!
├── DEPLOYMENT_GUIDE.md                    # Comprehensive guide
├── docker-compose.yml                     # Main Docker Compose configuration
├── claude-agents-ui-Dockerfile            # Custom Docker image combining UI + Claude Code
├── nginx.conf                             # Reverse proxy configuration
├── claude-code-stack.env                  # Environment variables template
├── deploy-ssh.sh                          # Automated SSH deployment script (RECOMMENDED)
├── deploy-mcp.py                          # MCP-based deployment script
└── README.md                              # This file
```

## 🚀 Quick Start (30 seconds)

```bash
# 1. Set your API key
export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"

# 2. Run the deployment script
chmod +x deploy-ssh.sh
./deploy-ssh.sh 192.168.1.100 root tank

# 3. Access the UI
# Open: http://192.168.1.100:3000
```

## 📋 What Each File Does

### QUICKSTART.md
**Start here if you're in a hurry!**
- 3 deployment methods
- Quick setup instructions
- Troubleshooting tips
- Common commands

### DEPLOYMENT_GUIDE.md
**Complete reference guide**
- Detailed architecture
- Step-by-step setup
- Configuration options
- Monitoring & maintenance
- Security hardening
- Performance tuning

### docker-compose.yml
**Main orchestration file**
Includes:
- Claude Code Agents UI (Nuxt 3 frontend)
- Claude Code Runtime (code execution)
- PostgreSQL (data persistence)
- Redis (caching)
- Nginx (reverse proxy)

All services with:
- Health checks
- Volume management
- Network configuration
- Resource limits

### claude-agents-ui-Dockerfile
**Optional: Combined image**
Builds a single Docker image containing:
- Agents UI (Nuxt 3)
- Claude Code CLI
- Required dependencies
- Non-root user for security

Use this if you prefer building a custom image instead of using pre-built images.

### nginx.conf
**Reverse proxy configuration**
- Load balancing
- SSL/TLS support
- Rate limiting
- Security headers
- WebSocket support
- Static file caching

### claude-code-stack.env
**Environment variables template**
Configure:
- Anthropic API key (REQUIRED)
- Database credentials
- API ports and hosts
- Security settings
- Storage options
- Agent configuration

### deploy-ssh.sh
**Automated SSH deployment** ⭐ RECOMMENDED
- One-command setup
- Validates prerequisites
- Tests SSH connection
- Creates directories
- Uploads files
- Configures environment
- Starts services
- Verifies deployment
- Sets up monitoring

### deploy-mcp.py
**MCP-based deployment**
For advanced users with MCP server running:
- Deploys via MCP protocol
- Async/await operation
- Progress indicators
- Error handling

## 🎯 Deployment Flowchart

```
Start
  │
  ├─→ Choose Method
  │    ├─→ SSH (recommended) → deploy-ssh.sh
  │    ├─→ MCP (advanced) → deploy-mcp.py
  │    └─→ Manual → Use docker-compose.yml directly
  │
  ├─→ Prerequisites
  │    ├─→ API Key ✓
  │    ├─→ SSH access ✓
  │    └─→ Docker on TrueNAS ✓
  │
  ├─→ Deploy Stack
  │    ├─→ Create directory
  │    ├─→ Upload files
  │    ├─→ Configure .env
  │    ├─→ Pull images
  │    └─→ Start services
  │
  ├─→ Verify
  │    ├─→ Check service status
  │    ├─→ Test port 3000
  │    └─→ View logs
  │
  └─→ Access UI
       └─→ http://your-truenas-ip:3000
```

## 🏗️ Architecture

```
Your Computer
     │
     │ (SSH or MCP)
     ▼
TrueNAS SCALE
     │
     ├─→ docker-compose
     │
     └─→ Services:
         ├─→ Claude Code Agents UI (Port 3000)
         │   └─→ Web interface for agent management
         │
         ├─→ Claude Code Backend (Port 5000)
         │   └─→ Code execution environment
         │
         ├─→ PostgreSQL (Port 5432)
         │   └─→ Agent data persistence
         │
         ├─→ Redis (Port 6379)
         │   └─→ Caching & sessions
         │
         └─→ Nginx (Port 80/443)
             └─→ Reverse proxy
```

## 🔐 Security Features

- ✓ Non-root user execution
- ✓ Health checks on all services
- ✓ Security headers via Nginx
- ✓ Rate limiting
- ✓ SSL/TLS support (optional)
- ✓ Environment variable isolation
- ✓ Volume isolation
- ✓ Network isolation

## 📊 Resource Requirements

### Minimum
- RAM: 2GB allocated to Docker
- CPU: 2 cores
- Disk: 10GB free

### Recommended
- RAM: 4GB allocated to Docker
- CPU: 4 cores
- Disk: 20GB free

### Optimal
- RAM: 8GB+ allocated to Docker
- CPU: 8+ cores
- Disk: 50GB+ free

## 🚦 Deployment Status

After running `deploy-ssh.sh`, you'll see:

```
[INFO] Checking prerequisites...
[INFO] Testing SSH connection...
[INFO] Creating project directory on TrueNAS...
[INFO] Uploading Docker configuration files...
[INFO] Configuring environment variables...
[INFO] Deploying Docker stack...
[INFO] Verifying deployment...
========================================
  Claude Code Stack Deployed!
========================================

Access the Agents UI at:
  http://192.168.1.100:3000
```

## 📝 Next Steps

1. **Deploy**: Run `./deploy-ssh.sh your-truenas-ip`
2. **Access**: Open http://your-truenas-ip:3000
3. **Configure**: Set up API keys and workspace
4. **Create**: Build your first agent
5. **Test**: Execute and monitor agent tasks

## 🆘 Common Issues

### Q: SSH connection fails
**A:** Check TrueNAS IP, SSH is enabled, and you have correct credentials.

### Q: Port 3000 not responding
**A:** Wait 30 seconds for startup. Check logs: `docker-compose logs agents-ui`

### Q: API key not recognized
**A:** Verify in .env file and restart: `docker-compose restart`

### Q: PostgreSQL connection fails
**A:** Check credentials match in .env. Run: `docker-compose logs postgres`

See DEPLOYMENT_GUIDE.md for more troubleshooting.

## 📚 Documentation

- **QUICKSTART.md** - Start here for quick setup
- **DEPLOYMENT_GUIDE.md** - Complete reference guide
- **Claude Code Docs** - https://docs.anthropic.com/
- **GitHub Repo** - https://github.com/Ngxba/claude-code-agents-ui

## 🎓 Learning Resources

### Getting Started with Claude Code
```bash
claude --help
claude "What's in the current directory?"
```

### Creating Agents
Use the Agents UI at http://your-truenas-ip:3000 to:
- Create agents
- Configure models
- Set instructions
- Build workflows

### Using Agents
```bash
# View available agents
claude list-agents

# Run an agent
claude run agent-name "prompt"

# Interactive mode
claude chat agent-name
```

## 🔄 Update & Maintenance

### Pull Latest Images
```bash
docker-compose pull
docker-compose up -d
```

### View Logs
```bash
docker-compose logs -f [service]
```

### Backup Data
```bash
docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz
```

### Clean Up
```bash
docker system prune -a
docker volume prune
```

## 📞 Support

For issues or questions:

1. Check **DEPLOYMENT_GUIDE.md** troubleshooting section
2. Review **QUICKSTART.md** for common solutions
3. Check Docker logs: `docker-compose logs`
4. Visit: https://github.com/Ngxba/claude-code-agents-ui/issues
5. See: https://docs.anthropic.com/

## 📄 License

This deployment package is provided as-is. 

- **Claude Code** - Use your Anthropic API key
- **Agents UI** - MIT License (https://github.com/Ngxba/claude-code-agents-ui)
- **Docker Components** - Various open-source licenses

## 🎉 Success!

Once deployed, you'll have:
- ✓ Web interface for agent management
- ✓ Claude Code execution environment
- ✓ Persistent storage with PostgreSQL
- ✓ Caching layer with Redis
- ✓ Reverse proxy with Nginx
- ✓ All integrated and running on TrueNAS

Happy coding! 🚀

---

**Version**: 1.0.0
**Last Updated**: 2026-04-04
**Compatibility**: TrueNAS SCALE, Docker Compose 3.8+