claudetools/NEW_MACHINE_SETUP.md

# New Machine Setup - Complete ClaudeTools Clone (Cross-Platform)

This guide will help you set up a complete, identical ClaudeTools environment on a new machine (Windows or Mac).

**Platform-Specific Notes:**
- Windows commands shown as: `Windows> command`
- Mac/Linux commands shown as: `Mac> command`
- When only one command shown, it works on both platforms

---

## Prerequisites

**Required Software (All Platforms):**
- Git (for cloning repository)
- Python 3.9+ (for ClaudeTools API)
- Node.js/npm (for MCP servers)
- Claude Code CLI installed
- SSH client (built-in on Mac/Linux, use Git Bash or OpenSSH on Windows)

**Installation:**
```bash
# Mac (using Homebrew)
Mac> brew install git python node

# Windows (using winget or Chocolatey)
Windows> winget install Git.Git Python.Python.3.11 OpenJS.NodeJS
# OR
Windows> choco install git python nodejs
```

---

## Step 1: Clone Repository from Gitea

**Choose Your Project Location:**
```bash
# Windows
Windows> cd D:\
Windows> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Windows> cd ClaudeTools

# Mac
Mac> cd ~/Projects  # or wherever you want it
Mac> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Mac> cd ClaudeTools
```

**Note:** You'll need SSH access to the Gitea server (172.16.3.20:2222)

**For This Guide:**
- Windows path: `D:\ClaudeTools`
- Mac path: `~/Projects/ClaudeTools` (adjust as needed)

---

## Step 2: Set Up Python Virtual Environment

```bash
# Create virtual environment (both platforms)
python -m venv api/venv

# Activate virtual environment
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Install Python dependencies (both platforms, once activated)
pip install -r requirements.txt

# Install development dependencies (if needed)
pip install -r requirements-dev.txt
```

**Verify Activation:**
```bash
# You should see (venv) in your prompt
# Check Python location:
Windows> where python
Mac> which python
# Should show path inside api/venv/
```

---

## Step 3: Configure Environment Variables

**Copy Environment Template:**
```bash
Windows> copy .env.example .env
Mac> cp .env.example .env
```

**Edit .env:**
```bash
Windows> notepad .env
Mac> nano .env  # or vim .env, or use VS Code: code .env
```

**Required Variables in .env:**
```ini
# Database Configuration
DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4

# JWT Configuration
JWT_SECRET_KEY=your-jwt-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Encryption Configuration
ENCRYPTION_KEY=your-fernet-encryption-key-here

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
```

**Get actual values from credentials.md in the repository!**

---

## Step 4: Set Up MCP Servers

The `.mcp.json` file needs platform-specific paths.

**Windows - Edit `.mcp.json`:**
```json
{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}
```

**Mac - Edit `.mcp.json`:**
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourusername/Projects/ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}
```

**Important for Mac:** Update the filesystem path to match your actual ClaudeTools location!

**Verify npm is installed:**
```bash
npm --version
# Should show version number (18.0.0 or higher)
```

**MCP servers will auto-install on first use via npx**

---

## Step 5: Test Database Connection

```bash
# Activate venv if not already active
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Test database connection (both platforms)
python test_db_connection.py
```

**Expected output:** Connection successful to 172.16.3.30:3306/claudetools

**Note:** Ensure you have network access to 172.16.3.30:3306 (MariaDB server)

---

## Step 6: Run Database Migrations (if needed)

```bash
# Check current migration status (both platforms)
alembic current

# Upgrade to latest (if needed)
alembic upgrade head
```

---

## Step 7: Test API Server

```bash
# Activate venv first
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Start the API server (both platforms)
python -m api.main

# Or use uvicorn directly
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
```

**Test endpoints:**
- Local: http://localhost:8000/api/docs
- Network: http://172.16.3.30:8001/api/docs (if running on RMM server)

**Stop Server:** Press Ctrl+C

---

## Step 8: Configure SSH Keys for Infrastructure

**Generate SSH Key (if you don't have one):**
```bash
# Both platforms
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter to accept default location
# Enter passphrase (optional but recommended)
```

**For AD2 (Windows Server):**
- Host: 192.168.0.6
- User: INTRANET\sysadmin
- Password: See credentials.md
- Note: Password authentication (SSH keys not typically used with Windows domain accounts)

**For D2TESTNAS (Linux NAS):**
```bash
# Copy your SSH key to the NAS
ssh-copy-id root@192.168.0.9

# Test connection (both platforms)
ssh root@192.168.0.9 "ls /data/test/COMMON/ProdSW/"
```

**For Gitea Server:**
```bash
# Test Gitea SSH access (both platforms)
ssh -p 2222 azcomputerguru@172.16.3.20

