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
258
docs/index.md
Normal file
258
docs/index.md
Normal file
|
|
@ -0,0 +1,258 @@
|
|||
# 📖 Documentation Index
|
||||
|
||||
<!-- Badges -->
|
||||
[](.forgejo/workflows/release.yml)
|
||||
[](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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue