claude-code-stack/CHECKLIST.md

# Claude Code Stack - Pre & Post Deployment Checklist

## ✅ Pre-Deployment Checklist

### Environment Preparation
- [ ] Anthropic API key obtained from https://console.anthropic.com/
- [ ] TrueNAS system is up and running
- [ ] Docker and Docker Compose installed on TrueNAS
  - Verify: `ssh root@truenas-ip "docker --version"`
  - Verify: `ssh root@truenas-ip "docker-compose --version"`
- [ ] SSH access to TrueNAS is working
  - Test: `ssh root@your-truenas-ip "echo 'Connected'"`
- [ ] Sufficient disk space available (minimum 20GB)
  - Check: `ssh root@truenas-ip "df -h"`
- [ ] Sufficient RAM (minimum 4GB allocated to Docker)

### Network Preparation
- [ ] TrueNAS IP address noted: _______________
- [ ] Firewall allows ports 3000, 5000, 5432, 6379, 80, 443
- [ ] No port conflicts on TrueNAS
  - Check: `ssh root@truenas-ip "netstat -tuln | grep LISTEN"`
- [ ] DNS is correctly configured (if accessing via hostname)

### File Preparation
- [ ] All deployment files downloaded
  - [ ] docker-compose.yml
  - [ ] deploy-ssh.sh or deploy-mcp.py
  - [ ] claude-code-stack.env
  - [ ] nginx.conf
  - [ ] Dockerfile (optional)
- [ ] deployment scripts have execute permissions
  - Run: `chmod +x deploy-ssh.sh`
  - Run: `chmod +x deploy-mcp.py`

### System Information (for reference)
- [ ] TrueNAS IP: _______________
- [ ] SSH Username: _______________
- [ ] Pool Name: _______________
- [ ] Anthropic API Key (first 10 chars): _______________
- [ ] PostgreSQL Password (secure): _______________

---

## 🚀 Deployment Execution Checklist

### Method 1: SSH Deployment (Recommended)

- [ ] Set API key environment variable
  ```bash
  export ANTHROPIC_API_KEY="sk-ant-your-key-here"
  ```

- [ ] Run deployment script
  ```bash
  chmod +x deploy-ssh.sh
  ./deploy-ssh.sh 192.168.1.100 root tank
  ```

- [ ] Monitor deployment progress
  - [ ] Directory creation: `✓ created`
  - [ ] Files uploaded: `✓ uploaded`
  - [ ] Docker images pulled: `✓ pulled`
  - [ ] Services started: `✓ started`

- [ ] Record deployment output
  - [ ] Project directory: _______________
  - [ ] Access URL: http://_______________:3000
  - [ ] Start time: _______________
  - [ ] End time: _______________

### Method 2: MCP Deployment

- [ ] Dependencies installed
  ```bash
  pip install httpx
  ```

- [ ] MCP server accessible
  - Test: `curl https://mcp.wilddragon.net/mcp`

- [ ] Run deployment script
  ```bash
  python deploy-mcp.py --mcp-url https://mcp.wilddragon.net/mcp --pool tank
  ```

- [ ] Monitor deployment status
  - [ ] Directory created
  - [ ] Files written
  - [ ] Images pulled
  - [ ] Services started

### Method 3: Manual Deployment

- [ ] SSH into TrueNAS
  ```bash
  ssh root@your-truenas-ip
  ```

- [ ] Create directory
  ```bash
  mkdir -p /mnt/tank/docker/claude-code-stack
  cd /mnt/tank/docker/claude-code-stack
  ```

- [ ] Copy docker-compose.yml
- [ ] Copy .env file and update with API key
- [ ] Verify .env file
  ```bash
  cat .env | grep ANTHROPIC_API_KEY
  ```

- [ ] Start services
  ```bash
  docker-compose pull
  docker-compose up -d
  ```

- [ ] Verify services
  ```bash
  docker-compose ps
  ```

