zgaetano/claude-code-stack
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove unneeded file: DEPLOYMENT_GUIDE.md

Browse source
This commit is contained in:
Zac Gaetano 2026-04-04 15:10:25 -04:00
parent 941520db35
commit 072e65cbff
1 changed files with 0 additions and 504 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

504
DEPLOYMENT_GUIDE.md
View file

@ -1,504 +0,0 @@
# 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+