feat: Add professional hierarchical documentation

- 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
2026-02-06 14:47:15 +00:00 · 2026-02-06 14:47:15 +00:00 · e4f03427b7
commit e4f03427b7
parent faf04d69f8
24 changed files with 3844 additions and 2 deletions
--- a/docs/05-ansible/pipeline.md
+++ b/docs/05-ansible/pipeline.md
@ -0,0 +1,195 @@
+# ✅ Ansible Pipeline
+
+[![Ansible](https://img.shields.io/badge/Ansible-Latest-blue?style=flat&logo=ansible)](https://www.ansible.com/)
+
+## Overview
+
+Ansible automates verification of the Windows installer on the provisioned VM. This document details the playbook in [`ansible/pipeline.yml`](../../ansible/pipeline.yml).
+
+---
+
+## Playbook Structure
+
+```mermaid
+flowchart TD
+    subgraph Playbook["Ansible Pipeline"]
+        direction TB
+        Play[Play: Verify Installer] --> Tasks[Tasks List]
+        Tasks --> T1[Create Workspace] --> T2[Upload Installer] --> T3[Install] --> T4[Verify] --> T5[Assert]
+    end
+    
+    subgraph Hosts["Host Selection"]
+        H[windows_vm] --> Play
+    end
+    
+    style Playbook fill:#e3f2fd
+    style Hosts fill:#e8f5e9
+```
+
+---
+
+## Full Playbook
+
+```yaml
+- name: Verify Installer
+  hosts: windows_vm
+  tasks:
+    - name: Create Workspace
+      ansible.windows.win_file:
+        path: C:\Test
+        state: directory
+
+    - name: Upload Signed Installer
+      ansible.windows.win_copy:
+        src: ./dist/installer_signed.exe
+        dest: C:\Test\installer.exe
+
+    - name: Install (Silent Mode)
+      ansible.windows.win_command: C:\Test\installer.exe /S
+      register: install_result
+
+    - name: Verify Executable Exists
+      ansible.windows.win_stat:
+        path: "C:\\Program Files\\MyApp\\app.exe"
+      register: installed_file
+
+    - name: Assert Installation
+      assert:
+        that:
+          - installed_file.stat.exists
+```
+
+---
+
+## Task Details
+
+### 1. Create Workspace
+
+```yaml
+- name: Create Workspace
+  ansible.windows.win_file:
+    path: C:\Test
+    state: directory
+```
+
+**Purpose:** Creates a directory for temporary files on the Windows VM.
+
+### 2. Upload Installer
+
+```yaml
+- name: Upload Signed Installer
+  ansible.windows.win_copy:
+    src: ./dist/installer_signed.exe
+    dest: C:\Test\installer.exe
+```
+
+**Purpose:** Copies the signed installer from the build host to the Windows VM.
+
+### 3. Silent Install
+
+```yaml
+- name: Install (Silent Mode)
+  ansible.windows.win_command: C:\Test\installer.exe /S
+  register: install_result
+```
+
+**Purpose:** Runs the installer in silent mode (`/S` flag).
+
+### 4. Verify Installation
+
+```yaml
+- name: Verify Executable Exists
+  ansible.windows.win_stat:
+    path: "C:\\Program Files\\MyApp\\app.exe"
+  register: installed_file
+```
+
+**Purpose:** Checks if the installed executable exists at the expected path.
+
+### 5. Assert Result
+
+```yaml
+- name: Assert Installation
+  assert:
+    that:
+      - installed_file.stat.exists
+```
+
+**Purpose:** Fails the pipeline if the executable is not found.
+
+---
+
+## Inventory Configuration
+
+### Dynamic Inventory
+
+The inventory is generated in the Forgejo workflow:
+
+```ini
+[windows_vm]
+<VM_IP> ansible_user=Administrator ansible_password=<password> ansible_connection=winrm ansible_winrm_server_cert_validation=ignore
+```
+
+### Inventory Variables
+
+| Variable | Value | Purpose |
+|----------|-------|---------|
+| `ansible_user` | `Administrator` | Windows admin account |
+| `ansible_password` | From secret | WinRM password |
+| `ansible_connection` | `winrm` | Connection type |
+| `ansible_winrm_server_cert_validation` | `ignore` | Skip cert validation |
+
+---
+
+## Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant Runner as Forgejo Runner
+    participant WinVM as Windows VM
+    
+    Runner->>WinVM: Connect via WinRM
+    WinVM->>Runner: Connection established
+    
+    Runner->>WinVM: Create C:\Test directory
+    WinVM->>Runner: Directory created
+    
+    Runner->>WinVM: Upload installer_signed.exe
+    WinVM->>Runner: File uploaded
+    
+    Runner->>WinVM: Execute installer.exe /S
+    WinVM->>Runner: Installation complete
+    
+    Runner->>WinVM: Check app.exe exists
+    WinVM->>Runner: File found (or not)
+    
+    alt File exists
+        Runner->>Runner: PASS - Continue pipeline
+    else File missing
+        Runner->>Runner: FAIL - Stop pipeline
+    end
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| WinRM connection timeout | Firewall blocking | Disable Private firewall |
+| Credential rejected | Wrong password | Verify WIN_ADMIN_PASS |
+| File not found | Wrong path | Check installation path |
+
+---
+
+## Next Steps
+
+| Goal | Next Document |
+|------|---------------|
+| Run pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |
+| View Terraform | [OpenTofu Resources](../04-terraform/main.tf.md) |
+| Troubleshoot | [Troubleshooting](../07-advanced/troubleshooting.md) |
+
+---
+
+[← Documentation Index](../index.md) | [→ Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) | [← Terraform Variables](../04-terraform/variables.md)