zgaetano/claude-code-stack
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code-stack/CHECKLIST.md
zgaetano 5881d0f0df Upload files to "/"
2026-04-04 14:32:22 -04:00

10 KiB
Raw Blame History

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

    export ANTHROPIC_API_KEY="sk-ant-your-key-here"

  • Run deployment script

    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

Method 2: MCP Deployment

  • Dependencies installed

    pip install httpx

  • MCP server accessible

    • Test: curl https://mcp.wilddragon.net/mcp

  • Run deployment script

    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

    ssh root@your-truenas-ip

  • Create directory

    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

    cat .env | grep ANTHROPIC_API_KEY

  • Start services

    docker-compose pull
docker-compose up -d

  • Verify services

    docker-compose ps

✅ Post-Deployment Verification

Immediate Verification (0-2 minutes)

  • Docker services are running

    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

  • 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

    curl http://localhost:3000/health

    Expected: healthy response

  • Claude Code backend responding

    docker-compose logs claude-code-backend | tail -20

    Look for: No error messages

  • PostgreSQL is initialized

    docker-compose exec postgres pg_isready -U claude

    Expected: accepting connections

  • Redis is running

    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

    docker-compose exec agents-ui ls -la /root/.claude
docker-compose exec agents-ui ls -la /workspace

  • Network connectivity between services

    docker-compose exec agents-ui ping -c 1 claude-code-backend

    Expected: successful ping

Data Persistence Verification

  • PostgreSQL database is accessible

    docker-compose exec postgres psql -U claude -d claude_agents -c "\dt"

  • Redis data can be stored and retrieved

    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

    docker-compose exec claude-code-backend claude auth status

  • If needed, re-authenticate

    docker-compose exec claude-code-backend claude auth login

Workspace Configuration

  • Create workspace structure

    docker-compose exec agents-ui mkdir -p /workspace/{projects,agents,tools}

  • Mount external projects (if applicable)

    # Update docker-compose.yml volumes section

🔒 Security Post-Deployment Tasks

Immediate Security

  • Change PostgreSQL password

    docker-compose exec postgres psql -U claude -c "ALTER USER claude WITH PASSWORD 'new-password';"

  • Update SESSION_SECRET in .env

    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

    docker-compose logs -f

  • Configure log rotation (optional)

Monitoring Tools

  • Set up resource monitoring

    docker stats

  • Configure alerts (optional)

Backup Strategy

  • Create backup script

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

    docker ps

  • Check logs for errors

    docker-compose logs agents-ui
docker-compose logs claude-code-backend

  • Verify API key format

    grep ANTHROPIC_API_KEY .env

  • Check port availability

    netstat -tuln | grep 3000

If UI Won't Load

  • Verify service is running

    docker-compose ps agents-ui

  • Check network connectivity

    curl -v http://localhost:3000

  • Review browser console for errors

  • Check DNS resolution

    nslookup your-truenas-ip

If Claude Code Won't Execute

  • Verify API key is correct

    docker-compose exec claude-code-backend echo $ANTHROPIC_API_KEY

  • Check authentication status

    docker-compose exec claude-code-backend claude auth status

  • Test with simple prompt

    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

  • Docker Compose stack deployed
  • All services are healthy
  • Web interface is accessible
  • Claude Code is responding
  • Database is initialized
  • Backups are configured
  • Security measures in place
  • 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