vm dev machine setup guide

2026-02-07 20:56:43 +00:00
parent 95c2abe449
commit cf97ab8aca
1 changed files with 676 additions and 0 deletions
--- a/V8-DEV-VM-SETUP-GUIDE.md
+++ b/V8-DEV-VM-SETUP-GUIDE.md
@@ -0,0 +1,676 @@
+# AyaNova v8 Build VM Setup Guide
+
+> **Purpose**: Step-by-step instructions to create a portable Windows virtual machine containing the complete AyaNova v8 build environment. This VM can run on Windows or Linux hosts.
+
+---
+
+## Overview
+
+This guide will help you create a VirtualBox VM that:
+- Contains all tools needed to build every AyaNova v8 target
+- Is portable (can be moved between machines)
+- Can be snapshotted (save known-good states)
+- Works on both Windows and Linux host machines
+
+**Time estimate**: 3-4 hours for initial setup
+
+---
+
+## Part 1: Prerequisites and Purchases
+
+### 1.1 Windows License
+
+You'll need a legitimate Windows license for the VM. Options:
+
+| Option | Approximate Cost | Notes |
+|--------|------------------|-------|
+| Windows 11 Pro (Retail) | $200 USD | Transferable to new hardware, recommended |
+| Windows 11 Pro (OEM) | $120-150 USD | Tied to "one machine" but works for VMs |
+| Windows 11 Home | $140 USD | Works but Pro has Hyper-V/dev features |
+| Windows 10 Pro | $120-150 USD | Still fully supported, lighter weight |
+
+**Recommendation**: Windows 11 Pro retail license. It's transferable and will remain supported longest.
+
+**Where to buy**:
+- Microsoft Store (microsoft.com) - Full retail price, guaranteed legitimate
+- Amazon - Often has retail boxed copies
+- Newegg - Same as Amazon
+
+**Avoid**: Grey market key resellers (G2A, Kinguin, etc.) - Keys may be revoked.
+
+### 1.2 Host Machine Requirements
+
+Your Linux laptop will need:
+- **RAM**: 16GB minimum (8GB for VM + 8GB for host)
+- **Disk**: 100GB free space for VM
+- **CPU**: 4+ cores recommended (VM will use 2-4)
+- **Virtualization**: VT-x/AMD-V enabled in BIOS
+
+Your current ThinkPad X13 (16GB RAM, Ryzen 7) will work, though it'll be tight on RAM. A machine with 32GB would be more comfortable.
+
+### 1.3 Software to Download (All Free)
+
+Download these before starting:
+
+1. **VirtualBox** (host machine)
+   - https://www.virtualbox.org/wiki/Downloads
+   - Get the version for your Linux distribution
+   - Also get the Extension Pack (same page)
+
+2. **Windows 11 ISO** (for VM)
+   - https://www.microsoft.com/software-download/windows11
+   - Download the ISO directly (not the Media Creation Tool)
+
+---
+
+## Part 2: Create the Virtual Machine
+
+### 2.1 Install VirtualBox on Linux Host
+
+For Ubuntu/Debian-based:
+```bash
+sudo apt update
+sudo apt install virtualbox virtualbox-ext-pack
+```
+
+For Fedora:
+```bash
+sudo dnf install VirtualBox
+```
+
+Or download from virtualbox.org for other distributions.
+
+### 2.2 Create New VM
+
+1. Open VirtualBox Manager
+2. Click **New**
+3. Configure:
+   - **Name**: `AyaNova-Build-v8`
+   - **Folder**: Choose a location with plenty of space
+   - **ISO Image**: Select the Windows 11 ISO you downloaded
+   - **Type**: Microsoft Windows
+   - **Version**: Windows 11 (64-bit)
+   - Check "Skip Unattended Installation" (gives you more control)
+
+4. Click **Next**
+
+### 2.3 Hardware Configuration
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| Base Memory | 8192 MB (8GB) | Minimum for VS 2022 |
+| Processors | 4 CPUs | More if your host has them |
+| Enable EFI | Yes | Required for Windows 11 |
+
+Click **Next**
+
+### 2.4 Virtual Hard Disk
+
+| Setting | Value | Notes |
+|---------|-------|-------|
+| Create Virtual Hard Disk | Yes | |
+| Disk Size | 120 GB | VS alone is 20-40GB |
+| Pre-allocate Full Size | No | Saves initial space |
+
+Click **Next**, then **Finish**
+
+### 2.5 Additional VM Settings
+
+Before starting the VM, click **Settings**:
+
+**System → Motherboard:**
+- Enable EFI: ✓ (should already be set)
+- TPM: v2.0 (required for Windows 11)
+
+**Display:**
+- Video Memory: 128 MB
+- Graphics Controller: VBoxSVGA
+- Enable 3D Acceleration: ✓
+
+**Storage:**
+- Verify Windows ISO is attached to IDE Controller
+
+**Shared Folders** (optional, configure later):
+- Can share folders between host and VM
+
+**Network:**
+- Attached to: NAT (default, fine for building)
+- Or: Bridged Adapter (if you need VM on your network)
+
+Click **OK**
+
+---
+
+## Part 3: Install Windows
+
+### 3.1 Start VM and Install
+
+1. Start the VM
+2. Press any key to boot from ISO when prompted
+3. Follow Windows 11 installer:
+   - Language: Your preference
+   - Click "Install now"
+   - Enter your product key (or "I don't have a product key" to enter later)
+   - Select **Windows 11 Pro**
+   - Accept license terms
+   - Choose **Custom: Install Windows only**
+   - Select the virtual drive, click **Next**
+   - Wait for installation (10-20 minutes)
+
+### 3.2 Initial Windows Setup
+
+When Windows restarts:
+1. Select region and keyboard layout
+2. **Network**: If asked, choose "I don't have internet" → "Continue with limited setup"
+   - This avoids Microsoft account requirement
+3. Create a local account:
+   - Username: `builder` (or your preference)
+   - Password: Something simple but memorable
+4. Disable all the telemetry/tracking options (your choice)
+5. Wait for setup to complete
+
+### 3.3 Install VirtualBox Guest Additions
+
+This enables better display, shared folders, clipboard sharing:
+
+1. In VirtualBox menu: **Devices → Insert Guest Additions CD image**
+2. Open File Explorer in Windows
+3. Navigate to the CD drive
+4. Run **VBoxWindowsAdditions.exe**
+5. Accept all defaults, click Install
+6. Reboot when prompted
+
+After reboot:
+- VM window can be resized freely
+- Enable shared clipboard: **Devices → Shared Clipboard → Bidirectional**
+
+### 3.4 Windows Updates
+
+Before installing dev tools, get Windows fully updated:
+
+1. **Settings → Windows Update**
+2. Click "Check for updates"
+3. Install all updates
+4. Reboot as needed
+5. Repeat until no more updates
+
+This may take 30-60 minutes. Be patient.
+
+### 3.5 Activate Windows
+
+1. **Settings → System → Activation**
+2. Click "Change product key"
+3. Enter your Windows license key
+4. Click Activate
+
+---
+
+## Part 4: Install Build Tools
+
+### 4.1 Create Standard Folders
+
+Open PowerShell as Administrator and run:
+```powershell
+mkdir C:\data
+mkdir C:\data\code
+```
+
+### 4.2 Install Package Manager (Winget or Chocolatey)
+
+Winget is built into Windows 11. Verify it works:
+```powershell
+winget --version
+```
+
+If not available, install Chocolatey as alternative:
+```powershell
+Set-ExecutionPolicy Bypass -Scope Process -Force
+[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
+iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+```
+
+### 4.3 Install Core Tools
+
+Using winget (run in PowerShell as Administrator):
+
+```powershell
+# 7-Zip
+winget install --id 7zip.7zip -e
+
+# Git (useful even if using SVN)
+winget install --id Git.Git -e
+
+# VS Code
+winget install --id Microsoft.VisualStudioCode -e --source winget
+
+# Python 3.11
+winget install --id Python.Python.3.11 -e --source winget
+
+# .NET 8 SDK
+winget install --id Microsoft.DotNet.SDK.8 -e --source winget
+
+# Inno Setup
+winget install --id JRSoftware.InnoSetup -e --source winget
+```
+
+Close and reopen PowerShell after these installs.
+
+### 4.4 Install Node.js 12.22.9 (Specific Version)
+
+Node 12 isn't in winget, so install manually:
+
+1. Download from: https://nodejs.org/dist/v12.22.9/node-v12.22.9-x64.msi
+2. Run the installer
+3. Accept all defaults
+4. Verify:
+```powershell
+node -v
+# Should show: v12.22.9
+```
+
+### 4.5 Install MkDocs
+
+```powershell
+pip install mkdocs mkdocs-material
+```
+
+Verify:
+```powershell
+mkdocs --version
+```
+
+### 4.6 Install Visual Studio 2022 Community
+
+This is needed for the QuickBooks Integration project (.NET Framework 4.8, Windows Forms).
+
+1. Download from: https://visualstudio.microsoft.com/vs/community/
+2. Run the installer
+3. When Workloads screen appears, select:
+   - ✓ **.NET desktop development** (includes Windows Forms)
+   - ✓ **ASP.NET and web development** (optional but useful)
+4. In Individual Components tab, verify:
+   - ✓ .NET Framework 4.8 SDK
+   - ✓ .NET Framework 4.8 targeting pack
+5. Click **Install**
+6. Wait (this takes 20-40 minutes and downloads several GB)
+
+### 4.7 Install TortoiseSVN (if using SVN)
+
+```powershell
+winget install --id TortoiseSVN.TortoiseSVN -e
+```
+
+Reboot after installation (adds shell integration).
+
+### 4.8 Verify All Installations
+
+Open a new PowerShell window and run:
+
+```powershell
+# Create a verification script
+@"
+Write-Host "=== AyaNova Build Environment Check ===" -ForegroundColor Cyan
+Write-Host ""
+
+Write-Host "Node.js:" -NoNewline
+node -v
+
+Write-Host "npm:" -NoNewline  
+npm -v
+
+Write-Host "Python:" -NoNewline
+python --version
+
+Write-Host "pip:" -NoNewline
+pip --version
+
+Write-Host ".NET SDK:" -NoNewline
+dotnet --version
+
+Write-Host "MkDocs:" -NoNewline
+mkdocs --version
+
+Write-Host ""
+Write-Host "Checking paths..." -ForegroundColor Cyan
+
+$tools = @(
+    "C:\Program Files\7-Zip\7z.exe",
+    "C:\Program Files (x86)\Inno Setup 6\ISCC.exe"
+)
+
+foreach ($tool in $tools) {
+    if (Test-Path $tool) {
+        Write-Host "[OK] $tool" -ForegroundColor Green
+    } else {
+        Write-Host "[MISSING] $tool" -ForegroundColor Red
+    }
+}
+
+Write-Host ""
+Write-Host "=== Check Complete ===" -ForegroundColor Cyan
+"@ | Out-File -FilePath "check-env.ps1"
+
+# Run it
+.\check-env.ps1
+```
+
+All items should show versions or [OK].
+
+---
+
+## Part 5: Set Up Source Code
+
+### 5.1 Check Out from SVN
+
+If your SVN server is accessible from the VM:
+
+```powershell
+cd C:\data\code
+
+# Check out main repository
+svn checkout https://your-svn-server/path/to/raven raven
+
+# Check out frontend
+svn checkout https://your-svn-server/path/to/raven-client raven-client
+
+# Check out launcher
+svn checkout https://your-svn-server/path/to/raven-launcher raven-launcher
+
+# Check out QBI
+svn checkout https://your-svn-server/path/to/ravenqbi ravenqbi
+```
+
+### 5.2 Alternative: Copy from Host via Shared Folder
+
+If SVN isn't accessible, use VirtualBox shared folders:
+
+1. In VirtualBox: **Devices → Shared Folders → Shared Folders Settings**
+2. Click the folder+ icon
+3. **Folder Path**: Your code folder on Linux host
+4. **Folder Name**: `code`
+5. Check "Auto-mount"
+6. Click OK
+
+The shared folder appears as a network drive in Windows. Copy files from there to `C:\data\code\`.
+
+### 5.3 Install Frontend Dependencies
+
+```powershell
+cd C:\data\code\raven-client\ayanova
+npm ci
+```
+
+This installs exact versions from package-lock.json. May take 5-10 minutes.
+
+---
+
+## Part 6: Test the Build
+
+### 6.1 Run Full Build
+
+```powershell
+cd C:\data\code\raven
+.\build-release.bat
+```
+
+Watch for errors. The build should:
+1. Build main docs ✓
+2. Build customer docs ✓
+3. Build frontend ✓
+4. Build subscription Linux ✓
+5. Build perpetual Linux ✓
+6. Build Windows standalone ✓
+7. Build Windows framework-dependent ✓
+8. Build launcher ✓
+9. Create standalone installer ✓
+10. Create LAN installer ✓
+
+### 6.2 Verify Outputs
+
+Check that all expected files were created:
+
+```powershell
+dir C:\data\code\raven\dist\installers
+```
+
+Expected files:
+- `ayanova-subscription-linux-x64-server.zip`
+- `ayanova-linux-x64-desktop.zip`
+- `ayanova-linux-x64-server.zip`
+- `ayanova-windows-x64-single-setup.exe`
+- `ayanova-windows-x64-lan-setup.exe`
+
+### 6.3 Test QBI Build (Separate)
+
+```powershell
+cd C:\data\code\ravenqbi\AyaNovaQBI
+
+# Build using MSBuild (comes with VS)
+& "C:\Program Files\Microsoft Visual Studio\18\Community\MSBuild\Current\Bin\MSBuild.exe" /p:Configuration=Release
+
+
+# Or open in Visual Studio and build from there
+```
+
+---
+
+## Part 7: Create Snapshot and Backup
+
+### 7.1 Clean Up Before Snapshot
+
+Inside the VM:
+```powershell
+# Clear temp files
+Remove-Item -Recurse -Force $env:TEMP\*
+
+# Clear Windows temp
+Remove-Item -Recurse -Force C:\Windows\Temp\* -ErrorAction SilentlyContinue
+
+# Empty recycle bin
+Clear-RecycleBin -Force -ErrorAction SilentlyContinue
+```
+
+Shut down the VM cleanly: **Start → Power → Shut down**
+
+### 7.2 Create Snapshot
+
+In VirtualBox Manager:
+1. Select your VM
+2. Click **Snapshots** (next to Details)
+3. Click **Take** (camera icon)
+4. Name: `Fresh-Build-Environment-Working`
+5. Description: `Clean install with all build tools. Full build tested and working.`
+6. Click OK
+
+This snapshot lets you restore to this exact state if anything breaks later.
+
+### 7.3 Export VM for Backup
+
+For a portable backup you can store on an external drive:
+
+1. **File → Export Appliance**
+2. Select your VM, click Next
+3. Choose location (external drive recommended)
+4. Format: OVF 2.0
+5. File: `AyaNova-Build-VM-v8.ova`
+6. Click Next, then Export
+
+This creates a single file (~30-50GB) that can be imported into VirtualBox on any machine.
+
+### 7.4 Backup Strategy
+
+Store the exported .ova file:
+- On an external drive (your monthly backup drives)
+- Separate from your regular backups (it's a different kind of asset)
+
+When to re-export:
+- After major tool updates (new .NET SDK version, etc.)
+- After significant build process changes
+- Quarterly, as a habit
+
+---
+
+## Part 8: Day-to-Day Usage
+
+### 8.1 Starting the VM
+
+1. Open VirtualBox
+2. Select `AyaNova-Build-v8`
+3. Click **Start**
+4. Wait for Windows to boot
+5. Log in
+
+### 8.2 Updating Source Code
+
+```powershell
+cd C:\data\code\raven
+svn update
+
+cd C:\data\code\raven-client
+svn update
+
+# etc.
+```
+
+### 8.3 Running Builds
+
+```powershell
+cd C:\data\code\raven
+.\build-release.bat
+```
+
+### 8.4 Getting Files Out of the VM
+
+Options:
+1. **Shared Folders**: Copy to a shared folder visible on host
+2. **Network**: If VM is bridged, access via network share
+3. **USB Drive**: Attach a USB drive to the VM
+4. **SVN Commit**: Commit build outputs to repo (not recommended for large binaries)
+
+### 8.5 Snapshots for Safety
+
+Before making any changes to the build environment:
+1. Shut down VM
+2. Take a snapshot
+3. Start VM
+4. Make changes
+5. If something breaks: Restore snapshot
+
+---
+
+## Part 9: Linux Host Notes
+
+### 9.1 Recommended Linux Distributions
+
+For a development workstation, these work well with VirtualBox:
+
+| Distribution | Notes |
+|--------------|-------|
+| Ubuntu 22.04/24.04 LTS | Most compatible, largest community |
+| Linux Mint | Ubuntu-based, more Windows-like feel |
+| Fedora Workstation | Cutting edge, good hardware support |
+| Pop!_OS | Good for laptops, System76's distro |
+
+### 9.2 ThinkPad Linux Compatibility
+
+ThinkPads are generally excellent Linux laptops. The X13 Gen 3 AMD should work well with Ubuntu or Fedora out of the box.
+
+### 9.3 Performance Tips
+
+- **Enable VT-x/AMD-V**: In BIOS settings, ensure virtualization is enabled
+- **Nested Virtualization**: May be needed if VM uses Hyper-V features (usually not needed for this use case)
+- **SSD**: VM performance is heavily dependent on disk speed; SSD is essential
+- **RAM**: 32GB on host would be more comfortable than 16GB
+
+### 9.4 Used ThinkPad Recommendations
+
+If you're looking at a used/refurbished ThinkPad for Linux:
+
+| Model | Era | Notes |
+|-------|-----|-------|
+| X1 Carbon Gen 9/10 | 2021-2022 | Excellent, lightweight |
+| T14s Gen 2/3 | 2021-2022 | Good value, business-class |
+| T480/T480s | 2018 | Older but very well supported, cheap |
+| P14s | 2020+ | More RAM options (up to 48GB) |
+
+Look for 32GB RAM models if possible. Check that the specific CPU is supported (Intel generally has better Linux support than AMD, though AMD works fine too).
+
+---
+
+## Appendix A: Troubleshooting
+
+### Windows 11 Won't Install (TPM Error)
+
+VirtualBox 7.0+ supports TPM 2.0 emulation. If you get TPM errors:
+1. VM Settings → System → Motherboard
+2. Ensure TPM is set to v2.0
+
+### Build Fails: Node Module Errors
+
+If `npm ci` fails with native module errors:
+1. Delete `node_modules` folder
+2. Try `npm install` instead of `npm ci`
+3. If still failing, verify Node version is exactly 12.22.9
+
+### VM Performance is Poor
+
+- Increase VM RAM (if host has headroom)
+- Increase CPU cores
+- Ensure VirtualBox Guest Additions are installed
+- Check that 3D acceleration is enabled
+- Use SSD, not spinning disk
+
+### Can't Access SVN Server
+
+- Check VM network mode (NAT vs Bridged)
+- Verify SVN server is accessible from host
+- Check firewall settings on both host and VM
+
+---
+
+## Appendix B: Quick Reference
+
+### Build Commands
+
+```powershell
+# Full build
+cd C:\data\code\raven
+.\build-release.bat
+
+# Frontend only
+cd C:\data\code\raven-client\ayanova
+npm run build
+
+# Docs only
+cd C:\data\code\raven\docs\8.0\ayanova
+mkdocs build
+
+# QBI only (in Visual Studio or command line)
+msbuild C:\data\code\ravenqbi\AyaNovaQBI\AyaNovaQBI.csproj /p:Configuration=Release
+```
+
+### Key Paths
+
+| What | Path |
+|------|------|
+| Main repo | `C:\data\code\raven` |
+| Frontend | `C:\data\code\raven-client\ayanova` |
+| Launcher | `C:\data\code\raven-launcher` |
+| QBI | `C:\data\code\ravenqbi` |
+| Build outputs | `C:\data\code\raven\dist\installers` |
+
+### Tool Locations
+
+| Tool | Path |
+|------|------|
+| 7-Zip | `C:\Program Files\7-Zip\7z.exe` |
+| Inno Setup | `C:\Program Files (x86)\Inno Setup 6\ISCC.exe` |
+| MSBuild | `C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe` |
+
+---
+
+## Version History
+
+| Date | Change |
+|------|--------|
+| 2026-02-01 | Initial guide created |