🖥️ Windows Automation on Proxmox

📋 Table of Contents

1. Overview
2. Architecture
3. Quick Start
4. Project Structure
5. Documentation Index
6. Prerequisites
7. Pipeline Phases
8. Advanced Topics
9. Contributing

---

🚀 Overview

This repository contains a complete automated build, package, and test pipeline for Windows applications using infrastructure as code. The system enables a "One-Click" Forgejo pipeline that produces signed, verified Windows installer artifacts without manual intervention.

Key Features

• 🔧 Automated Golden Image Creation - Packer builds reproducible Windows templates
• ☁️ Ephemeral Infrastructure - OpenTofu provisions temporary Windows VMs for testing
• 🔐 Code Signing - Linux-native code signing with timestamp verification
• ✅ Automated Testing - Ansible verifies installations on live Windows VMs
• 🔄 Cross-Platform Compilation - MinGW cross-compilation for Windows on Linux

---

🏗️ Architecture

flowchart TB
    subgraph CI["Forgejo CI/CD"]
        direction LR
        C[Checkout] --> X[Cross-Compile<br/>MinGW] --> P[Package<br/>NSIS] --> S[Sign<br/>osslsigncode]
    end
    
    subgraph Build["Build Phase"]
        P --> B[Packer Build<br/>Windows Template]
        B --> T[OpenTofu Provision<br/>Windows VM]
    end
    
    subgraph Verify["Verification Phase"]
        S --> A[Ansible Test<br/>Smoke Test]
        T --> A
    end
    
    subgraph Artifacts["Output"]
        A --> EXE[ installer_signed.exe]
        EXE --> Release[Release Artifacts]
    end
    
    CI --> Build --> Verify --> Artifacts
    
    style CI fill:#e1f5fe
    style Build fill:#e8f5e9
    style Verify fill:#fff3e0
    style Artifacts fill:#fce4ec

Pipeline Flow

Phase	Technology	Purpose
1. Build	Packer	Create Windows golden image template
2. Provision	OpenTofu	Spin up ephemeral Windows test VMs
3. Compile	MinGW	Cross-compile Windows applications on Linux
4. Package	NSIS	Create Windows installer packages
5. Sign	osslsigncode	Code-sign binaries with timestamp
6. Verify	Ansible	Test installation on live Windows VM

---

⚡ Quick Start

Prerequisites

Before beginning, ensure ISOs are available on Proxmox:

# ISO Storage Location
/mnt/pve-07-iso-nvme/template/iso/

Required Files:

• CLIENT_LTSC_EVAL_x64FRE_en-us.iso - Windows 11 LTSC 2024
• virtio-win.iso - VirtIO drivers for I/O performance

Download Sources:

• Windows 11 Enterprise
• VirtIO Drivers

Step 1: Build Golden Image

cd packer
packer init .
packer build windows.pkr.hcl

Step 2: Provision Test Environment

cd terraform
tofu init
export PM_API_TOKEN_ID="your-token-id"
export PM_API_TOKEN_SECRET="your-token-secret"
tofu apply -auto-approve

Step 3: Run Verification

ansible-playbook -i inventory.ini ../ansible/pipeline.yml

---

📁 Project Structure

windows-iac-vm-tooling/
├── 📄 README.md                    # ← Entry point (this file)
├── 📄 doc.tex                      # Full LaTeX documentation
├── 📄 LICENSE                      # MIT License
├── 📄 installer.nsi                # NSIS installer script
├── 📁 .forgejo/
│   └── 📁 workflows/
│       └── 📄 release.yml          # Forgejo CI/CD pipeline
├── 📁 ansible/
│   └── 📄 pipeline.yml             # Ansible verification playbook
├── 📁 docs/                        # Hierarchical documentation
│   ├── 📄 index.md                 # Documentation index
│   ├── 📁 01-overview/
│   │   └── 📄 architecture.md      # Detailed architecture
│   ├── 📁 02-prerequisites/
│   │   ├── 📄 isos.md              # ISO requirements
│   │   └── 📄 secrets.md           # Secret management
│   ├── 📁 03-packer/
│   │   ├── 📄 configuration.md    # Packer HCL config
│   │   └── 📄 autounattend.md      # Windows answer file
│   ├── 📁 04-terraform/
│   │   ├── 📄 main.tf.md           # OpenTofu resources
│   │   └── 📄 variables.md         # Terraform variables
│   ├── 📁 05-ansible/
│   │   └── 📄 pipeline.md          # Ansible playbook guide
│   ├── 📁 06-ci-cd/
│   │   └── 📄 forgejo-workflows.md # CI/CD pipeline details
│   └── 📁 07-advanced/
│       ├── 📄 evaluation.md         # 90-day evaluation management
│       └── 📄 troubleshooting.md   # Common issues & solutions
├── 📁 packer/
│   ├── 📄 windows.pkr.hcl          # Packer template configuration
│   └── 📄 Autounattend.xml         # Windows unattended installation
├── 📁 src/
│   └── 📄 main.c                   # Example Windows application
└── 📁 terraform/
    ├── 📄 main.tf                  # OpenTofu main configuration
    ├── 📄 variables.tf              # Input variables
    └── 📄 outputs.tf               # Output values

