feat(local-llms): add one-click Windows setup scripts

- setup-windows.ps1: PowerShell script for Windows side
  - NVIDIA driver verification, Ollama install via winget
  - Pull all 5 models with skip-if-exists logic
  - WSL2 Ubuntu 24.04 install
- setup-wsl.sh: Bash script for WSL2 side
  - Idempotent apt deps (Node.js 20, Python 3.12, ffmpeg, cmake)
  - CUDA GPU passthrough verification
  - Repo clone + git pull, whisper.cpp CUDA build
  - Whisper model download, TTS setup, dashboard start
- README.md: 2-step quick start (no IDE required)
- setup-guide.md: add automated setup section at top
This commit is contained in:
saravanakumardb1 2026-02-21 16:28:02 -08:00
parent 416a8eed84
commit efd45ad86f
4 changed files with 551 additions and 0 deletions

View File

@ -0,0 +1,97 @@
# Windows Setup — Local LLM Stack
> **Two scripts. Zero IDE required. Fresh machine to running dashboard in ~30 minutes.**
## Quick Start
### Step 1: Windows Side (PowerShell as Admin)
```powershell
# Allow script execution for this session
Set-ExecutionPolicy -Scope Process Bypass
# Run the Windows setup (installs Ollama, pulls models, installs WSL2)
.\setup-windows.ps1
```
**What it does:** Verifies NVIDIA drivers, installs Ollama, pulls 5 models (~52 GB), installs WSL2 Ubuntu 24.04.
> After WSL2 install you may need to **reboot**. Ubuntu will ask for a username/password on first launch.
### Step 2: WSL2 Side (Ubuntu terminal)
```bash
# One-liner — downloads and runs the WSL2 setup script
curl -fsSL https://raw.githubusercontent.com/saravanakumardb1/learning_ai_common_plat/main/__LOCAL_LLMs/windows_specific/setup-wsl.sh | bash
```
**What it does:** Installs Node.js, Python, ffmpeg, cmake → builds Whisper.cpp with CUDA → sets up TTS → starts the dashboard.
### Step 3: Open Browser
```
http://localhost:3000
```
Dashboard should show all green. Done.
---
## What Gets Installed
| Component | Where | Size |
| ------------------ | ---------------------------------- | ------------- |
| NVIDIA drivers | Windows | pre-installed |
| Ollama | Windows (native) | ~200 MB |
| 5 LLM models | Windows (`%USERPROFILE%\.ollama\`) | ~52 GB |
| WSL2 Ubuntu 24.04 | Windows | ~1 GB |
| Node.js 20 LTS | WSL2 | ~50 MB |
| Python 3.12 + venv | WSL2 | ~200 MB |
| whisper.cpp (CUDA) | WSL2 `/usr/local/bin/` | ~50 MB |
| Whisper model | WSL2 `~/whisper-models/` | ~1.5 GB |
| SNAC decoder | WSL2 (repo `models/`) | ~76 MB |
| Qwen3-TTS 0.6B | WSL2 (repo `models/`) | ~1.7 GB |
| PyTorch CUDA | WSL2 (`.venv-qwen-tts/`) | ~2.5 GB |
| Dashboard deps | WSL2 (`dashboard/node_modules/`) | ~200 MB |
**Total:** ~60 GB (mostly Ollama models)
---
## Files in This Directory
| File | Purpose |
| -------------------------- | ------------------------------------------ |
| **README.md** | This file — quick start guide |
| **setup-windows.ps1** | PowerShell script — Windows-side setup |
| **setup-wsl.sh** | Bash script — WSL2-side setup |
| **setup-guide.md** | Detailed manual guide with troubleshooting |
| **razer-blade-18-spec.md** | Full hardware specs for the Razer Blade 18 |
---
## After Setup
```bash
# Daily usage — start everything
cd ~/code/mygh/learning_ai_common_plat/__LOCAL_LLMs
bash start-dashboard.sh
# Check status
bash start-dashboard.sh status
# Stop
bash start-dashboard.sh stop
# Test TTS
.venv-qwen-tts/bin/python test_orpheus_tts.py
.venv-qwen-tts/bin/python test_qwen_tts.py
```
## Troubleshooting
See [setup-guide.md](setup-guide.md#troubleshooting) for common issues:
- Ollama not accessible from WSL2
- CUDA not visible in WSL2
- Slow filesystem performance

View File

@ -7,6 +7,26 @@
---
## Automated Setup (Recommended)
**Two scripts, zero IDE required.** See [README.md](README.md) for the quick start, or run directly:
```powershell
# Step 1 — PowerShell (Admin) on Windows
Set-ExecutionPolicy -Scope Process Bypass
.\setup-windows.ps1
# Reboot if WSL2 was just installed
```
```bash
# Step 2 — Ubuntu (WSL2) terminal
curl -fsSL https://raw.githubusercontent.com/saravanakumardb1/learning_ai_common_plat/main/__LOCAL_LLMs/windows_specific/setup-wsl.sh | bash
```
The rest of this guide covers each step in detail for reference and troubleshooting.
---
## Architecture: Windows-Native + WSL2
```

View File

@ -0,0 +1,176 @@
# ============================================================
# Windows-Side Setup — Local LLM Stack (Razer Blade 18)
#
# Run this FIRST from PowerShell (Admin) on a fresh Windows machine.
# After this completes, open WSL2 and run setup-wsl.sh.
#
# What this does:
# 1. Verifies NVIDIA drivers + CUDA
# 2. Installs Ollama via winget
# 3. Pulls all 5 LLM models
# 4. Installs WSL2 with Ubuntu 24.04
#
# Usage (PowerShell as Admin):
# Set-ExecutionPolicy -Scope Process Bypass
# .\setup-windows.ps1
#
# After reboot, open Ubuntu (WSL2) and run:
# bash ~/setup-wsl.sh
# ============================================================
$ErrorActionPreference = "Stop"
function Write-OK { param($msg) Write-Host " [OK] $msg" -ForegroundColor Green }
function Write-Warn { param($msg) Write-Host " [!!] $msg" -ForegroundColor Yellow }
function Write-Fail { param($msg) Write-Host " [FAIL] $msg" -ForegroundColor Red }
function Write-Step { param($msg) Write-Host "`n=== $msg ===" -ForegroundColor Cyan }
Write-Host ""
Write-Host " =====================================" -ForegroundColor Cyan
Write-Host " Local LLM Stack — Windows Setup" -ForegroundColor Cyan
Write-Host " Razer Blade 18 / RTX 5090" -ForegroundColor Cyan
Write-Host " =====================================" -ForegroundColor Cyan
Write-Host ""
# ── 1. Check NVIDIA Drivers ──────────────────────────────────
Write-Step "Step 1/4: NVIDIA Drivers + CUDA"
$nvidiaSmi = Get-Command nvidia-smi -ErrorAction SilentlyContinue
if ($nvidiaSmi) {
$gpuInfo = & nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader 2>$null
if ($gpuInfo) {
Write-OK "NVIDIA driver installed"
Write-Host " GPU: $($gpuInfo.Trim())"
} else {
Write-Warn "nvidia-smi found but returned no data"
}
} else {
Write-Fail "NVIDIA drivers not found!"
Write-Host " Download from: https://www.nvidia.com/Download/index.aspx"
Write-Host " Install Game Ready or Studio drivers, then re-run this script."
Write-Host ""
$continue = Read-Host " Continue anyway? (y/N)"
if ($continue -ne "y") { exit 1 }
}
# ── 2. Install Ollama ────────────────────────────────────────
Write-Step "Step 2/4: Ollama"
$ollamaCmd = Get-Command ollama -ErrorAction SilentlyContinue
if ($ollamaCmd) {
$ollamaVer = & ollama --version 2>&1
Write-OK "Ollama already installed ($ollamaVer)"
} else {
Write-Host " Installing Ollama via winget..."
try {
& winget install --id Ollama.Ollama --accept-source-agreements --accept-package-agreements
Write-OK "Ollama installed"
Write-Warn "You may need to restart your terminal for 'ollama' to be on PATH"
} catch {
Write-Fail "winget install failed. Download manually: https://ollama.com/download"
$continue = Read-Host " Continue anyway? (y/N)"
if ($continue -ne "y") { exit 1 }
}
}
# Verify Ollama is running
Write-Host " Checking if Ollama is running..."
try {
$response = Invoke-WebRequest -Uri "http://localhost:11434/api/tags" -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
Write-OK "Ollama is running on port 11434"
} catch {
Write-Warn "Ollama not running. Starting..."
Start-Process ollama -ArgumentList "serve" -WindowStyle Hidden
Start-Sleep -Seconds 3
try {
$response = Invoke-WebRequest -Uri "http://localhost:11434/api/tags" -TimeoutSec 3 -UseBasicParsing -ErrorAction Stop
Write-OK "Ollama started"
} catch {
Write-Fail "Could not start Ollama. Start manually: ollama serve"
Write-Host " Then re-run this script."
$continue = Read-Host " Continue anyway? (y/N)"
if ($continue -ne "y") { exit 1 }
}
}
# ── 3. Pull Models ───────────────────────────────────────────
Write-Step "Step 3/4: Pull Ollama Models"
$models = @(
@{ name = "qwen2.5-coder:32b"; desc = "19 GB - primary coding model" },
@{ name = "qwen2.5-coder:7b"; desc = "4.7 GB - fast coding" },
@{ name = "deepseek-r1:32b"; desc = "19 GB - chain-of-thought" },
@{ name = "llama3.1:8b"; desc = "4.9 GB - fast general tasks" },
@{ name = "sematre/orpheus:en"; desc = "4 GB - text-to-speech (8 voices)" }
)
# Check which models are already pulled
$existingModels = @()
try {
$tagsJson = Invoke-WebRequest -Uri "http://localhost:11434/api/tags" -TimeoutSec 5 -UseBasicParsing -ErrorAction Stop
$tagsObj = $tagsJson.Content | ConvertFrom-Json
$existingModels = $tagsObj.models | ForEach-Object { $_.name }
} catch {
Write-Warn "Could not check existing models (Ollama may not be running)"
}
foreach ($model in $models) {
$alreadyPulled = $existingModels | Where-Object { $_ -like "*$($model.name)*" }
if ($alreadyPulled) {
Write-OK "$($model.name) — already pulled"
} else {
Write-Host " Pulling $($model.name) ($($model.desc))..."
& ollama pull $model.name
if ($LASTEXITCODE -eq 0) {
Write-OK "$($model.name) — pulled"
} else {
Write-Warn "$($model.name) — pull failed (you can retry later: ollama pull $($model.name))"
}
}
}
# Verify
Write-Host ""
Write-Host " Installed models:"
& ollama list
# ── 4. Install WSL2 ──────────────────────────────────────────
Write-Step "Step 4/4: WSL2 (Ubuntu 24.04)"
$wslInstalled = $false
try {
$wslList = & wsl --list --quiet 2>&1
if ($wslList -match "Ubuntu") {
Write-OK "WSL2 Ubuntu already installed"
$wslInstalled = $true
}
} catch {
# wsl not available
}
if (-not $wslInstalled) {
Write-Host " Installing WSL2 with Ubuntu 24.04..."
Write-Host " This may require a reboot."
Write-Host ""
& wsl --install -d Ubuntu-24.04
Write-Host ""
Write-Warn "If prompted, REBOOT your machine now."
Write-Warn "After reboot, Ubuntu will ask you to set up a username/password."
}
# ── Summary ──────────────────────────────────────────────────
Write-Host ""
Write-Host " =====================================" -ForegroundColor Green
Write-Host " Windows-Side Setup Complete!" -ForegroundColor Green
Write-Host " =====================================" -ForegroundColor Green
Write-Host ""
Write-Host " Next steps:" -ForegroundColor Yellow
Write-Host " 1. If WSL2 was just installed, reboot and set up Ubuntu username/password"
Write-Host " 2. Open Ubuntu (WSL2) terminal"
Write-Host " 3. Run the WSL2 setup script:"
Write-Host ""
Write-Host " curl -fsSL https://raw.githubusercontent.com/saravanakumardb1/learning_ai_common_plat/main/__LOCAL_LLMs/windows_specific/setup-wsl.sh | bash" -ForegroundColor Cyan
Write-Host ""
Write-Host " Or if you already cloned the repo:"
Write-Host " bash ~/code/mygh/learning_ai_common_plat/__LOCAL_LLMs/windows_specific/setup-wsl.sh" -ForegroundColor Cyan
Write-Host ""

View File

@ -0,0 +1,258 @@
#!/bin/bash
# ============================================================
# WSL2-Side Setup — Local LLM Stack (Razer Blade 18)
#
# Run this INSIDE WSL2 (Ubuntu 24.04) after setup-windows.ps1.
# This is a one-shot script — safe to re-run (idempotent).
#
# What this does:
# 1. Installs system deps (Node.js 20, Python 3.12, ffmpeg, cmake)
# 2. Verifies NVIDIA GPU passthrough (CUDA)
# 3. Clones the repo (if not already cloned)
# 4. Builds whisper.cpp with CUDA
# 5. Downloads Whisper large-v3-turbo model
# 6. Runs setup-tts.sh (Orpheus + Qwen3-TTS)
# 7. Starts the Mission Control dashboard
#
# Usage:
# bash setup-wsl.sh
#
# Or one-liner from a fresh WSL2 terminal:
# curl -fsSL https://raw.githubusercontent.com/saravanakumardb1/learning_ai_common_plat/main/__LOCAL_LLMs/windows_specific/setup-wsl.sh | bash
# ============================================================
set -e
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
NC='\033[0m'
ok() { echo -e " ${GREEN}[OK]${NC} $1"; }
warn() { echo -e " ${YELLOW}[!!]${NC} $1"; }
fail() { echo -e " ${RED}[FAIL]${NC} $1"; exit 1; }
step() { echo -e "\n${CYAN}=== $1 ===${NC}"; }
REPO_URL="https://github.com/saravanakumardb1/learning_ai_common_plat.git"
REPO_DIR="$HOME/code/mygh/learning_ai_common_plat"
LLMS_DIR="$REPO_DIR/__LOCAL_LLMs"
WHISPER_DIR="$HOME/whisper-cpp"
WHISPER_MODEL_DIR="$HOME/whisper-models"
WHISPER_MODEL_FILE="$WHISPER_MODEL_DIR/ggml-large-v3-turbo.bin"
echo ""
echo -e " ${CYAN}=====================================${NC}"
echo -e " ${CYAN}Local LLM Stack — WSL2 Setup${NC}"
echo -e " ${CYAN}Ubuntu 24.04 + CUDA${NC}"
echo -e " ${CYAN}=====================================${NC}"
echo ""
# ── 1. System Dependencies ───────────────────────────────────
step "Step 1/7: System Dependencies"
sudo apt update -qq
# Node.js 20 LTS
if command -v node &>/dev/null && [[ "$(node --version)" == v20* || "$(node --version)" == v22* ]]; then
ok "Node.js $(node --version) already installed"
else
echo " Installing Node.js 20 LTS..."
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - 2>/dev/null
sudo apt install -y nodejs -qq
ok "Node.js $(node --version) installed"
fi
# Python 3.12
PYTHON_CMD=""
for cmd in python3.12 python3; do
if command -v "$cmd" &>/dev/null; then
PYTHON_CMD="$cmd"
break
fi
done
if [ -z "$PYTHON_CMD" ]; then
echo " Installing Python 3.12..."
sudo apt install -y python3.12 python3.12-venv python3-pip -qq
PYTHON_CMD="python3.12"
fi
ok "$($PYTHON_CMD --version) at $(which $PYTHON_CMD)"
# Build tools + ffmpeg
PKGS_TO_INSTALL=""
for pkg in ffmpeg git curl build-essential cmake; do
if ! dpkg -s "$pkg" &>/dev/null; then
PKGS_TO_INSTALL="$PKGS_TO_INSTALL $pkg"
fi
done
if [ -n "$PKGS_TO_INSTALL" ]; then
echo " Installing:$PKGS_TO_INSTALL"
sudo apt install -y $PKGS_TO_INSTALL -qq
fi
ok "ffmpeg, git, curl, build-essential, cmake"
# ── 2. NVIDIA GPU Passthrough ────────────────────────────────
step "Step 2/7: NVIDIA GPU (CUDA passthrough)"
if command -v nvidia-smi &>/dev/null; then
GPU_NAME=$(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1)
GPU_MEM=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader 2>/dev/null | head -1)
ok "GPU: $GPU_NAME ($GPU_MEM)"
else
warn "nvidia-smi not found!"
echo " Possible fixes:"
echo " 1. Update NVIDIA drivers on Windows to the latest version"
echo " 2. Run in PowerShell (Admin): wsl --update"
echo " 3. Do NOT install nvidia-driver-* inside WSL2"
echo ""
read -p " Continue without CUDA? (y/N) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1; fi
fi
# ── 3. Verify Ollama (Windows-side) ──────────────────────────
step "Step 3/7: Ollama Connectivity"
if curl -s --max-time 3 http://localhost:11434/api/tags &>/dev/null; then
MODEL_COUNT=$(curl -s http://localhost:11434/api/tags | python3 -c "import sys,json; print(len(json.load(sys.stdin).get('models',[])))" 2>/dev/null || echo "?")
ok "Ollama reachable at localhost:11434 ($MODEL_COUNT models)"
else
warn "Ollama not reachable at localhost:11434"
echo " Make sure Ollama is running on the Windows side."
echo " Open PowerShell and run: ollama serve"
echo ""
read -p " Continue anyway? (y/N) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then exit 1; fi
fi
# ── 4. Clone Repo ────────────────────────────────────────────
step "Step 4/7: Clone Repository"
if [ -d "$LLMS_DIR" ]; then
ok "Repo already cloned at $REPO_DIR"
echo " Pulling latest..."
(cd "$REPO_DIR" && git pull --ff-only origin main 2>/dev/null || true)
else
echo " Cloning into $REPO_DIR..."
mkdir -p "$(dirname "$REPO_DIR")"
git clone "$REPO_URL" "$REPO_DIR"
ok "Cloned"
fi
# Verify __LOCAL_LLMs exists
if [ ! -d "$LLMS_DIR" ]; then
fail "__LOCAL_LLMs directory not found at $LLMS_DIR"
fi
ok "__LOCAL_LLMs directory: $LLMS_DIR"
# ── 5. Build Whisper.cpp (CUDA) ──────────────────────────────
step "Step 5/7: Whisper.cpp (CUDA build)"
if command -v whisper-cli &>/dev/null; then
ok "whisper-cli already installed: $(which whisper-cli)"
else
if [ ! -d "$WHISPER_DIR" ]; then
echo " Cloning whisper.cpp..."
git clone https://github.com/ggerganov/whisper.cpp.git "$WHISPER_DIR"
fi
echo " Building with CUDA support (this may take a few minutes)..."
cd "$WHISPER_DIR"
# Check if CUDA toolkit headers are available for build
if command -v nvidia-smi &>/dev/null; then
# Need CUDA toolkit for compilation
if ! dpkg -s nvidia-cuda-toolkit &>/dev/null 2>&1; then
echo " Installing CUDA toolkit for compilation..."
sudo apt install -y nvidia-cuda-toolkit -qq 2>/dev/null || true
fi
cmake -B build -DGGML_CUDA=ON 2>/dev/null || cmake -B build
else
warn "No CUDA — building CPU-only whisper.cpp"
cmake -B build
fi
cmake --build build --config Release -j$(nproc)
sudo cp build/bin/whisper-cli /usr/local/bin/
ok "whisper-cli installed to /usr/local/bin/"
fi
# Download Whisper model
if [ -f "$WHISPER_MODEL_FILE" ]; then
SIZE=$(stat -c%s "$WHISPER_MODEL_FILE" 2>/dev/null || echo 0)
if [ "$SIZE" -gt 100000000 ]; then
ok "Whisper model already downloaded ($(echo "scale=0; $SIZE/1048576" | bc) MB)"
else
warn "Whisper model looks incomplete ($SIZE bytes). Re-downloading..."
rm -f "$WHISPER_MODEL_FILE"
fi
fi
if [ ! -f "$WHISPER_MODEL_FILE" ]; then
mkdir -p "$WHISPER_MODEL_DIR"
echo " Downloading ggml-large-v3-turbo.bin (~1.5 GB)..."
curl -L --progress-bar -o "$WHISPER_MODEL_FILE" \
"https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin"
ok "Whisper model downloaded"
fi
# ── 6. TTS Setup ─────────────────────────────────────────────
step "Step 6/7: TTS Setup (Orpheus + Qwen3-TTS)"
cd "$LLMS_DIR"
# Use huggingface.co directly (personal machine, no corporate proxy)
echo " Running setup-tts.sh (this may take several minutes on first run)..."
HF_MIRROR=https://huggingface.co bash setup-tts.sh
ok "TTS setup complete"
# ── 7. Start Dashboard ───────────────────────────────────────
step "Step 7/7: Mission Control Dashboard"
cd "$LLMS_DIR"
# Install npm deps if needed
if [ ! -d "$LLMS_DIR/dashboard/node_modules" ]; then
echo " Installing dashboard dependencies..."
(cd "$LLMS_DIR/dashboard" && npm install --silent)
ok "Dashboard dependencies installed"
fi
# Check if already running
if curl -s --max-time 2 http://localhost:3000 &>/dev/null; then
ok "Dashboard already running at http://localhost:3000"
else
echo " Starting dashboard..."
bash start-dashboard.sh
fi
# ── Summary ──────────────────────────────────────────────────
echo ""
echo -e " ${GREEN}=====================================${NC}"
echo -e " ${GREEN}WSL2 Setup Complete!${NC}"
echo -e " ${GREEN}=====================================${NC}"
echo ""
echo " Components installed:"
echo " Node.js: $(node --version)"
echo " Python: $($PYTHON_CMD --version 2>&1)"
if command -v nvidia-smi &>/dev/null; then
echo " GPU: $(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1)"
fi
echo " Whisper: $(which whisper-cli 2>/dev/null || echo 'not found')"
echo " Repo: $LLMS_DIR"
echo ""
echo " Dashboard: http://localhost:3000"
echo " Ollama API: http://localhost:11434"
echo ""
echo " Useful commands:"
echo " bash start-dashboard.sh # start dashboard"
echo " bash start-dashboard.sh status # check status"
echo " bash start-dashboard.sh stop # stop dashboard"
echo ""
echo " Test TTS:"
echo " .venv-qwen-tts/bin/python test_orpheus_tts.py"
echo " .venv-qwen-tts/bin/python test_qwen_tts.py"
echo ""