# 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+