---

📚 Documentation Index

Getting Started

• Documentation Index - Complete navigation guide
• Architecture Overview - System design and components

Prerequisites

• ISO Requirements - Download and placement instructions
• Secret Management - Configure required credentials

Implementation Guides

• Packer Configuration - Build Windows templates
• Autounattend.xml Guide - Windows installation automation
• OpenTofu Resources - Infrastructure as code
• Ansible Pipeline - Automated testing
• Forgejo Workflows - CI/CD pipeline reference

Advanced Topics

• Evaluation Management - Handle 90-day expiration
• Troubleshooting - Debug common issues

---

📋 Prerequisites

Required ISO Images on Proxmox Storage

Storage Location: /mnt/pve-07-iso-nvme/template/iso/

File	Description	Required
CLIENT_LTSC_EVAL_x64FRE_en-us.iso	Windows 11 LTSC 2024	✅ Yes
virtio-win.iso	VirtIO drivers	✅ Yes
SERVER_EVAL_x64FRE_en-us.iso	Windows Server 2022	Optional
26100.1742.240906-0331...iso	Alternate Windows 11	Optional

Required Secrets

Configure these in your Forgejo repository settings:

Secret	Description	Usage
PFX_PASS	Code signing certificate password	osslsigncode sign
PM_TOKEN_ID	Proxmox API token ID	tofu apply
PM_TOKEN_SECRET	Proxmox API token secret	tofu apply
WIN_ADMIN_PASS	Windows Administrator password	Ansible connection

---

🔄 Pipeline Phases

Phase 1: Automated Image Build (Packer)

flowchart LR
    subgraph Packer["Packer Process"]
        ISO[Mount ISO] --> VM[Create VM] --> Install[Windows Install] --> Drivers[Install VirtIO] --> Template[Convert to Template]
    end
    
    Packer --> Output[Windows Golden Image]
    
    style Packer fill:#e3f2fd
    style Output fill:#c8e6c9

Related Documentation:

• Packer Configuration
• Autounattend.xml Guide

Phase 2: Infrastructure as Code (OpenTofu)

flowchart TB
    subgraph OpenTofu["OpenTofu Workflow"]
        Init[tofu init] --> Plan[tofu plan] --> Apply[tofu apply] --> VM[Provision VM] --> Test[Test] --> Destroy[tofu destroy]
    end
    
    Input[Template VM ID] --> VM
    Output[VM IP Address] --> Test
    
    style OpenTofu fill:#f3e5f5
    style Input fill:#fff3e0
    style Output fill:#e8f5e9

Related Documentation:

• OpenTofu Resources
• Terraform Variables

Phase 3: Cross-Compile & Package (Linux)

flowchart LR
    subgraph Linux["Linux Build Container"]
        Src[Source Code] --> Compile[MinGW GCC] --> Binary[app.exe] --> Package[NSIS] --> Installer[installer.exe]
    end
    
    Compile --> Sign[osslsigncode] --> Signed[installer_signed.exe]
    
    style Linux fill:#e0f7fa
    style Signed fill:#c8e6c9

Related Documentation:

• Forgejo Workflows

Phase 4: Verification (Ansible)

flowchart TB
    subgraph Ansible["Ansible Verification"]
        Upload[Upload Installer] --> Install[Silent Install] --> Verify[Check Installation] --> Assert[Pass/Fail]
    end
    
    VM[Windows VM] --> Upload
    Assert --> Report[Test Report]
    
    style Ansible fill:#fff8e1
    style Report fill:#e8f5e9

Related Documentation:

• Ansible Pipeline

---

🔧 Advanced Topics

Managing the 90-Day Evaluation

Windows Evaluation ISO expires after 90 days. Two management strategies:

Method	Command	Limit
Rearm	slmgr /rearm	3 times
Rebuild	Monthly Packer build	Unlimited

Recommended Approach: Schedule a monthly Packer build in Forgejo to regenerate the Golden Template, ensuring:

• Fresh 90-day timer
• Latest security updates
• Consistent baseline

Troubleshooting

Common Issues:

Issue	Cause	Solution
Packer timeout	WinRM not configured	Check Autounattend.xml settings
VM won't boot	ISO not found	Verify Proxmox storage path
Ansible connection	Firewall enabled	Disable Private profile firewall
Code signing fails	Invalid PFX	Verify certificate password

Related Documentation:

• Troubleshooting Guide

---

🤝 Contributing

1. Review the architecture documentation
2. Follow existing code patterns in configuration files
3. Update relevant documentation when making changes
4. Test changes in development environment before committing

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📞 Support

• Documentation: See docs/index.md for complete navigation
• Issues: Report via GitHub Issues
• Discussion: Use GitHub Discussions

---

Last Updated: February 2026 Target: Windows 11 Enterprise LTSC 2024