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

Implement claude auth login + repo cleanup

Browse source 
- Dockerfile: entrypoint bootstraps ~/.claude/.credentials.json from ANTHROPIC_API_KEY (non-interactive auth, no manual claude auth login needed); fix build stage; add jq
- docker-compose.yml: fix build context; update model to claude-sonnet-4-6; pass ANTHROPIC_MODEL env; fix backend healthcheck
- claude-code-stack.env: update models to claude-sonnet-4-6; add CLAUDE_CONFIG_DIR; document auth strategy
- deploy-ssh.sh: add verify_auth step; fix file aliasing on remote; auto-generate secrets; better output
- README.md: document full auth flow end-to-end; add useful commands table
This commit is contained in:
Zac Gaetano 2026-04-04 15:09:27 -04:00
parent 804b1d35b6
commit 3a666d608b
1 changed files with 217 additions and 337 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

554
README.md
View file

@ -1,341 +1,221 @@
# Claude Code + Agents UI Stack - Complete Package
# Claude Code + Agents UI Stack
## 📦 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! 🚀
A self-hosted Docker stack that combines the [claude-code-agents-ui](https://github.com/Ngxba/claude-code-agents-ui) frontend with the Claude Code CLI runtime, designed for TrueNAS SCALE deployment.
---
**Version**: 1.0.0
**Last Updated**: 2026-04-04
**Compatibility**: TrueNAS SCALE, Docker Compose 3.8+
## What's Included
| File | Purpose |
|------|---------|
| `claude-agents-ui-Dockerfile` | Multi-stage image: builds the Nuxt 3 UI + installs Claude Code CLI |
| `claude-code-stack-docker-compose.yml` | Orchestrates all services (UI, runtime, Postgres, Redis, Nginx) |
| `claude-code-stack.env` | Environment variable template — copy to `.env` before deploying |
| `nginx.conf` | Reverse-proxy config (SSL-ready) |
| `deploy-ssh.sh` | One-command SSH deployment to TrueNAS ⭐ recommended |
| `deploy-mcp.py` | MCP-based deployment (advanced) |
| `QUICKSTART.md` | 5-minute setup guide |
| `DEPLOYMENT_GUIDE.md` | Full reference |
| `CHECKLIST.md` | Pre/post-deployment checklist |
---
## Quick Start
```bash
# 1. Set your Anthropic API key (get one at https://console.anthropic.com/)
export ANTHROPIC_API_KEY="sk-ant-..."
# 2. Deploy to TrueNAS
chmod +x deploy-ssh.sh
./deploy-ssh.sh 192.168.1.100 root tank
# 3. Open the UI
open http://192.168.1.100:3000
```
---
## Authentication
Claude Code requires authentication to execute prompts. This stack implements **non-interactive auth** so no manual `claude auth login` step is needed.
### How it works
1. You provide your `ANTHROPIC_API_KEY` in `.env` (or via environment variable).
2. The `agents-ui` container entrypoint writes `~/.claude/.credentials.json` containing your API key on first start.
3. The Claude Code CLI reads this file and is ready to execute without any interactive login step.
4. The `claude-code-backend` container uses `ANTHROPIC_API_KEY` directly at runtime.
### Manual auth (optional)
If you prefer OAuth-based login (tied to a Claude.ai subscription rather than pay-per-token API):
```bash
# SSH into TrueNAS
ssh root@192.168.1.100
# Run interactive login inside the container
cd /mnt/tank/docker/claude-code-stack
docker-compose exec agents-ui claude auth login
```
The credentials are stored in the `claude-config` Docker volume and persist across restarts.
### Auth status check
```bash
docker-compose exec agents-ui claude auth status
```
---
## Architecture
```
Your Browser
│
▼
Nginx :80/:443
│
├──► Agents UI (Nuxt 3) :3000 ──► ~/.claude/ volume
│ │
│ └──► Claude Code Backend :5000
│
├──► PostgreSQL :5432
└──► Redis :6379
```
All services share two Docker volumes:
- `claude-config` — Claude credentials, agents, commands, skills, workflows
- `workspace` — Project files for agent execution
---
## Configuration
Copy the env template and fill in your values:
```bash
cp claude-code-stack.env .env
nano .env # Set ANTHROPIC_API_KEY and change POSTGRES_PASSWORD / SESSION_SECRET
```
### Key variables
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | **Yes** | Your Anthropic API key |
| `CLAUDE_MODEL` | No | Model to use (default: `claude-sonnet-4-6`) |
| `POSTGRES_PASSWORD` | **Yes** | Change from default before production |
| `SESSION_SECRET` | **Yes** | Random string — run `openssl rand -base64 32` |
Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001`
---
## Deployment Methods
### Method 1: SSH (recommended)
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
./deploy-ssh.sh 192.168.1.100 root tank
```
The script:
- Validates prerequisites
- Tests SSH connectivity
- Creates project directory on TrueNAS
- Uploads all files
- Writes `.env` with auto-generated secrets
- Builds and starts all services
- Verifies Claude auth inside containers
### Method 2: Manual
```bash
# SSH into TrueNAS
ssh root@192.168.1.100
mkdir -p /mnt/tank/docker/claude-code-stack
cd /mnt/tank/docker/claude-code-stack
# Upload files, then:
cp claude-code-stack.env .env
cp claude-code-stack-docker-compose.yml docker-compose.yml
cp claude-agents-ui-Dockerfile Dockerfile
nano .env # Set your API key
docker-compose build
docker-compose up -d
```
### Method 3: MCP
```bash
pip install httpx
python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank
```
---
## Useful Commands
```bash
# View all logs
docker-compose logs -f
# View just the UI logs
docker-compose logs -f agents-ui
# Check auth status
docker-compose exec agents-ui claude auth status
# Re-authenticate (interactive OAuth)
docker-compose exec agents-ui claude auth login
# Restart a service
docker-compose restart agents-ui
# Pull latest images
docker-compose pull && docker-compose up -d
# Stop everything
docker-compose down
# Stop and remove volumes (WARNING: deletes all data)
docker-compose down -v
```
---
## Resource Requirements
| Tier | RAM | CPU | Disk |
|------|-----|-----|------|
| Minimum | 2 GB | 2 cores | 10 GB |
| Recommended | 4 GB | 4 cores | 20 GB |
| Optimal | 8 GB+ | 8+ cores | 50 GB+ |
---
## Security Notes
- Change `POSTGRES_PASSWORD` from the default before production
- Generate a proper `SESSION_SECRET`: `openssl rand -base64 32`
- The `.env` file is chmod 600 — never commit it to version control
- The `claude-config` volume contains your API credentials — back it up securely
- Consider restricting Nginx to internal network access only
---
## Links
- [Agents UI source](https://github.com/Ngxba/claude-code-agents-ui)
- [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code)
- [Anthropic console](https://console.anthropic.com/)
---
**Version:** 1.1.0 | **Updated:** 2026-04-04 | **Compatibility:** TrueNAS SCALE, Docker Compose 3.8+