windows-iac-vm-tooling/BUILD.md

🔨 Build Instructions for Windows 11 LTSC Template

This guide provides step-by-step instructions to build the Windows 11 LTSC template on Proxmox.

Prerequisites

Before building, ensure:

1. ✅ Access to Proxmox host (la-vmh-07.loopaware.com)
2. ✅ SSH key copied to Proxmox
3. ✅ Packer installed (version ≥ 1.1.0)
4. ✅ ISOs present on Proxmox

---

Step 1: SSH Setup

Copy SSH Key to Proxmox

# Copy your public key to Proxmox
ssh-copy-id root@la-vmh-07.loopaware.com

# Or manually add to /root/.ssh/authorized_keys on Proxmox
cat ~/.ssh/id_ed25519_no_pass.pub | ssh root@la-vmh-07.loopaware.com 'cat >> /root/.ssh/authorized_keys'

Test SSH Connection

ssh root@la-vmh-07.loopaware.com "hostname"

Expected output: la-vmh-07

---

Step 2: Install Packer on Proxmox

Option A: On Proxmox Host

# SSH to Proxmox
ssh root@la-vmh-07.loopaware.com

# Install Packer
wget https://apt.releases.hashicorp.com/pool/main/h/hashicorp_*_amd64.deb
apt install -y ./hashicorp_*.deb
rm hashicorp_*.deb

# Verify
packer --version

Option B: From Remote Machine

Packer can run remotely via the Proxmox API. Just install Packer locally:

# macOS
brew install packer

# Linux
wget https://apt.releases.hashicorp.com/pool/main/h/hashicorp_*_amd64.deb
sudo apt install -y ./hashicorp_*.deb

# Windows (Chocolatey)
choco install packer

---

Step 3: Verify ISOs on Proxmox

ssh root@la-vmh-07.loopaware.com "ls -lh /mnt/pve-07-iso-nvme/template/iso/"

Expected output:

CLIENT_LTSC_EVAL_x64FRE_en-us.iso
virtio-win.iso

---

Step 4: Configure Credentials

Method 1: Environment Variables

export PKR_VAR_proxmox_url="https://la-vmh-07.loopaware.com:8006/api2/json"
export PKR_VAR_proxmox_username="root@pam"
export PKR_VAR_proxmox_password="your-root-password"

Method 2: .env File

# Copy example and edit
cp .env.example .env
nano .env
source .env

---

Step 5: Run the Build

Using the Build Script (Recommended)

# Make executable
chmod +x build-template.sh

# Option 1: Interactive (will prompt for password)
./build-template.sh --node la-vmh-07

# Option 2: With password
./build-template.sh --node la-vmh-07 --password "your-password"

# Option 3: Validate only
./build-template.sh --node la-vmh-07 --check

Manual Packer Commands

# Initialize plugins
packer init packer/

# Validate configuration
packer validate -var "proxmox_url=https://la-vmh-07.loopaware.com:8006/api2/json" packer/windows.pkr.hcl

# Build (will take 15-25 minutes)
packer build -var "proxmox_url=https://la-vmh-07.loopaware.com:8006/api2/json" packer/windows.pkr.hcl

---

Build Process Overview

flowchart TB
    subgraph Setup["Preparation"]
        SSH[SSH to Proxmox] --> ISO[Verify ISOs]
        ISO --> Creds[Set Credentials]
    end
    
    subgraph Build["Packer Build"]
        Creds --> Init[packer init] --> Validate[packer validate]
        Validate --> BuildCmd[packer build]
        BuildCmd --> CreateVM[Create VM from ISO]
        CreateVM --> Install[Windows Install]
        Install --> Drivers[Install VirtIO Drivers]
        Drivers --> Sysprep[Generalize/Shutdown]
        Sysprep --> Template[Convert to Template]
    end
    
    subgraph Verify["Verification"]
        Template --> List[qm list]
        List --> VMID[Note VM ID]
    end
    
    style Setup fill:#e3f2fd
    style Build fill:#e8f5e9
    style Verify fill:#fff3e0

---

Expected Output

When the build starts, you'll see:

proxmox-iso.windows-11: output will be in this color.

==> proxmox-iso.windows-11: Starting Packer Proxmox API...
==> proxmox-iso.windows-11: Creating VM...
==> proxmox-iso.windows-11: Mounting ISO...
==> proxmox-iso.windows-11: Starting VM...
==> proxmox-iso.windows-11: Waiting for WinRM...
==> proxmox-iso.windows-11: Provisioning with PowerShell...
==> proxmox-iso.windows-11: Gracefully shutting down VM...
==> proxmox-iso.windows-11: Converting to template...
==> proxmox-iso.windows-11: Build complete!

---

Post-Build Steps

1. Verify Template Creation

ssh root@la-vmh-07.loopaware.com "qm list | grep win11-ltsc"

Expected output:

  9000  win11-ltsc-template              running   8192

2. Note the VM ID

VM ID: 9000

3. Update Terraform

Edit terraform/variables.tf and update:

variable "template_vm_id" {
  default = 9000  # Your VM ID here
}

4. Test Provisioning

cd terraform
tofu init
tofu apply -auto-approve

---

Troubleshooting

ISO Not Found

# Verify ISO location
ssh root@la-vmh-07.loopaware.com "pvesm status"
ssh root@la-vmh-07.loopaware.com "ls -la /mnt/pve-07-iso-nvme/template/iso/"

Fix: Ensure ISOs are in /mnt/pve-07-iso-nvme/template/iso/

WinRM Timeout

# Check Autounattend.xml
cat packer/Autounattend.xml | grep -A5 "FirstLogonCommands"

Fix: Verify WinRM configuration in Autounattend.xml

Permission Denied

# Verify API token permissions in Proxmox GUI
# Datacenter -> API Tokens

Fix: Ensure token has VM.Admin privileges

---

Build Time Estimates

Phase	Duration
VM Creation	1-2 min
Windows Install	8-12 min
Driver Installation	2-3 min
Sysprep/Shutdown	1-2 min
Total	15-20 min

---

Next Steps

After successful build:

1. ✅ Template created in Proxmox
2. 📝 Update Terraform VM ID
3. 🔄 Run full pipeline with Forgejo Actions
4. 📊 Monitor builds in Proxmox

---

Quick Command Reference

# Full build command
./build-template.sh --node la-vmh-07 --password "root-password"

# Validate only
./build-template.sh --node la-vmh-07 --check

# Check Proxmox
ssh root@la-vmh-07.loopaware.com "qm list"

# Check ISOs
ssh root@la-vmh-07.loopaware.com "ls -la /mnt/pve-07-iso-nvme/template/iso/"