From 5cc158d641961c1a1c7edb8c2f7c2253c2c0f191 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 6 Feb 2026 16:03:55 +0000 Subject: [PATCH] docs: Add comprehensive build instructions - Created BUILD.md with step-by-step build guide - Added SSH setup instructions for Proxmox host - Included troubleshooting section - Added build process diagram and time estimates --- BUILD.md | 300 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 BUILD.md diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..0aefa00 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,300 @@ +# 🔨 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/" +```