---

## ✅ Post-Deployment Verification

### Immediate Verification (0-2 minutes)

- [ ] Docker services are running
  ```bash
  docker-compose ps
  ```
  Expected output:
  ```
  NAME                    STATUS              PORTS
  claude-agents-ui        Up (healthy)        0.0.0.0:3000->3000/tcp
  claude-code-runtime     Up (healthy)        0.0.0.0:5000->5000/tcp
  claude-postgres         Up (healthy)        0.0.0.0:5432->5432/tcp
  claude-redis            Up (healthy)        0.0.0.0:6379->6379/tcp
  ```

- [ ] All services showing "healthy" status
- [ ] No error messages in deployment output

### Web Interface Verification (2-5 minutes)

- [ ] Access Agents UI
  - URL: http://your-truenas-ip:3000
  - [ ] Page loads successfully
  - [ ] No console errors

- [ ] Check UI is responsive
  - [ ] Can click menu items
  - [ ] Can see available agents
  - [ ] Can see command structure

### Service Health Check (5-10 minutes)

- [ ] Agents UI health check
  ```bash
  curl http://localhost:3000/health
  ```
  Expected: `healthy` response

- [ ] Claude Code backend responding
  ```bash
  docker-compose logs claude-code-backend | tail -20
  ```
  Look for: No error messages

- [ ] PostgreSQL is initialized
  ```bash
  docker-compose exec postgres pg_isready -U claude
  ```
  Expected: `accepting connections`

- [ ] Redis is running
  ```bash
  docker-compose exec redis redis-cli ping
  ```
  Expected: `PONG`

### Configuration Verification

- [ ] .env file is properly configured
  - [ ] ANTHROPIC_API_KEY is set
  - [ ] POSTGRES_PASSWORD is changed from default
  - [ ] SESSION_SECRET is set

- [ ] Volumes are mounted correctly
  ```bash
  docker-compose exec agents-ui ls -la /root/.claude
  docker-compose exec agents-ui ls -la /workspace
  ```

- [ ] Network connectivity between services
  ```bash
  docker-compose exec agents-ui ping -c 1 claude-code-backend
  ```
  Expected: successful ping

### Data Persistence Verification

- [ ] PostgreSQL database is accessible
  ```bash
  docker-compose exec postgres psql -U claude -d claude_agents -c "\dt"
  ```

- [ ] Redis data can be stored and retrieved
  ```bash
  docker-compose exec redis redis-cli SET test_key "test_value"
  docker-compose exec redis redis-cli GET test_key
  ```

---

## 🎯 Initial Configuration Tasks

### First-Time Setup

- [ ] Access Agents UI at http://your-truenas-ip:3000
- [ ] Create initial agent
- [ ] Test agent with simple prompt
- [ ] Configure workspace directory
- [ ] Set up SSH keys for git operations (optional)

### Authentication Setup

- [ ] Verify Claude Code authentication
  ```bash
  docker-compose exec claude-code-backend claude auth status
  ```

- [ ] If needed, re-authenticate
  ```bash
  docker-compose exec claude-code-backend claude auth login
  ```

### Workspace Configuration

- [ ] Create workspace structure
  ```bash
  docker-compose exec agents-ui mkdir -p /workspace/{projects,agents,tools}
  ```

- [ ] Mount external projects (if applicable)
  ```bash
  # Update docker-compose.yml volumes section
  ```

---

## 🔒 Security Post-Deployment Tasks

### Immediate Security

- [ ] Change PostgreSQL password
  ```bash
  docker-compose exec postgres psql -U claude -c "ALTER USER claude WITH PASSWORD 'new-password';"
  ```

- [ ] Update SESSION_SECRET in .env
  ```bash
  SESSION_SECRET=$(openssl rand -base64 32)
  # Update .env and restart
  ```

- [ ] Restrict SSH access to TrueNAS (if possible)

