e4f03427b7
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
355 lines
11 KiB
Markdown
355 lines
11 KiB
Markdown
# 🖥️ Windows Automation on Proxmox
|
|
|
|
<!-- Badges and metadata -->
|
|
[](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<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*
|