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
234
docs/01-overview/architecture.md
Normal file
234
docs/01-overview/architecture.md
Normal file
|
|
@ -0,0 +1,234 @@
|
|||
# 🏗️ Architecture Overview
|
||||
|
||||
[](../../.forgejo/workflows/release.yml)
|
||||
[](https://www.microsoft.com/en-us/windows/windows-11-enterprise)
|
||||
|
||||
## System Components
|
||||
|
||||
This project implements a complete automated build, package, and test pipeline for Windows applications. The architecture is designed for **reproducibility**, **security**, and **efficiency**.
|
||||
|
||||
### Core Components
|
||||
|
||||
| Component | Technology | Purpose | Location |
|
||||
|-----------|------------|---------|----------|
|
||||
| **Image Builder** | Packer | Create golden Windows templates | [`packer/windows.pkr.hcl`](../../packer/windows.pkr.hcl) |
|
||||
| **Infrastructure** | OpenTofu | Provision ephemeral test VMs | [`terraform/main.tf`](../../terraform/main.tf) |
|
||||
| **Automation** | Ansible | Verify installations | [`ansible/pipeline.yml`](../../ansible/pipeline.yml) |
|
||||
| **CI/CD** | Forgejo Actions | Orchestrate pipeline | [`.forgejo/workflows/release.yml`](../../.forgejo/workflows/release.yml) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Development["Developer Workflow"]
|
||||
Code[Write Code] --> Commit[Git Commit] --> Push[Git Push]
|
||||
end
|
||||
|
||||
subgraph Pipeline["Forgejo Pipeline"]
|
||||
Push --> |Trigger| Build["Build & Sign"]
|
||||
Build --> Provision["Provision VM"]
|
||||
Provision --> Verify["Verify"]
|
||||
Verify --> Artifacts["Artifacts"]
|
||||
end
|
||||
|
||||
subgraph Build["Build Stage"]
|
||||
direction LR
|
||||
Compile[Cross-Compile<br/>MinGW] --> Package[Package<br/>NSIS] --> Sign[Code Sign<br/>osslsigncode]
|
||||
end
|
||||
|
||||
subgraph Infrastructure["Proxmox Infrastructure"]
|
||||
Template[Windows Template<br/>Packer Built] --> Clone[Clone VM<br/>OpenTofu] --> TestVM[Test VM<br/>Ansible]
|
||||
end
|
||||
|
||||
Build --> Template
|
||||
Provision --> Clone
|
||||
Verify --> TestVM
|
||||
|
||||
style Development fill:#e3f2fd
|
||||
style Pipeline fill:#f3e5f5
|
||||
style Build fill:#e8f5e9
|
||||
style Infrastructure fill:#fff8e1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as Developer
|
||||
participant Forgejo as Forgejo CI/CD
|
||||
participant Proxmox as Proxmox Host
|
||||
participant VM as Windows VM
|
||||
participant Artifact as Artifacts
|
||||
|
||||
Dev->>Forgejo: Push code changes
|
||||
Forgejo->>Forgejo: Cross-compile (MinGW)
|
||||
Forgejo->>Forgejo: Package (NSIS)
|
||||
Forgejo->>Forgejo: Sign binary (osslsigncode)
|
||||
|
||||
Forgejo->>Proxmox: Provision VM (OpenTofu)
|
||||
Proxmox->>VM: Clone from template
|
||||
VM->>VM: Boot Windows
|
||||
|
||||
Forgejo->>VM: Deploy signed installer
|
||||
Forgejo->>VM: Run Ansible playbook
|
||||
VM->>Forgejo: Test results
|
||||
|
||||
alt Test Passed
|
||||
Forgejo->>Artifact: Publish installer
|
||||
else Test Failed
|
||||
Forgejo->>Dev: Notify failure
|
||||
end
|
||||
|
||||
Proxmox->>Proxmox: Destroy VM (cleanup)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Why This Architecture?
|
||||
|
||||
| Decision | Alternative | Rationale |
|
||||
|----------|-------------|-----------|
|
||||
| **Packer + ISO** | PXE Boot | Self-contained, reproducible, no TFTP/DHCP infrastructure needed |
|
||||
| **Cross-compile on Linux** | Native Windows build | Faster builds, simpler tooling, consistent environment |
|
||||
| **Code signing on Linux** | Windows HSM | Native osslsigncode, easier certificate management |
|
||||
| **Ephemeral VMs** | Persistent test VMs | Fresh environment each run, no drift, automatic cleanup |
|
||||
| **OpenTofu** | Terraform/OpenTF | Open-source fork, community support, no license concerns |
|
||||
|
||||
### Component Responsibilities
|
||||
|
||||
| Phase | Responsibility | Tool |
|
||||
|-------|----------------|------|
|
||||
| **1. Build** | Create reproducible Windows template | Packer |
|
||||
| **2. Provision** | Deploy ephemeral test environment | OpenTofu |
|
||||
| **3. Compile** | Build Windows binaries from Linux | MinGW |
|
||||
| **4. Package** | Create installer executable | NSIS |
|
||||
| **5. Sign** | Authenticode signing with timestamp | osslsigncode |
|
||||
| **6. Verify** | Smoke test on live Windows | Ansible |
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph CI["CI/CD Layer"]
|
||||
Forgejo["Forgejo Actions"]
|
||||
ArchLinux["Arch Linux Container"]
|
||||
end
|
||||
|
||||
subgraph Build["Build Layer"]
|
||||
MinGW["MinGW GCC"]
|
||||
NSIS["NSIS"]
|
||||
Sign["osslsigncode"]
|
||||
end
|
||||
|
||||
subgraph Infra["Infrastructure Layer"]
|
||||
OpenTofu["OpenTofu"]
|
||||
Packer["Packer"]
|
||||
Proxmox["Proxmox VE"]
|
||||
end
|
||||
|
||||
subgraph Test["Testing Layer"]
|
||||
Ansible["Ansible"]
|
||||
WinVM["Windows VM"]
|
||||
end
|
||||
|
||||
CI --> Build
|
||||
CI --> Infra
|
||||
Infra --> Test
|
||||
Build --> Test
|
||||
|
||||
style CI fill:#e1f5fe
|
||||
style Build fill:#e8f5e9
|
||||
style Infra fill:#fff3e0
|
||||
style Test fill:#fce4ec
|
||||
```
|
||||
|
||||
| Layer | Technologies |
|
||||
|-------|--------------|
|
||||
| **CI/CD** | Forgejo Actions, Arch Linux container |
|
||||
| **Build Tools** | MinGW GCC, NSIS, osslsigncode |
|
||||
| **Infrastructure** | Packer, OpenTofu, Proxmox VE |
|
||||
| **Testing** | Ansible, Windows 11 LTSC |
|
||||
|
||||
---
|
||||
|
||||
## Environment Details
|
||||
|
||||
### Proxmox Host Configuration
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **Host** | la-vmh-07 |
|
||||
| **API Endpoint** | https://proxmox-host:8006/ |
|
||||
| **Storage** | local-lvm (templates), local (ISOs) |
|
||||
| **Network** | vmbr0 |
|
||||
|
||||
### Windows Configuration
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| **Edition** | Windows 11 Enterprise LTSC 2024 |
|
||||
| **Administrator** | Built-in Administrator account |
|
||||
| **WinRM** | Enabled via ConfigureRemotingForAnsible.ps1 |
|
||||
| **Firewall** | Private profile disabled |
|
||||
|
||||
---
|
||||
|
||||
## File Manifest
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Source["Source Files"]
|
||||
Src["src/main.c"]
|
||||
NSIS["installer.nsi"]
|
||||
end
|
||||
|
||||
subgraph Config["Configuration"]
|
||||
Packer["packer/windows.pkr.hcl"]
|
||||
Answer["packer/Autounattend.xml"]
|
||||
Terraform["terraform/main.tf"]
|
||||
Ansible["ansible/pipeline.yml"]
|
||||
Workflow[".forgejo/workflows/release.yml"]
|
||||
end
|
||||
|
||||
subgraph Docs["Documentation"]
|
||||
Readme["README.md"]
|
||||
Index["docs/index.md"]
|
||||
Arch["docs/01-overview/architecture.md"]
|
||||
end
|
||||
|
||||
Src --> Packer
|
||||
Src --> Workflow
|
||||
NSIS --> Workflow
|
||||
Packer --> Terraform
|
||||
Terraform --> Ansible
|
||||
Ansible --> Workflow
|
||||
Readme --> Index
|
||||
Index --> Arch
|
||||
|
||||
style Source fill:#e3f2fd
|
||||
style Config fill:#e8f5e9
|
||||
style Docs fill:#fff3e0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
| Goal | Next Document |
|
||||
|------|---------------|
|
||||
| Set up prerequisites | [ISO Requirements](../02-prerequisites/isos.md) |
|
||||
| Build template | [Packer Configuration](../03-packer/configuration.md) |
|
||||
| Configure secrets | [Secret Management](../02-prerequisites/secrets.md) |
|
||||
| Run pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
|
||||
|
||||
---
|
||||
|
||||
[← Documentation Index](../index.md) | [→ ISO Requirements](../02-prerequisites/isos.md) | [← README](../../README.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue