e4f03427b7
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
258 lines
11 KiB
Markdown
258 lines
11 KiB
Markdown
# 📖 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)
|