# 🖥️ Windows Automation on Proxmox
[](LICENSE)
[](.forgejo/workflows/release.yml)
[](https://www.microsoft.com/en-us/windows/windows-11-enterprise)
## 📋 Table of Contents
1. [Overview](#-overview)
2. [Architecture](#-architecture)
3. [Quick Start](#-quick-start)
4. [Project Structure](#-project-structure)
5. [Documentation Index](#-documentation-index)
6. [Prerequisites](#-prerequisites)
7. [Pipeline Phases](#-pipeline-phases)
8. [Advanced Topics](#-advanced-topics)
9. [Contributing](#-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
```mermaid
flowchart TB
subgraph CI["Forgejo CI/CD"]
direction LR
C[Checkout] --> X[Cross-Compile
MinGW] --> P[Package
NSIS] --> S[Sign
osslsigncode]
end
subgraph Build["Build Phase"]
P --> B[Packer Build
Windows Template]
B --> T[OpenTofu Provision
Windows VM]
end
subgraph Verify["Verification Phase"]
S --> A[Ansible Test
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:
```bash
# 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](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
- [VirtIO Drivers](https://github.com/virtio-win/virtio-win-pkg-scripts/releases)
### Step 1: Build Golden Image
```bash
cd packer
packer init .
packer build windows.pkr.hcl
```
### Step 2: Provision Test Environment
```bash
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
```bash
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](docs/index.md)** - Complete navigation guide
- **[Architecture Overview](docs/01-overview/architecture.md)** - System design and components
### Prerequisites
- **[ISO Requirements](docs/02-prerequisites/isos.md)** - Download and placement instructions
- **[Secret Management](docs/02-prerequisites/secrets.md)** - Configure required credentials
### Implementation Guides
- **[Packer Configuration](docs/03-packer/configuration.md)** - Build Windows templates
- **[Autounattend.xml Guide](docs/03-packer/autounattend.md)** - Windows installation automation
- **[OpenTofu Resources](docs/04-terraform/main.tf.md)** - Infrastructure as code
- **[Ansible Pipeline](docs/05-ansible/pipeline.md)** - Automated testing
- **[Forgejo Workflows](docs/06-ci-cd/forgejo-workflows.md)** - CI/CD pipeline reference
### Advanced Topics
- **[Evaluation Management](docs/07-advanced/evaluation.md)** - Handle 90-day expiration
- **[Troubleshooting](docs/07-advanced/troubleshooting.md)** - 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)
```mermaid
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](docs/03-packer/configuration.md)
- [Autounattend.xml Guide](docs/03-packer/autounattend.md)
### Phase 2: Infrastructure as Code (OpenTofu)
```mermaid
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](docs/04-terraform/main.tf.md)
- [Terraform Variables](docs/04-terraform/variables.md)
### Phase 3: Cross-Compile & Package (Linux)
```mermaid
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](docs/06-ci-cd/forgejo-workflows.md)
### Phase 4: Verification (Ansible)
```mermaid
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](docs/05-ansible/pipeline.md)
---
## 🔧 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](docs/07-advanced/troubleshooting.md)
---
## 🤝 Contributing
1. Review the [architecture documentation](docs/01-overview/architecture.md)
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](LICENSE) file for details.
---
## 📞 Support
- **Documentation:** See [docs/index.md](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*