azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add cross-platform setup guide and context recovery for Mac/Windows/Linux

Browse Source
This commit is contained in:
Mike Swanson
2026-01-20 16:10:28 -07:00
parent 6f874d7a17
commit dc7174a53d
1 changed files with 486 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

486
NEW_MACHINE_SETUP.md Normal file
View File

@@ -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