raven/V8-DEV-VM-SETUP-GUIDE.md

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