windows-iac-vm-tooling/README.md

# 🖥️ Windows Automation on Proxmox

<!-- Badges and metadata -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Pipeline Status](https://img.shields.io/badge/Pipeline-Packer%20%E2%86%92%20OpenTofu%20%E2%86%92%20Forgejo-blue)](.forgejo/workflows/release.yml)
[![Windows Version](https://img.shields.io/badge/Windows-11%20LTSC%202024-0078D6?style=flat&logo=windows)](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<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:

```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*