# Should show Gitea greeting, then disconnect
```

**Mac-Specific SSH Notes:**
- Keys stored in: `~/.ssh/`
- Config file: `~/.ssh/config`
- Permissions must be correct: `chmod 600 ~/.ssh/id_ed25519`

**Windows-Specific SSH Notes:**
- Keys stored in: `C:\Users\YourName\.ssh\`
- Use Git Bash or PowerShell for SSH commands
- OpenSSH should be installed (Windows 10+)

---

## Step 9: Update File Paths in Context Recovery Prompt

The context recovery prompt has Windows paths. Update them for your platform:

**For Mac, change:**
- `D:\ClaudeTools` → `/Users/yourusername/Projects/ClaudeTools`
- Or use relative paths (just `PROJECT_ORGANIZATION.md` instead of full path)

**Context Recovery Prompt (Platform-Agnostic Version):**

See `CONTEXT_RECOVERY_PROMPT.md` in the repository. When pasting to Claude Code, use paths appropriate for your platform:

```
Working directory: D:\ClaudeTools          (Windows)
Working directory: ~/Projects/ClaudeTools   (Mac)
```

---

## Step 10: Restore Full Context in Claude Code

Open Claude Code in your ClaudeTools directory:

```bash
Windows> cd D:\ClaudeTools
Mac> cd ~/Projects/ClaudeTools
```

**Then paste the context recovery prompt from `CONTEXT_RECOVERY_PROMPT.md`**

The prompt will tell Claude to read all necessary files and restore full context including:
- Project states (DOS, API, clients)
- Credentials and infrastructure access
- Organization system
- MCP servers, commands, and skills

---

## Step 11: Verify Everything Works

**Test Checklist:**

- [ ] Python venv activates
- [ ] Database connection successful (172.16.3.30:3306)
- [ ] API server starts and responds (http://localhost:8000/api/docs)
- [ ] SSH to D2TESTNAS works (ssh root@192.168.0.9)
- [ ] SSH to Gitea works (ssh -p 2222 azcomputerguru@172.16.3.20)
- [ ] Claude Code loads in ClaudeTools directory
- [ ] MCP servers load (check Claude Code startup messages)
- [ ] Context recovery prompt works
- [ ] Available commands show: /save, /context, /checkpoint, etc.
- [ ] Git push to Gitea works

---

## Platform-Specific Quick Reference

### Windows

**Start API:**
```bash
cd D:\ClaudeTools
api\venv\Scripts\activate
python -m api.main
```

**File Paths:**
- Project root: `D:\ClaudeTools`
- Venv: `D:\ClaudeTools\api\venv`
- Credentials: `D:\ClaudeTools\credentials.md`

**Deploy to DOS:**
```bash
scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/
```

### Mac

**Start API:**
```bash
cd ~/Projects/ClaudeTools
source api/venv/bin/activate
python -m api.main
```

**File Paths:**
- Project root: `~/Projects/ClaudeTools`
- Venv: `~/Projects/ClaudeTools/api/venv`
- Credentials: `~/Projects/ClaudeTools/credentials.md`

**Deploy to DOS:**
```bash
scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/
```

---

## Cross-Platform Notes

**What's the Same:**
- Git commands (clone, commit, push, pull)
- Python/pip commands (once venv activated)
- SSH commands (ssh, scp)
- Database access (same connection string)
- API endpoints (same URLs)
- File organization structure

**What's Different:**
- Path separators: `\` (Windows) vs `/` (Mac/Linux)
- Venv activation: `Scripts\activate` vs `bin/activate`
- File copy: `copy` vs `cp`
- Text editors: `notepad` vs `nano/vim`
- MCP .mcp.json: `cmd /c npx` vs just `npx`
- Absolute paths: `D:\` vs `/Users/` or `~`

---

## Troubleshooting

**MCP servers not loading:**
- Restart Claude Code completely
- Check npm is installed: `npm --version`
- Check .mcp.json is valid JSON
- **Mac:** Verify paths use forward slashes: `/Users/...`
- **Windows:** Verify paths use double backslashes: `D:\\...`

**Database connection fails:**
- Verify network access to 172.16.3.30:3306
- **Mac:** Check firewall settings (System Preferences → Security)
- **Windows:** Check Windows Firewall
- Test with: `python test_db_connection.py`

**SSH keys not working:**
```bash
# Mac: Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Windows: Use Git Bash for SSH operations
# Or ensure OpenSSH is installed and running
```

**API won't start:**
```bash
# Check port 8000 not in use
Windows> netstat -ano | findstr :8000
Mac> lsof -i :8000

# Verify venv is activated (should see (venv) in prompt)
# Check all dependencies: pip list
```

**Git push fails:**
```bash
# Ensure SSH key is added to Gitea
# Test connection:
ssh -p 2222 azcomputerguru@172.16.3.20

# Check remote URL:
git remote -v
```

---

## What You Now Have (All Platforms)

**Complete Environment:**
- ✅ All project files organized by project/client
- ✅ Full git history from Gitea
- ✅ Python API environment configured
- ✅ MCP servers ready to use
- ✅ SSH access to infrastructure (D2TESTNAS, Gitea)
- ✅ Database connection to MariaDB (172.16.3.30)
- ✅ All credentials and context
- ✅ All commands and skills available

**Full Context:**
- ✅ Dataforth DOS project status and history
- ✅ ClaudeTools API development history
- ✅ Client history (Horseshoe Management)
- ✅ Infrastructure access details
- ✅ Recent work and decisions

**Works On:**
- ✅ Windows 10/11
- ✅ macOS (Intel and Apple Silicon)
- ✅ Linux (Ubuntu, Debian, etc.)

---

## Next Steps After Setup

1. **Test DOS deployment on TS-4R** (pending from last session)
2. **Continue API development** (Phase 5 complete, optional Phase 7 available)
3. **Handle client support requests** (Horseshoe Management, etc.)

All work will automatically be organized into correct project/client folders and synced back to Gitea.

---

**Setup Complete!** You now have an identical ClaudeTools environment on your new machine, whether it's Windows, Mac, or Linux.

---

**Last Updated:** 2026-01-20
**File Location:** NEW_MACHINE_SETUP.md (in Gitea repository)
**Platforms:** Windows, macOS, Linux