Files

John Cardinal cf97ab8aca vm dev machine setup guide

2026-02-07 20:56:43 +00:00

17 KiB

Raw Permalink Blame History

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:

VirtualBox (host machine)
- https://www.virtualbox.org/wiki/Downloads
- Get the version for your Linux distribution
- Also get the Extension Pack (same page)
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:

sudo apt update
sudo apt install virtualbox virtualbox-ext-pack

For Fedora:

sudo dnf install VirtualBox

Or download from virtualbox.org for other distributions.

2.2 Create New VM

Open VirtualBox Manager
Click New
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)
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

Start the VM
Press any key to boot from ISO when prompted
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:

Select region and keyboard layout
Network: If asked, choose "I don't have internet" → "Continue with limited setup"
- This avoids Microsoft account requirement
Create a local account:
- Username: builder (or your preference)
- Password: Something simple but memorable
Disable all the telemetry/tracking options (your choice)
Wait for setup to complete

3.3 Install VirtualBox Guest Additions

This enables better display, shared folders, clipboard sharing:

In VirtualBox menu: Devices → Insert Guest Additions CD image
Open File Explorer in Windows
Navigate to the CD drive
Run VBoxWindowsAdditions.exe
Accept all defaults, click Install
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:

Settings → Windows Update
Click "Check for updates"
Install all updates
Reboot as needed
Repeat until no more updates

This may take 30-60 minutes. Be patient.

3.5 Activate Windows

Settings → System → Activation
Click "Change product key"
Enter your Windows license key
Click Activate

Part 4: Install Build Tools

4.1 Create Standard Folders

Open PowerShell as Administrator and run:

mkdir C:\data
mkdir C:\data\code

4.2 Install Package Manager (Winget or Chocolatey)

Winget is built into Windows 11. Verify it works:

winget --version

If not available, install Chocolatey as alternative:

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):

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

Download from: https://nodejs.org/dist/v12.22.9/node-v12.22.9-x64.msi
Run the installer
Accept all defaults
Verify:

node -v
# Should show: v12.22.9

4.5 Install MkDocs

pip install mkdocs mkdocs-material

Verify:

mkdocs --version

4.6 Install Visual Studio 2022 Community

This is needed for the QuickBooks Integration project (.NET Framework 4.8, Windows Forms).

Download from: https://visualstudio.microsoft.com/vs/community/
Run the installer
When Workloads screen appears, select:
- ✓ .NET desktop development (includes Windows Forms)
- ✓ ASP.NET and web development (optional but useful)
In Individual Components tab, verify:
- ✓ .NET Framework 4.8 SDK
- ✓ .NET Framework 4.8 targeting pack
Click Install
Wait (this takes 20-40 minutes and downloads several GB)

4.7 Install TortoiseSVN (if using SVN)

winget install --id TortoiseSVN.TortoiseSVN -e

Reboot after installation (adds shell integration).

4.8 Verify All Installations

Open a new PowerShell window and run:

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

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:

In VirtualBox: Devices → Shared Folders → Shared Folders Settings
Click the folder+ icon
Folder Path: Your code folder on Linux host
Folder Name: code
Check "Auto-mount"
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

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

cd C:\data\code\raven
.\build-release.bat

Watch for errors. The build should:

Build main docs ✓
Build customer docs ✓
Build frontend ✓
Build subscription Linux ✓
Build perpetual Linux ✓
Build Windows standalone ✓
Build Windows framework-dependent ✓
Build launcher ✓
Create standalone installer ✓
Create LAN installer ✓

6.2 Verify Outputs

Check that all expected files were created:

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)

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:

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

Select your VM
Click Snapshots (next to Details)
Click Take (camera icon)
Name: Fresh-Build-Environment-Working
Description: Clean install with all build tools. Full build tested and working.
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:

File → Export Appliance
Select your VM, click Next
Choose location (external drive recommended)
Format: OVF 2.0
File: AyaNova-Build-VM-v8.ova
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

Open VirtualBox
Select AyaNova-Build-v8
Click Start
Wait for Windows to boot
Log in

8.2 Updating Source Code

cd C:\data\code\raven
svn update

cd C:\data\code\raven-client
svn update

# etc.

8.3 Running Builds

cd C:\data\code\raven
.\build-release.bat

8.4 Getting Files Out of the VM

Options:

Shared Folders: Copy to a shared folder visible on host
Network: If VM is bridged, access via network share
USB Drive: Attach a USB drive to the VM
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:

Shut down VM
Take a snapshot
Start VM
Make changes
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:

VM Settings → System → Motherboard
Ensure TPM is set to v2.0

Build Fails: Node Module Errors

If npm ci fails with native module errors:

Delete node_modules folder
Try npm install instead of npm ci
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

# 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

17 KiB Raw Permalink Blame History