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

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

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

**Expected output:** `la-vmh-07`

---

## Step 2: Install Packer on Proxmox

### Option A: On Proxmox Host

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

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

```bash
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

```bash
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

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

---

## Step 5: Run the Build

### Using the Build Script (Recommended)

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

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

```mermaid
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

```bash
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:

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

### 4. Test Provisioning

```bash
cd terraform
tofu init
tofu apply -auto-approve
```

---

## Troubleshooting

### ISO Not Found

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

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

**Fix:** Verify WinRM configuration in Autounattend.xml

### Permission Denied

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

```bash
# 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/"
```