feat: Add professional hierarchical documentation

- 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
2026-02-06 14:47:15 +00:00 · 2026-02-06 14:47:15 +00:00 · e4f03427b7
commit e4f03427b7
parent faf04d69f8
24 changed files with 3844 additions and 2 deletions
--- a/docs/07-advanced/evaluation.md
+++ b/docs/07-advanced/evaluation.md
@ -0,0 +1,200 @@
+# ⏰ 90-Day Evaluation Management
+
+[![Windows](https://img.shields.io/badge/Windows-Evaluation-0078D6?style=flat&logo=windows)](https://www.microsoft.com/en-us/evalcenter/)
+
+## Overview
+
+Windows Evaluation editions expire after 90 days. This document explains the expiration mechanism and provides strategies for managing it in your automation pipeline.
+
+---
+
+## Understanding Evaluation Expiration
+
+```mermaid
+flowchart LR
+    subgraph Timeline["90-Day Timeline"]
+        Start[Install Day 0] --> Day30[Day 30] --> Day60[Day 60] --> Day90[Day 90 - Expiration]
+    end
+    
+    subgraph States["System States"]
+        Active[✅ Active] --> Warning[⚠️ Warning 15 days] --> Expired[❌ Expired]
+    end
+    
+    Timeline --> States
+    
+    style Timeline fill:#e3f2fd
+    style States fill:#e8f5e9
+```
+
+| Phase | Duration | Status |
+|-------|----------|--------|
+| **Full Activation** | Days 0-89 | ✅ Fully functional |
+| **Warning Period** | Days 90-104 | ⚠️ Countdown warnings |
+| **Grace Period** | Days 105-180 | ⏳ Extended grace |
+| **Expired** | Day 181+ | ❌ System stops |
+
+---
+
+## Expiration Methods
+
+### Method 1: Rearm (Manual/Scripted)
+
+The `slmgr /rearm` command resets the activation timer.
+
+```powershell
+# Run as Administrator
+slmgr /rearm
+
+# Reboot required
+shutdown /r /t 0
+```
+
+**Limits:**
+- Maximum 3 rearm attempts per installation
+- Each rearm resets to 90 days
+- **Total: 360 days maximum**
+
+### Method 2: Packer Rebuild (Recommended)
+
+The recommended approach is to **rebuild the golden image monthly**.
+
+```mermaid
+flowchart TB
+    subgraph Monthly["Monthly Schedule"]
+        direction LR
+        Week1[Week 1: Packer Build] --> Week2[Week 2-4: Use Template]
+    end
+    
+    subgraph Process["Rebuild Process"]
+        Destroy[Destroy Old Template] --> Create[Create New Template] --> Verify[Test New Template]
+    end
+    
+    Monthly --> Process
+    
+    style Monthly fill:#e3f2fd
+    style Process fill:#e8f5e9
+```
+
+**Benefits:**
+- Fresh timer each month
+- Latest Windows updates baked in
+- Consistent baseline
+- No rearm limitations
+
+---
+
+## Implementation Strategy
+
+### Automated Monthly Rebuild
+
+Configure a scheduled workflow in Forgejo:
+
+```yaml
+# .forgejo/workflows/monthly-rebuild.yml
+name: Monthly Template Rebuild
+on:
+  schedule:
+    - cron: '0 0 1 * *'  # First day of each month at midnight
+
+jobs:
+  rebuild-template:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      
+      - name: Build New Template
+        run: |
+          cd packer
+          packer build -timestamp-ui windows.pkr.hcl
+      
+      - name: Cleanup Old Template
+        run: |
+          # Script to remove template older than 45 days
+          ./scripts/cleanup-old-templates.sh --older-than 45d
+```
+
+### Rebarm as Backup
+
+For emergency extension:
+
+```powershell
+# emergency-rearm.ps1
+# Run via Ansible or manually
+
+if ((slmgr /dlv) -match "Remaining: 0") {
+    Write-Host "Rearming system..."
+    slmgr /rearm
+    shutdown /r /t 0
+} else {
+    Write-Host "Not yet expired, no action needed"
+}
+```
+
+---
+
+## Monitoring Expiration
+
+### Check Current Status
+
+```powershell
+# Method 1: slmgr
+slmgr /dlv
+
+# Method 2: PowerShell
+(Get-CimInstance -Query "SELECT * FROM SoftwareLicensingProduct WHERE PartialProductKey IS NOT NULL").RemainingGracePeriod
+```
+
+### Automated Monitoring Script
+
+```bash
+#!/bin/bash
+# check-expiration.sh - Run via Ansible monthly
+
+VM_ID="9000"
+PROXMOX_HOST="la-vmh-07"
+
+# Get VM's Windows activation status
+ssh root@$PROXMOX_HOST "qm agent $VM_ID exec-win32 powershell -Command '(Get-CimInstance -Query \"SELECT * FROM SoftwareLicensingProduct WHERE PartialProductKey IS NOT NULL\").RemainingGracePeriod'"
+
+# Alert if less than 7 days
+if [ $DAYS_REMAINING -lt 7 ]; then
+    echo "⚠️ ALERT: Template expires in $DAYS_REMAINING days"
+    # Send notification
+fi
+```
+
+---
+
+## Best Practices
+
+| Practice | Description | Priority |
+|----------|-------------|----------|
+| **Monthly rebuild** | Schedule automatic Packer build | 🔴 High |
+| **Monitor expiration** | Check status weekly | 🟡 Medium |
+| **Test new templates** | Verify before production use | 🔴 High |
+| **Document rebuilds** | Log template versions | 🟢 Low |
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Rearm failed | Already rearmed 3 times | Rebuild with Packer |
+| VM won't boot after rearm | Activation issues | Rebuild template |
+| Updates not installing | WSUS offline | Include updates in Packer build |
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| View troubleshooting | [Troubleshooting](troubleshooting.md) |
+| Configure pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
+| View architecture | [Architecture Overview](../01-overview/architecture.md) |
+
+---
+
+[← Documentation Index](../index.md) | [→ Troubleshooting](troubleshooting.md) | [← Forgejo Workflows](../06-ci-cd/forgejo-workflows.md)
--- a/docs/07-advanced/troubleshooting.md
+++ b/docs/07-advanced/troubleshooting.md
@ -0,0 +1,273 @@
+# 🔧 Troubleshooting Guide
+
+[![Debug](https://img.shields.io/badge/Troubleshooting-Common%20Issues-yellow)]()
+
+## Overview
+
+This guide covers common issues and their solutions for the Windows automation pipeline.
+
+---
+
+## Quick Fix Index
+
+| Issue | Phase | Quick Fix |
+|-------|-------|-----------|
+| Packer timeout | Build | Check Autounattend.xml WinRM config |
+| VM won't boot | Provision | Verify ISO paths in Packer |
+| Ansible connection | Test | Disable Windows firewall |
+| Code signing fails | Build | Verify PFX password |
+| Template expired | All | Rebuild with Packer |
+
+---
+
+## Phase 1: Packer Issues
+
+### Timeout Waiting for WinRM
+
+**Symptom:**
+```
+==> proxmox-iso.windows-11: Timeout waiting for WinRM.
+```
+
+**Cause:** Windows not fully booted or WinRM not configured.
+
+**Solution:**
+1. Verify `Autounattend.xml` has WinRM configuration
+2. Check boot command timing
+3. Increase `boot_wait` duration
+
+```hcl
+# Increase boot wait
+boot_wait = "30s"
+
+# Check boot command
+boot_command = [
+  "<wait><wait><wait><wait><wait>",
+  "<enter><wait><wait>",
+  "<enter>"
+]
+```
+
+---
+
+### ISO Not Found
+
+**Symptom:**
+```
+==> proxmox-iso.windows-iso: ISO file not found: local:iso/...
+```
+
+**Cause:** Wrong ISO path or storage.
+
+**Solution:**
+1. Verify ISO location on Proxmox
+2. Check storage name (local vs local-lvm)
+
+```bash
+# On Proxmox host
+ls -la /mnt/pve-07-iso-nvme/template/iso/
+qm storage
+```
+
+---
+
+## Phase 2: OpenTofu Issues
+
+### Clone Failed
+
+**Symptom:**
+```
+Error: resource is not a cloneable VM
+```
+
+**Cause:** Wrong VM ID or template not found.
+
+**Solution:**
+1. Verify template VM exists
+2. Check VM ID is correct
+
+```bash
+# On Proxmox host
+qm list | grep template
+```
+
+---
+
+### Permission Denied
+
+**Symptom:**
+```
+Error: permission denied (400)
+```
+
+**Cause:** Proxmox API token lacks privileges.
+
+**Solution:**
+1. Add VM.Admin role to token
+2. Verify token is not expired
+
+---
+
+## Phase 3: Ansible Issues
+
+### WinRM Connection Timeout
+
+**Symptom:**
+```
+fatal: [10.0.0.5]: UNREACHABLE! => {"msg": "Connection timeout"}
+```
+
+**Cause:** Firewall blocking WinRM or WinRM not configured.
+
+**Solution:**
+```yaml
+# In Autounattend.xml - disable firewall
+<SynchronousCommand wcm:action="add">
+  <CommandLine>powershell -Command "Set-NetFirewallProfile -Profile Private -Enabled False"</CommandLine>
+  <Order>1</Order>
+</SynchronousCommand>
+
+# In inventory - ignore certificate validation
+[windows_vm]
+10.0.0.5 ansible_winrm_server_cert_validation=ignore
+```
+
+---
+
+### Invalid Credentials
+
+**Symptom:**
+```
+fatal: [10.0.0.5]: UNREACHABLE! => {"msg": "Basic auth failed"}
+```
+
+**Cause:** Wrong username or password.
+
+**Solution:**
+```bash
+# Verify secrets are set
+echo $WIN_ADMIN_PASS
+
+# Test manually
+winrs -r:10.0.0.5 -u:Administrator -p:$WIN_ADMIN_PASS "hostname"
+```
+
+---
+
+## Phase 4: Code Signing Issues
+
+### Invalid Certificate
+
+**Symptom:**
+```
+Error: PKCS12_parse failed
+```
+
+**Cause:** Wrong password or corrupted PFX file.
+
+**Solution:**
+```bash
+# Verify certificate
+openssl pkcs12 -in cert.pfx -info -noout -passin pass:$PFX_PASS
+```
+
+---
+
+## Diagnostic Commands
+
+### Proxmox Diagnostics
+
+```bash
+# List VMs
+qm list
+
+# Check VM status
+qm status <VM_ID>
+
+# View VM config
+qm config <VM_ID>
+
+# Check storage
+pvesm status
+```
+
+### Windows Diagnostics
+
+```powershell
+# Check WinRM status
+winrm quickconfig
+Get-WinRM -Service
+
+# Check firewall
+Get-NetFirewallProfile | Select Name, Enabled
+
+# Check activation
+slmgr /dlv
+```
+
+### Ansible Diagnostics
+
+```bash
+# Test WinRM connection
+ansible windows_vm -m win_ping -i inventory.ini
+
+# Verbose output
+ansible-playbook -i inventory.ini pipeline.yml -vvvv
+```
+
+---
+
+## Log Locations
+
+| Component | Log Location |
+|-----------|--------------|
+| Packer | Console output + `packer.log` |
+| OpenTofu | Console output + `.terraform.lock.hcl` |
+| Ansible | Console output + `/var/log/ansible.log` |
+| Windows | Event Viewer → System |
+
+---
+
+## FAQ
+
+### Q: Can I use a different Windows edition?
+
+**A:** Yes, but you need to:
+1. Update ISO in `packer/windows.pkr.hcl`
+2. Modify `Autounattend.xml` for that edition
+3. Update product key settings
+
+### Q: How do I add more software to the template?
+
+**A:** Add PowerShell provisioners:
+
+```hcl
+provisioner "powershell" {
+  inline = [
+    "choco install -y 7zip git vscode",
+    "& 'C:\\ProgramData\\Chocolatey\\bin\\choco.exe' install -y dotnetfx"
+  ]
+}
+```
+
+### Q: The VM has no IP after provisioning
+
+**Cause:** DHCP not working or VirtIO drivers missing.
+
+**Solution:**
+1. Ensure VirtIO drivers are installed in template
+2. Verify network bridge is correct
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| Manage evaluations | [Evaluation Management](evaluation.md) |
+| View pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
+| Full documentation | [Documentation Index](../index.md) |
+
+---
+
+[← Documentation Index](../index.md) | [← Evaluation Management](evaluation.md) | [← Home](../index.md)