feat: Add professional hierarchical documentation
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
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
This commit is contained in:
root
parent
faf04d69f8
commit
e4f03427b7
24 changed files with 3844 additions and 2 deletions
356
README.md
356
README.md
|
|
@ -1,3 +1,355 @@
|
|||
# windows-iac-vm-tooling
|
||||
# 🖥️ Windows Automation on Proxmox
|
||||
|
||||
This repo contains scripts and docs on how to create a golden image and then also how to use IaC tooling (OpenTofu, Ansibla and Jinja) to deploy windows build and test machines.
|
||||
<!-- 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*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue