LoopAware-Infra/windows-iac-vm-tooling
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
windows-iac-vm-tooling/docs/index.md

259 lines
11 KiB
Markdown
Raw Normal View History

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
# 📖 Documentation Index
<!-- Badges -->
[![Pipeline](https://img.shields.io/badge/Pipeline-Packer%20→%20OpenTofu%20→%20Forgejo-blue)](.forgejo/workflows/release.yml)
[![Windows](https://img.shields.io/badge/Windows-11%20LTSC%202024-0078D6?style=flat&logo=windows)](https://www.microsoft.com/en-us/windows/windows-11-enterprise)
## Welcome
This is the comprehensive documentation index for the **Windows Automation on Proxmox** project. Use this guide to navigate through all available documentation.
---
## 🗂️ Documentation Map
```
┌─────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION TREE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📄 index.md (You are here) │
│ ├── 📁 01-overview/ │
│ │ └── 📄 architecture.md │
│ │ ├── System Components │
│ │ ├── Architecture Diagrams │
│ │ └── Design Decisions │
│ │ │
│ ├── 📁 02-prerequisites/ │
│ │ ├── 📄 isos.md │
│ │ │ ├── ISO Download Sources │
│ │ │ ├── Storage Location │
│ │ │ └── Verification Steps │
│ │ │ │
│ │ └── 📄 secrets.md │
│ │ ├── Forgejo Secrets │
│ │ ├── Proxmox API Tokens │
│ │ └── Certificate Management │
│ │ │
│ ├── 📁 03-packer/ │
│ │ ├── 📄 configuration.md │
│ │ │ ├── Packer HCL Syntax │
│ │ │ ├── Proxmox Builder Settings │
│ │ │ └── Provisioner Configuration │
│ │ │ │
│ │ └── 📄 autounattend.md │
│ │ ├── XML Structure │
│ │ ├── WinRM Configuration │
│ │ └── FirstLogonCommands │
│ │ │
│ ├── 📁 04-terraform/ │
│ │ ├── 📄 main.tf.md │
│ │ │ ├── Provider Configuration │
│ │ │ ├── VM Resource Definition │
│ │ │ └── Clone Strategy │
│ │ │ │
│ │ └── 📄 variables.md │
│ │ ├── Input Variables │
│ │ └── Variable Validation │
│ │ │
│ ├── 📁 05-ansible/ │
│ │ └── 📄 pipeline.md │
│ │ ├── Playbook Structure │
│ │ ├── WinRM Setup │
│ │ └── Verification Tasks │
│ │ │
│ ├── 📁 06-ci-cd/ │
│ │ └── 📄 forgejo-workflows.md │
│ │ ├── Workflow Syntax │
│ │ ├── Container Configuration │
│ │ ├── Step-by-Step Execution │
│ │ └── Environment Variables │
│ │ │
│ └── 📁 07-advanced/ │
│ ├── 📄 evaluation.md │
│ │ ├── 90-Day Timer Management │
│ │ ├── Rearm Procedure │
│ │ └── Monthly Rebuild Strategy │
│ │ │
│ └── 📄 troubleshooting.md │
│ ├── Common Errors │
│ ├── Debug Techniques │
│ └── FAQ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 🎯 Quick Navigation
### I want to...
| Goal | Start Here |
|------|------------|
| **Understand the system** | [Architecture Overview](01-overview/architecture.md) |
| **Set up prerequisites** | [ISO Requirements](02-prerequisites/isos.md) |
| **Build the golden image** | [Packer Configuration](03-packer/configuration.md) |
| **Provision test VMs** | [OpenTofu Resources](04-terraform/main.tf.md) |
| **Run the CI/CD pipeline** | [Forgejo Workflows](06-ci-cd/forgejo-workflows.md) |
| **Troubleshoot issues** | [Troubleshooting Guide](07-advanced/troubleshooting.md) |
---
## 📊 Architecture Overview
```mermaid
graph TD
subgraph CI["Forgejo CI/CD"]
direction LR
Git[Git Push] --> |Triggers| WF[Workflow]
WF --> |Cross-Compile| MC[MinGW]
WF --> |Package| NS[NSIS]
WF --> |Sign| CS[Code Sign]
end
subgraph Infra["Infrastructure"]
CS --> |Provision| TF[OpenTofu]
TF --> |Clone| VM[Windows VM]
end
subgraph Test["Testing"]
VM --> |Deploy| Inst[Installer]
Inst --> |Verify| Ans[Ansible]
Ans --> |Result| Pass{✅ Pass}
Ans --> |Result| Fail{❌ Fail}
end
style CI fill:#e1f5fe
style Infra fill:#e8f5e9
style Test fill:#fff3e0
```
---
## 📚 Section Descriptions
### 01. Overview
- **[architecture.md](01-overview/architecture.md)** - Complete system design including:
- Component overview
- Data flow diagrams
- Design decisions and rationale
- Technology stack explanation
### 02. Prerequisites
- **[isos.md](02-prerequisites/isos.md)** - ISO image requirements:
- Download links for Windows ISOs
- VirtIO driver sources
- Proxmox storage configuration
- File verification steps
- **[secrets.md](02-prerequisites/secrets.md)** - Credential management:
- Forgejo secret configuration
- Proxmox API token creation
- Code signing certificate handling
- Environment variable mapping
### 03. Packer
- **[configuration.md](03-packer/configuration.md)** - Packer template guide:
- HCL syntax reference
- Proxmox builder settings
- Hardware configuration
- Provisioner scripts
- **[autounattend.md](03-packer/autounattend.md)** - Windows无人值守安装:
- XML structure reference
- WinRM enabling
- Firewall configuration
- FirstLogonCommands详解
### 04. Terraform/OpenTofu
- **[main.tf.md](04-terraform/main.tf.md)** - Infrastructure as code:
- Provider configuration
- VM cloning strategy
- Network settings
- IP address assignment
- **[variables.md](04-terraform/variables.md)** - Variables reference:
- Input variable definitions
- Default values
- Variable validation
- Sensitive value handling
### 05. Ansible
- **[pipeline.md](05-ansible/pipeline.md)** - Automation playbook:
- WinRM connection setup
- File transfer tasks
- Silent installation
- Verification assertions
- Error handling
### 06. CI/CD
- **[forgejo-workflows.md](06-ci-cd/forgejo-workflows.md)** - Pipeline configuration:
- Workflow syntax
- Container images
- Step-by-step execution
- Artifact publishing
- Cleanup procedures
### 07. Advanced
- **[evaluation.md](07-advanced/evaluation.md)** - Evaluation management:
- 90-day expiration explained
- Rearm procedure
- Automated rebuild strategy
- Security considerations
- **[troubleshooting.md](07-advanced/troubleshooting.md)** - Problem resolution:
- Common error messages
- Debug commands
- Log file locations
- FAQ section
---
## 🔗 Cross-References
This documentation is fully interlinked. Key cross-references include:
| From | To | Context |
|------|-----|---------|
| README | docs/index.md | Documentation entry |
| architecture.md | isos.md | Prerequisites section |
| configuration.md | autounattend.md | Related Packer topics |
| main.tf.md | variables.md | Terraform variables |
| forgejo-workflows.md | pipeline.md | Ansible integration |
| pipeline.md | main.tf.md | Infrastructure reference |
| troubleshooting.md | All sections | Problem resolution |
---
## 🛠️ Tool Reference
| Tool | Version | Purpose | Docs Link |
|------|---------|---------|-----------|
| Packer | ≥ 1.1.0 | Image building | [configuration.md](03-packer/configuration.md) |
| OpenTofu | Latest | IaC provisioning | [main.tf.md](04-terraform/main.tf.md) |
| Ansible | Latest | Automation | [pipeline.md](05-ansible/pipeline.md) |
| Forgejo Actions | Latest | CI/CD | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |
| MinGW | Latest | Cross-compilation | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |
| NSIS | Latest | Installer creation | [forgejo-workflows.md](06-ci-cd/forgejo-workflows.md) |
---
## 📖 Reading Guide
1. **First Time Setup:** Read in order: 01 → 02 → 03 → 04 → 05 → 06
2. **Specific Task:** Use the Quick Navigation table above
3. **Deep Dive:** Follow cross-references from any section
4. **Troubleshooting:** Start with [troubleshooting.md](07-advanced/troubleshooting.md)
---
## 🔄 Document Version
| Property | Value |
|----------|-------|
| Version | 1.0.0 |
| Last Updated | February 2026 |
| Target OS | Windows 11 LTSC 2024 |
| Status | Active Development |
---
[← Back to README](../README.md) | [→ Architecture Overview](01-overview/architecture.md)
Reference in a new issue Copy permalink