504 lines
12 KiB
Markdown
504 lines
12 KiB
Markdown
# Claude Code + Agents UI Docker Stack Deployment Guide
|
|
|
|
## Overview
|
|
|
|
This guide covers deploying a complete Docker stack on your TrueNAS SCALE instance that combines:
|
|
- **Claude Code Agents UI** (Nuxt 3 frontend for agent orchestration)
|
|
- **Claude Code Runtime** (Backend for code execution)
|
|
- **PostgreSQL** (Optional: for agent data persistence)
|
|
- **Redis** (Optional: for caching)
|
|
- **Nginx** (Optional: reverse proxy)
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
- TrueNAS SCALE with Docker/Portainer running
|
|
- Minimum 4GB RAM allocated to Docker
|
|
- At least 20GB free disk space
|
|
- Anthropic API key (get from https://console.anthropic.com/)
|
|
|
|
### Network Requirements
|
|
- Port 3000 (Agents UI)
|
|
- Port 5000 (Claude Code API - optional)
|
|
- Port 80/443 (Nginx - optional)
|
|
- Port 5432 (PostgreSQL - optional)
|
|
- Port 6379 (Redis - optional)
|
|
|
|
## Deployment Methods
|
|
|
|
### Method 1: SSH Deployment (Recommended for TrueNAS)
|
|
|
|
#### Step 1: SSH into your TrueNAS system
|
|
|
|
```bash
|
|
ssh root@your-truenas-ip
|
|
# or use your specific TrueNAS user
|
|
```
|
|
|
|
#### Step 2: Create project directory
|
|
|
|
```bash
|
|
mkdir -p /mnt/pool-name/docker/claude-code-stack
|
|
cd /mnt/pool-name/docker/claude-code-stack
|
|
```
|
|
|
|
#### Step 3: Clone/create Docker files
|
|
|
|
Option A: Clone the entire repo with compose file:
|
|
```bash
|
|
git clone https://github.com/Ngxba/claude-code-agents-ui.git
|
|
cd claude-code-agents-ui
|
|
```
|
|
|
|
Option B: Copy the provided docker-compose.yml (recommended for your setup):
|
|
```bash
|
|
# Copy the provided files to this directory
|
|
# - docker-compose.yml
|
|
# - claude-code-stack.env
|
|
# - nginx.conf
|
|
# - Dockerfile (if using combined image)
|
|
```
|
|
|
|
#### Step 4: Configure environment variables
|
|
|
|
```bash
|
|
cp claude-code-stack.env .env
|
|
nano .env # or vim .env
|
|
```
|
|
|
|
Update these critical variables:
|
|
```env
|
|
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here
|
|
POSTGRES_PASSWORD=your-secure-password
|
|
SESSION_SECRET=your-random-session-secret
|
|
```
|
|
|
|
#### Step 5: Deploy with Docker Compose
|
|
|
|
```bash
|
|
# Pull latest images
|
|
docker-compose pull
|
|
|
|
# Build custom image (if using combined Dockerfile)
|
|
docker-compose build --no-cache
|
|
|
|
# Start all services
|
|
docker-compose up -d
|
|
|
|
# Check status
|
|
docker-compose ps
|
|
```
|
|
|
|
#### Step 6: Verify deployment
|
|
|
|
```bash
|
|
# Check logs
|
|
docker-compose logs -f agents-ui
|
|
docker-compose logs -f claude-code-backend
|
|
|
|
# Test Claude Code UI
|
|
curl http://localhost:3000
|
|
|
|
# Test Claude Code API
|
|
curl http://localhost:5000/health 2>/dev/null || echo "API not yet responsive"
|
|
```
|
|
|
|
### Method 2: TrueNAS MCP Deployment
|
|
|
|
If you have the TrueNAS MCP server configured:
|
|
|
|
```javascript
|
|
// Example: Using TrueNAS MCP to deploy
|
|
|
|
await mcp.call('truenas:create_dataset', {
|
|
parent: 'pool-name',
|
|
name: 'docker/claude-code-stack'
|
|
});
|
|
|
|
await mcp.call('truenas:list_directory', {
|
|
path: '/mnt/pool-name/docker/claude-code-stack'
|
|
});
|
|
|
|
// Write Docker Compose file via MCP
|
|
// (Use ssh_ssh_exec for Docker commands)
|
|
```
|
|
|
|
### Method 3: Portainer UI Deployment
|
|
|
|
If using Portainer on TrueNAS:
|
|
|
|
1. **Open Portainer** at `https://your-truenas-ip:9000`
|
|
2. **Go to: Stacks > Add Stack**
|
|
3. **Upload or paste** the docker-compose.yml content
|
|
4. **Set environment variables** via the Web Editor
|
|
5. **Deploy**
|
|
|
|
## Stack Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Claude Code Stack │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────────┐ ┌────────────────────┐ │
|
|
│ │ Nginx (Port 80) │◄───────►│ Agents UI │ │
|
|
│ │ (optional) │ │ (Port 3000) │ │
|
|
│ └──────────────────┘ ├────────────────────┤ │
|
|
│ │ - Agent Management │ │
|
|
│ │ - Chat Interface │ │
|
|
│ ┌──────────────────┐ │ - Workflow Builder │ │
|
|
│ │ Claude Code │ └────────────────────┘ │
|
|
│ │ Backend (5000) │ │
|
|
│ │ │ ┌────────────────────┐ │
|
|
│ │ - Code Execution │◄───────►│ PostgreSQL │ │
|
|
│ │ - File Access │ │ (Port 5432) │ │
|
|
│ │ - Shell Commands │ │ (optional) │ │
|
|
│ └──────────────────┘ └────────────────────┘ │
|
|
│ │ │ │
|
|
│ └──────────────┬───────────────┘ │
|
|
│ │ │
|
|
│ ┌─────▼──────┐ │
|
|
│ │ Redis │ │
|
|
│ │ (6379) │ │
|
|
│ │ (optional) │ │
|
|
│ └────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────┐ │
|
|
│ │ Shared Volumes │ │
|
|
│ │ - /workspace (projects) │ │
|
|
│ │ - /root/.claude (config) │ │
|
|
│ └────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Post-Deployment Setup
|
|
|
|
### 1. Initialize Claude Code Configuration
|
|
|
|
```bash
|
|
docker-compose exec claude-code-backend bash
|
|
|
|
# Inside container:
|
|
claude auth login
|
|
# Follow the authentication flow
|
|
|
|
# Create initial .claude directory structure
|
|
mkdir -p ~/.claude/agents ~/.claude/skills ~/.claude/commands
|
|
cd ~/.claude
|
|
```
|
|
|
|
### 2. Configure Agents UI
|
|
|
|
The Agents UI will automatically detect:
|
|
- Your Claude configuration at `~/.claude`
|
|
- Available agents and commands
|
|
- Environment setup
|
|
|
|
Access it at: `http://your-truenas-ip:3000`
|
|
|
|
### 3. Set Up Project Workspace
|
|
|
|
```bash
|
|
# Create workspace structure
|
|
docker-compose exec agents-ui bash -c "mkdir -p /workspace/{projects,agents,tools}"
|
|
|
|
# Mount your projects (example)
|
|
docker-compose exec agents-ui bash -c "ln -s /mnt/shared/projects /workspace/projects"
|
|
```
|
|
|
|
### 4. Configure SSH Keys (Optional but Recommended)
|
|
|
|
For agents to perform git operations:
|
|
|
|
```bash
|
|
docker-compose exec claude-code-backend bash
|
|
|
|
# Inside container:
|
|
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""
|
|
|
|
# Copy public key to your GitHub/GitLab:
|
|
cat ~/.ssh/id_rsa.pub
|
|
```
|
|
|
|
## Common Operations
|
|
|
|
### Start/Stop Stack
|
|
|
|
```bash
|
|
# Start
|
|
docker-compose up -d
|
|
|
|
# Stop
|
|
docker-compose down
|
|
|
|
# Stop with volume preservation
|
|
docker-compose down --remove-orphans
|
|
|
|
# Full reset (CAUTION: removes volumes)
|
|
docker-compose down -v
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Specific service
|
|
docker-compose logs -f agents-ui
|
|
docker-compose logs -f claude-code-backend
|
|
|
|
# Follow errors only
|
|
docker-compose logs -f --tail=100 | grep -i error
|
|
```
|
|
|
|
### Execute Commands in Container
|
|
|
|
```bash
|
|
# Access Agents UI shell
|
|
docker-compose exec agents-ui sh
|
|
|
|
# Access Claude Code shell
|
|
docker-compose exec claude-code-backend bash
|
|
|
|
# Run Claude Code directly
|
|
docker-compose exec claude-code-backend claude "your prompt here"
|
|
```
|
|
|
|
### Backup and Restore
|
|
|
|
```bash
|
|
# Backup volumes
|
|
docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > claude-backup.tar.gz
|
|
|
|
# Backup workspace
|
|
tar czf workspace-backup.tar.gz workspace/
|
|
|
|
# Restore
|
|
tar xzf claude-backup.tar.gz -C workspace/
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: Connection refused on port 3000
|
|
|
|
```bash
|
|
# Check if service is running
|
|
docker-compose ps
|
|
|
|
# Check service logs
|
|
docker-compose logs agents-ui
|
|
|
|
# Restart service
|
|
docker-compose restart agents-ui
|
|
```
|
|
|
|
### Issue: ANTHROPIC_API_KEY not recognized
|
|
|
|
```bash
|
|
# Verify .env file exists and has correct key
|
|
cat .env | grep ANTHROPIC_API_KEY
|
|
|
|
# Pass key directly in docker-compose command
|
|
ANTHROPIC_API_KEY=your-key docker-compose up -d
|
|
```
|
|
|
|
### Issue: PostgreSQL connection fails
|
|
|
|
```bash
|
|
# Check if postgres is ready
|
|
docker-compose exec postgres pg_isready -U claude
|
|
|
|
# Check credentials in .env
|
|
grep POSTGRES .env
|
|
|
|
# View postgres logs
|
|
docker-compose logs postgres
|
|
```
|
|
|
|
### Issue: Agents UI can't find Claude config
|
|
|
|
```bash
|
|
# Verify mount
|
|
docker-compose exec agents-ui ls -la /root/.claude/
|
|
|
|
# Check permissions
|
|
docker-compose exec agents-ui stat /root/.claude
|
|
|
|
# Ensure volume is created
|
|
docker volume ls | grep claude
|
|
```
|
|
|
|
## Performance Tuning
|
|
|
|
### Increase Resource Limits
|
|
|
|
Edit docker-compose.yml:
|
|
|
|
```yaml
|
|
services:
|
|
agents-ui:
|
|
deploy:
|
|
resources:
|
|
limits:
|
|
cpus: '2'
|
|
memory: 2G
|
|
reservations:
|
|
cpus: '1'
|
|
memory: 1G
|
|
```
|
|
|
|
### Enable Redis Caching
|
|
|
|
```bash
|
|
# Uncomment Redis in docker-compose.yml
|
|
# Set REDIS_HOST=redis in .env
|
|
docker-compose up -d redis
|
|
```
|
|
|
|
### Database Optimization
|
|
|
|
```bash
|
|
# Increase PostgreSQL max connections
|
|
docker-compose exec postgres psql -U claude -c "ALTER SYSTEM SET max_connections = 200;"
|
|
docker-compose restart postgres
|
|
```
|
|
|
|
## Security Hardening
|
|
|
|
### 1. Enable SSL/TLS
|
|
|
|
```bash
|
|
# Generate self-signed certificate (for testing)
|
|
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
|
|
|
|
# Or use Let's Encrypt with certbot
|
|
mkdir -p certs
|
|
# Place your cert.pem and key.pem in ./certs/
|
|
```
|
|
|
|
Update docker-compose.yml to mount certs.
|
|
|
|
### 2. Restrict Network Access
|
|
|
|
```bash
|
|
# Allow only specific IPs to Nginx
|
|
# In nginx.conf, add to each location:
|
|
allow 192.168.1.0/24;
|
|
deny all;
|
|
```
|
|
|
|
### 3. Regular Backups
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# backup.sh
|
|
|
|
BACKUP_DIR="/mnt/backup/claude-code-stack"
|
|
mkdir -p $BACKUP_DIR
|
|
|
|
# Backup volumes
|
|
docker run --rm \
|
|
-v claude_config:/data \
|
|
-v $BACKUP_DIR:/backup \
|
|
alpine tar czf /backup/claude-config-$(date +%Y%m%d).tar.gz -C /data .
|
|
|
|
echo "Backup complete: $BACKUP_DIR"
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
### Health Checks
|
|
|
|
```bash
|
|
# Manual health check
|
|
curl http://localhost:3000/health
|
|
|
|
# Monitor with watch
|
|
watch -n 5 'docker-compose ps && echo "---" && curl -s http://localhost:3000/health'
|
|
```
|
|
|
|
### Logging and Metrics
|
|
|
|
```bash
|
|
# View resource usage
|
|
docker stats
|
|
|
|
# Monitor over time
|
|
docker-compose up -d && \
|
|
sleep 60 && \
|
|
docker stats --no-stream
|
|
```
|
|
|
|
## Updating and Maintenance
|
|
|
|
### Update Images
|
|
|
|
```bash
|
|
# Pull latest images
|
|
docker-compose pull
|
|
|
|
# Rebuild custom image
|
|
docker-compose build --no-cache
|
|
|
|
# Restart services
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Clear Disk Space
|
|
|
|
```bash
|
|
# Remove unused images
|
|
docker image prune -a
|
|
|
|
# Remove unused volumes
|
|
docker volume prune
|
|
|
|
# Remove unused networks
|
|
docker network prune
|
|
```
|
|
|
|
## Support and Resources
|
|
|
|
- **Claude Code Agents UI**: https://github.com/Ngxba/claude-code-agents-ui
|
|
- **Claude Code Docs**: https://docs.anthropic.com/en/docs/build-with-claude
|
|
- **Docker Docs**: https://docs.docker.com/
|
|
- **TrueNAS Documentation**: https://www.truenas.com/docs/
|
|
|
|
## Quick Reference Commands
|
|
|
|
```bash
|
|
# Start stack
|
|
docker-compose up -d
|
|
|
|
# Check status
|
|
docker-compose ps
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# Stop stack
|
|
docker-compose down
|
|
|
|
# Execute command
|
|
docker-compose exec agents-ui command
|
|
|
|
# Access shell
|
|
docker-compose exec agents-ui sh
|
|
|
|
# Update
|
|
docker-compose pull && docker-compose up -d
|
|
|
|
# Backup
|
|
docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz
|
|
|
|
# Restore database
|
|
psql -h localhost -U claude -d claude_agents < backup.sql
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-04-04
|
|
**Stack Version**: 1.0.0
|
|
**Docker Compose Version**: 3.8+
|