### Recommended Security

- [ ] Enable SSL/TLS for web interface
- [ ] Configure firewall rules on TrueNAS
- [ ] Set up regular backups
- [ ] Configure log rotation
- [ ] Review and harden Nginx configuration

---

## 📊 Monitoring & Logging Setup

### Log Aggregation

- [ ] Set up log monitoring
  ```bash
  docker-compose logs -f
  ```

- [ ] Configure log rotation (optional)

### Monitoring Tools

- [ ] Set up resource monitoring
  ```bash
  docker stats
  ```

- [ ] Configure alerts (optional)

### Backup Strategy

- [ ] Create backup script
  ```bash
  #!/bin/bash
  docker-compose exec claude-code-backend tar czf - -C /root .claude | gzip > backup.tar.gz
  docker-compose exec postgres pg_dump -U claude claude_agents > backup.sql
  ```

- [ ] Schedule daily backups
- [ ] Test backup restoration

---

## 🚨 Troubleshooting Post-Deployment

### If Services Won't Start

- [ ] Check Docker daemon is running
  ```bash
  docker ps
  ```

- [ ] Check logs for errors
  ```bash
  docker-compose logs agents-ui
  docker-compose logs claude-code-backend
  ```

- [ ] Verify API key format
  ```bash
  grep ANTHROPIC_API_KEY .env
  ```

- [ ] Check port availability
  ```bash
  netstat -tuln | grep 3000
  ```

### If UI Won't Load

- [ ] Verify service is running
  ```bash
  docker-compose ps agents-ui
  ```

- [ ] Check network connectivity
  ```bash
  curl -v http://localhost:3000
  ```

- [ ] Review browser console for errors
- [ ] Check DNS resolution
  ```bash
  nslookup your-truenas-ip
  ```

### If Claude Code Won't Execute

- [ ] Verify API key is correct
  ```bash
  docker-compose exec claude-code-backend echo $ANTHROPIC_API_KEY
  ```

- [ ] Check authentication status
  ```bash
  docker-compose exec claude-code-backend claude auth status
  ```

- [ ] Test with simple prompt
  ```bash
  docker-compose exec claude-code-backend claude "hello"
  ```

---

## 📋 Documentation & Handoff

### Documentation Created

- [ ] Deployment notes saved
- [ ] Custom configuration documented
- [ ] Access credentials stored securely
- [ ] Network diagram created (if complex setup)

### Team Handoff (if applicable)

- [ ] Access credentials shared securely
- [ ] Deployment process documented
- [ ] Troubleshooting guide provided
- [ ] Emergency contact information shared

---

## 🎉 Final Checklist

### Deployment Success Criteria

- [ ] All services running and healthy
- [ ] Web UI accessible and responsive
- [ ] Claude Code can execute prompts
- [ ] Database is initialized
- [ ] Redis cache is working
- [ ] Logs show no critical errors
- [ ] All required ports are open
- [ ] API key is properly configured

### Deployment Complete When

- [x] Docker Compose stack deployed
- [x] All services are healthy
- [x] Web interface is accessible
- [x] Claude Code is responding
- [x] Database is initialized
- [x] Backups are configured
- [x] Security measures in place
- [x] Documentation complete

---

## 📝 Sign-Off

**Deployment Date**: _______________
**Deployed By**: _______________
**System**: TrueNAS SCALE
**Pool**: _______________
**Project Directory**: _______________
**Access URL**: http://_______________:3000

**Notes**:
```
_____________________________________________________________________________
_____________________________________________________________________________
_____________________________________________________________________________
```

**Verification Complete**: ☐ Yes ☐ No

**Ready for Production**: ☐ Yes ☐ No (if No, list remaining items below)

```
_____________________________________________________________________________
_____________________________________________________________________________
```

---

**Deployment Package Version**: 1.0.0
**Last Updated**: 2026-04-04
**Checklist Version**: 1.0