docs: Add comprehensive build instructions
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
- 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
This commit is contained in:
root
parent
61ae0d0a07
commit
5cc158d641
1 changed files with 300 additions and 0 deletions
300
BUILD.md
Normal file
300
BUILD.md
Normal file
|
|
@ -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/"
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue