zgaetano/claude-code-stack

Fork 0

zgaetano 068e6e9f5e Upload files to "/"

2026-04-04 14:34:56 -04:00

12 KiB

Raw Blame History

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

ssh root@your-truenas-ip
# or use your specific TrueNAS user

Step 2: Create project directory

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:

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):

# 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

cp claude-code-stack.env .env
nano .env  # or vim .env

Update these critical variables:

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

# 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

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

// 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:

Open Portainer at https://your-truenas-ip:9000
Go to: Stacks > Add Stack
Upload or paste the docker-compose.yml content
Set environment variables via the Web Editor
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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

services:
  agents-ui:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Enable Redis Caching

# Uncomment Redis in docker-compose.yml
# Set REDIS_HOST=redis in .env
docker-compose up -d redis

Database Optimization

# 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

# 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

# Allow only specific IPs to Nginx
# In nginx.conf, add to each location:
allow 192.168.1.0/24;
deny all;

3. Regular Backups

#!/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

# 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

# View resource usage
docker stats

# Monitor over time
docker-compose up -d && \
sleep 60 && \
docker stats --no-stream

Updating and Maintenance

Update Images

# Pull latest images
docker-compose pull

# Rebuild custom image
docker-compose build --no-cache

# Restart services
docker-compose up -d

Clear Disk Space

# 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

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

12 KiB Raw Blame History