feat: Add professional hierarchical documentation
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 comprehensive README.md with Mermaid diagrams, badges, and TOC - Added docs/ directory with 7 sections and 14 markdown files - Included architecture diagrams, flowcharts, and sequence diagrams - All documentation is fully interlinked with cross-references - Added ISO storage location on Proxmox development server - Included troubleshooting guide and evaluation management docs - All config files (Packer, Terraform, Ansible, Forgejo) documented - Added icons and visual elements throughout documentation
This commit is contained in:
root
parent
faf04d69f8
commit
e4f03427b7
24 changed files with 3844 additions and 2 deletions
238
docs/03-packer/autounattend.md
Normal file
238
docs/03-packer/autounattend.md
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
# 📝 Autounattend.xml Guide
|
||||
|
||||
[](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/)
|
||||
|
||||
## Overview
|
||||
|
||||
The `Autounattend.xml` file provides automated answers to Windows Setup questions. Packer injects this file to enable fully automated installation.
|
||||
|
||||
**File Location:** [`packer/Autounattend.xml`](../../packer/Autounattend.xml)
|
||||
|
||||
---
|
||||
|
||||
## XML Structure
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Unattend["Autounattend.xml"]
|
||||
direction TB
|
||||
Root[<unattend>] --> WindowsPE["pass='windowsPE'"] --> Specialize["pass='specialize'"]
|
||||
Specialize --> OOBE["pass='oobeSystem'"] --> UserAccounts["<UserAccounts>"]
|
||||
OOBE --> AutoLogon["<AutoLogon>"] --> FirstLogon["<FirstLogonCommands>"]
|
||||
end
|
||||
|
||||
subgraph Purpose["Each Section"]
|
||||
WindowsPE[Language, Setup UI]
|
||||
Specialize[Computer Name, Timezone]
|
||||
OOBE[User Account, OOBE Screens]
|
||||
FirstLogon[WinRM, Firewall]
|
||||
end
|
||||
|
||||
Unattend --> Purpose
|
||||
|
||||
style Unattend fill:#e3f2fd
|
||||
style Purpose fill:#e8f5e9
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Configuration
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<unattend xmlns="urn:schemas-microsoft-com:unattend">
|
||||
|
||||
<!-- === Windows PE Phase === -->
|
||||
<settings pass="windowsPE">
|
||||
<component name="Microsoft-Windows-International-Core-WinPE"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<SetupUILanguage>
|
||||
<UILanguage>en-US</UILanguage>
|
||||
</SetupUILanguage>
|
||||
<InputLocale>en-US</InputLocale>
|
||||
<SystemLocale>en-US</SystemLocale>
|
||||
<UILanguage>en-US</UILanguage>
|
||||
<UserLocale>en-US</UserLocale>
|
||||
</component>
|
||||
|
||||
<component name="Microsoft-Windows-Setup"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<UserData>
|
||||
<ProductKey>
|
||||
<Key></Key> <!-- Evaluation version: no key needed -->
|
||||
</ProductKey>
|
||||
<AcceptEula>true</AcceptEula>
|
||||
</UserData>
|
||||
</component>
|
||||
</settings>
|
||||
|
||||
<!-- === Specialize Phase === -->
|
||||
<settings pass="specialize">
|
||||
<component name="Microsoft-Windows-Shell-Setup"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<ComputerName>*</ComputerName> <!-- Auto-generate name -->
|
||||
</component>
|
||||
|
||||
<component name="Microsoft-Windows-International-Core"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<InputLocale>en-US</InputLocale>
|
||||
<SystemLocale>en-US</SystemLocale>
|
||||
<UILanguage>en-US</UILanguage>
|
||||
<UserLocale>en-US</UserLocale>
|
||||
</component>
|
||||
|
||||
<component name="Microsoft-Windows-TerminalServices-LocalSessionManager"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<fDenyTSConnections>false</fDenyTSConnections>
|
||||
</component>
|
||||
</settings>
|
||||
|
||||
<!-- === OOBE System Phase === -->
|
||||
<settings pass="oobeSystem">
|
||||
<component name="Microsoft-Windows-Shell-Setup"
|
||||
processorArchitecture="amd64"
|
||||
publicKeyToken="31bf3856ad364e35"
|
||||
language="neutral"
|
||||
versionScope="nonSxS">
|
||||
<OOBE>
|
||||
<HideEULAPage>true</HideEULAPage>
|
||||
<HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE>
|
||||
<HideOnlineAccountScreens>true</HideOnlineAccountScreens>
|
||||
<HideLocalAccountScreen>false</HideLocalAccountScreen>
|
||||
<ProtectYourPC>3</ProtectYourPC>
|
||||
</OOBE>
|
||||
|
||||
<!-- Administrator Password -->
|
||||
<UserAccounts>
|
||||
<AdministratorPassword>
|
||||
<Value>PackerPassword123!</Value>
|
||||
<PlainText>true</PlainText>
|
||||
</AdministratorPassword>
|
||||
</UserAccounts>
|
||||
|
||||
<!-- Auto-login (Count=1 = login once) -->
|
||||
<AutoLogon>
|
||||
<Enabled>true</Enabled>
|
||||
<Username>Administrator</Username>
|
||||
<LogonCount>1</LogonCount>
|
||||
</AutoLogon>
|
||||
|
||||
<!-- First Logon Commands -->
|
||||
<FirstLogonCommands>
|
||||
<SynchronousCommand wcm:action="add">
|
||||
<CommandLine>powershell -Command "Set-NetFirewallProfile -Profile Private -Enabled False"</CommandLine>
|
||||
<Order>1</Order>
|
||||
</SynchronousCommand>
|
||||
<SynchronousCommand wcm:action="add">
|
||||
<CommandLine>powershell -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1 -OutFile C:\ConfigureRemotingForAnsible.ps1; C:\ConfigureRemotingForAnsible.ps1"</CommandLine>
|
||||
<Order>2</Order>
|
||||
</SynchronousCommand>
|
||||
</FirstLogonCommands>
|
||||
</component>
|
||||
</settings>
|
||||
|
||||
</unattend>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Settings
|
||||
|
||||
### ⚠️ Auto-Login Configuration
|
||||
|
||||
```xml
|
||||
<AutoLogon>
|
||||
<Enabled>true</Enabled>
|
||||
<Username>Administrator</Username>
|
||||
<LogonCount>1</LogonCount> <!-- Login once, then stay logged in -->
|
||||
</AutoLogon>
|
||||
```
|
||||
|
||||
**Why?** Packer needs to connect via WinRM after the OS is installed. Auto-login allows WinRM to be configured and accessed.
|
||||
|
||||
### ⚠️ Firewall Configuration
|
||||
|
||||
```xml
|
||||
<SynchronousCommand wcm:action="add">
|
||||
<CommandLine>powershell -Command "Set-NetFirewallProfile -Profile Private -Enabled False"</CommandLine>
|
||||
<Order>1</Order>
|
||||
</SynchronousCommand>
|
||||
```
|
||||
|
||||
**Why?** Ansible connects via WinRM on the Private network profile. If the firewall blocks WinRM, connection fails.
|
||||
|
||||
### ⚠️ WinRM Enablement
|
||||
|
||||
```xml
|
||||
<SynchronousCommand wcm:action="add">
|
||||
<CommandLine>powershell -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/ansible/ansible/devel/examples/scripts/ConfigureRemotingForAnsible.ps1 -OutFile C:\ConfigureRemotingForAnsible.ps1; C:\ConfigureRemotingForAnsible.ps1"</CommandLine>
|
||||
<Order>2</Order>
|
||||
</SynchronousCommand>
|
||||
```
|
||||
|
||||
**Why?** This script configures WinRM for remote management by Ansible.
|
||||
|
||||
---
|
||||
|
||||
## Pass Phases Explained
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Phases["Windows Setup Phases"]
|
||||
direction LR
|
||||
PE[windowsPE<br/>Pre-installation] --> Spec[specialize<br/>Specialize] --> OOBE[oobeSystem<br/>OOBE] --> Desktop[Desktop<br/>Ready]
|
||||
end
|
||||
|
||||
subgraph Actions["Key Actions"]
|
||||
PE[Load drivers<br/>Setup language] --> Spec[Computer name<br/>Timezone] --> OOBE[Create accounts<br/>Run commands]
|
||||
end
|
||||
|
||||
style Phases fill:#e3f2fd
|
||||
style Actions fill:#e8f5e9
|
||||
```
|
||||
|
||||
| Pass | Purpose | Key Settings |
|
||||
|------|---------|--------------|
|
||||
| `windowsPE` | Pre-installation environment | Language, keyboard |
|
||||
| `specialize` | Specialized configuration | Computer name, timezone |
|
||||
| `oobeSystem` | Out-of-box experience | User accounts, auto-logon, first commands |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| Packer timeout | WinRM not ready | Check FirstLogonCommands order |
|
||||
| Cannot join domain | ComputerName conflict | Use `*` for auto-generate |
|
||||
| Firewall blocking | Private profile enabled | Add firewall disable command |
|
||||
| Auto-login fails | Password complexity | Use simple password for testing |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
| Goal | Next Document |
|
||||
|------|---------------|
|
||||
| Build template | [Packer Configuration](configuration.md) |
|
||||
| View Terraform | [OpenTofu Resources](../04-terraform/main.tf.md) |
|
||||
| Run pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
|
||||
|
||||
---
|
||||
|
||||
[← Documentation Index](../index.md) | [← Packer Configuration](configuration.md) | [→ OpenTofu](../04-terraform/main.tf.md)
|
||||
218
docs/03-packer/configuration.md
Normal file
218
docs/03-packer/configuration.md
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
# 📦 Packer Configuration
|
||||
|
||||
[](https://developer.hashicorp.com/packer)
|
||||
[](https://www.proxmox.com/)
|
||||
|
||||
## Overview
|
||||
|
||||
Packer is used to create a reproducible Windows golden image template. This document details the Packer configuration in [`packer/windows.pkr.hcl`](../../packer/windows.pkr.hcl).
|
||||
|
||||
---
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph PackerConfig["Packer Configuration"]
|
||||
direction TB
|
||||
Block1[packer { required_plugins }] --> Block2[source "proxmox-iso" "windows-11"]
|
||||
Block2 --> Block3[build { sources } + provisioners]
|
||||
end
|
||||
|
||||
subgraph Plugins["Plugins"]
|
||||
Plugin[proxmox >= 1.1.0]
|
||||
end
|
||||
|
||||
subgraph Sources["Source Settings"]
|
||||
VM[VM Settings] --> HW[Hardware] --> Storage[Storage] --> Comm[Communicator]
|
||||
end
|
||||
|
||||
PackerConfig --> Plugins
|
||||
PackerConfig --> Sources
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full Configuration
|
||||
|
||||
```hcl
|
||||
packer {
|
||||
required_plugins {
|
||||
proxmox = {
|
||||
version = ">= 1.1.0"
|
||||
source = "github.com/hashicorp/proxmox"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
source "proxmox-iso" "windows-11" {
|
||||
# === Connection ===
|
||||
proxmox_url = "https://proxmox-host:8006/api2/json"
|
||||
username = "root@pam"
|
||||
password = "secret"
|
||||
node = "la-vmh-07"
|
||||
|
||||
# === VM Settings ===
|
||||
vm_name = "win11-ltsc-template"
|
||||
template_description = "Built with Packer on ${timestamp()}"
|
||||
iso_file = "local:iso/CLIENT_LTSC_EVAL_x64FRE_en-us.iso"
|
||||
|
||||
# === Hardware (Win11 Compliant) ===
|
||||
qemu_agent = true
|
||||
cores = 4
|
||||
memory = 8192
|
||||
machine = "q35"
|
||||
bios = "ovmf"
|
||||
|
||||
# UEFI + TPM 2.0
|
||||
efi_config {
|
||||
efi_storage_pool = "local-lvm"
|
||||
pre_enrolled_keys = true
|
||||
}
|
||||
tpm_config {
|
||||
version = "2.0"
|
||||
tpm_storage_pool = "local-lvm"
|
||||
}
|
||||
|
||||
# === Storage ===
|
||||
scsi_controller = "virtio-scsi-pci"
|
||||
disks {
|
||||
disk_size = "60G"
|
||||
storage_pool = "local-lvm"
|
||||
type = "virtio"
|
||||
format = "raw"
|
||||
cache_mode = "writeback"
|
||||
}
|
||||
|
||||
# === Additional ISOs ===
|
||||
additional_iso_files {
|
||||
device = "sata1"
|
||||
iso_file = "local:iso/virtio-win.iso"
|
||||
}
|
||||
|
||||
# === Communicator (WinRM) ===
|
||||
communicator = "winrm"
|
||||
winrm_username = "Administrator"
|
||||
winrm_password = "PackerPassword123!"
|
||||
winrm_insecure = true
|
||||
winrm_use_ssl = true
|
||||
|
||||
# === Boot Command ===
|
||||
boot_command = [
|
||||
"<wait><wait><wait>", "<enter><wait>", "<enter><wait>",
|
||||
"<enter><wait>", "<enter>"
|
||||
]
|
||||
boot_wait = "10s"
|
||||
}
|
||||
|
||||
build {
|
||||
sources = ["source.proxmox-iso.windows-11"]
|
||||
|
||||
# === Provisioners ===
|
||||
provisioner "powershell" {
|
||||
inline = [
|
||||
# Install VirtIO storage driver
|
||||
"pnputil /add-driver 'E:\\viostor\\w11\\amd64\\*.inf' /install",
|
||||
# Install VirtIO network driver
|
||||
"pnputil /add-driver 'E:\\NetKVM\\w11\\amd64\\*.inf' /install",
|
||||
# Install VirtIO guest tools
|
||||
"& 'E:\\virtio-win-guest-tools.exe' /install /passive /norestart"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section Details
|
||||
|
||||
### Connection Settings
|
||||
|
||||
| Setting | Value | Description |
|
||||
|---------|-------|-------------|
|
||||
| `proxmox_url` | `https://proxmox-host:8006/api2/json` | Proxmox API endpoint |
|
||||
| `username` | `root@pam` | Authentication user |
|
||||
| `password` | `secret` | Authentication password |
|
||||
| `node` | `la-vmh-07` | Target Proxmox node |
|
||||
|
||||
### Hardware Configuration
|
||||
|
||||
| Setting | Value | Notes |
|
||||
|---------|-------|-------|
|
||||
| `cores` | 4 | Windows 11 minimum |
|
||||
| `memory` | 8192 | 8 GB RAM |
|
||||
| `machine` | `q35` | Modern chipset |
|
||||
| `bios` | `ovmf` | UEFI firmware |
|
||||
|
||||
### Storage Configuration
|
||||
|
||||
| Setting | Value | Notes |
|
||||
|---------|-------|-------|
|
||||
| `disk_size` | 60G | 60 GB disk |
|
||||
| `storage_pool` | `local-lvm` | LVM storage |
|
||||
| `format` | `raw` | Raw disk format |
|
||||
|
||||
### Boot Command
|
||||
|
||||
```hcl
|
||||
boot_command = [
|
||||
"<wait><wait><wait>", # Wait 30 seconds
|
||||
"<enter><wait>", # Press Enter (handle "Press any key")
|
||||
"<enter><wait>", # Confirm boot
|
||||
"<enter><wait>", # Continue installation
|
||||
"<enter>" # Final confirmation
|
||||
]
|
||||
boot_wait = "10s" # Initial wait before sending commands
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Provisioners
|
||||
|
||||
### PowerShell Provisioner
|
||||
|
||||
The PowerShell provisioner installs VirtIO drivers:
|
||||
|
||||
```powershell
|
||||
# Install VirtIO storage driver
|
||||
pnputil /add-driver 'E:\viostor\w11\amd64\*.inf' /install
|
||||
|
||||
# Install VirtIO network driver
|
||||
pnputil /add-driver 'E:\NetKVM\w11\amd64\*.inf' /install
|
||||
|
||||
# Install VirtIO guest tools (silent)
|
||||
& 'E:\virtio-win-guest-tools.exe' /install /passive /norestart
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Process
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph BuildSteps["Packer Build Process"]
|
||||
direction TB
|
||||
Start[Start Build] --> Create[Create VM] --> MountISO[Mount ISO] --> Install[Windows Install] --> InstallDrivers[Install Drivers] --> Shutdown[Shutdown] --> Template[Convert to Template]
|
||||
end
|
||||
|
||||
subgraph InstallActions["Windows Setup"]
|
||||
Boot[Boot from ISO] --> WinSetup[Windows Setup] --> OOBE[OOBE - Autounattend.xml] --> Desktop[Desktop - WinRM Ready]
|
||||
end
|
||||
|
||||
style BuildSteps fill:#e3f2fd
|
||||
style InstallActions fill:#e8f5e9
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
| Goal | Next Document |
|
||||
|------|---------------|
|
||||
| Configure Autounattend.xml | [Autounattend.xml Guide](autounattend.md) |
|
||||
| Build the template | Run `packer build windows.pkr.hcl` |
|
||||
| View Terraform | [OpenTofu Resources](../04-terraform/main.tf.md) |
|
||||
|
||||
---
|
||||
|
||||
[← Documentation Index](../index.md) | [→ Autounattend.xml](autounattend.md) | [← ISO Requirements](../02-prerequisites/isos.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue