From dc7174a53dbf2763ca1b73c244a4a2af947f2e8e Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Tue, 20 Jan 2026 16:10:28 -0700 Subject: [PATCH] Add cross-platform setup guide and context recovery for Mac/Windows/Linux --- NEW_MACHINE_SETUP.md | 486 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 486 insertions(+) create mode 100644 NEW_MACHINE_SETUP.md diff --git a/NEW_MACHINE_SETUP.md b/NEW_MACHINE_SETUP.md new file mode 100644 index 0000000..416a99b --- /dev/null +++ b/NEW_MACHINE_SETUP.md @@ -0,0 +1,486 @@ +# 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