Add comprehensive documentation for all project sections

Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.
2026-02-25 05:57:26 +00:00 · 2025-12-01 11:40:38 +01:00
parent dab67f7980
commit 3998b80194
34 changed files with 5221 additions and 42 deletions
--- a/docs/vm/README.md
+++ b/docs/vm/README.md
@@ -0,0 +1,129 @@
+# VM Scripts Documentation (/vm)
+
+This directory contains comprehensive documentation for virtual machine creation scripts in the `/vm` directory.
+
+## Overview
+
+VM scripts (`vm/*.sh`) create full virtual machines (not containers) in Proxmox VE with complete operating systems and cloud-init provisioning.
+
+## Documentation Structure
+
+VM documentation parallels container documentation but focuses on VM-specific features.
+
+## Key Resources
+
+- **[misc/cloud-init.func/](../misc/cloud-init.func/)** - Cloud-init provisioning documentation
+- **[CONTRIBUTION_GUIDE.md](../CONTRIBUTION_GUIDE.md)** - Contribution workflow
+- **[EXIT_CODES.md](../EXIT_CODES.md)** - Exit code reference
+
+## VM Creation Flow
+
+```
+vm/OsName-vm.sh (host-side)
+    │
+    ├─ Calls: build.func (orchestrator)
+    │
+    ├─ Variables: var_cpu, var_ram, var_disk, var_os
+    │
+    ├─ Uses: cloud-init.func (provisioning)
+    │
+    └─ Creates: KVM/QEMU VM
+                │
+                └─ Boots with: Cloud-init config
+                               │
+                               ├─ System phase
+                               ├─ Config phase
+                               └─ Final phase
+```
+
+## Available VM Scripts
+
+See `/vm` directory for all VM creation scripts. Examples:
+
+- `ubuntu2404-vm.sh` - Ubuntu 24.04 VM
+- `ubuntu2204-vm.sh` - Ubuntu 22.04 VM
+- `debian-vm.sh` - Debian VM
+- `debian-13-vm.sh` - Debian 13 VM
+- `opnsense-vm.sh` - OPNsense firewall
+- `haos-vm.sh` - Home Assistant OS
+- `unifi-os-vm.sh` - Unifi Dream Machine
+- `k3s-vm.sh` - Kubernetes lightweight
+- And 10+ more...
+
+## VM vs Container
+
+| Feature | VM | Container |
+|---------|:---:|:---:|
+| Isolation | Full | Lightweight |
+| Boot Time | Slower | Instant |
+| Resource Use | Higher | Lower |
+| Use Case | Full OS | Single app |
+| Init System | systemd/etc | cloud-init |
+| Storage | Disk image | Filesystem |
+
+## Quick Start
+
+To understand VM creation:
+
+1. Read: [misc/cloud-init.func/README.md](../misc/cloud-init.func/README.md)
+2. Study: A similar existing script in `/vm`
+3. Understand cloud-init configuration
+4. Test locally
+5. Submit PR
+
+## Contributing a New VM
+
+1. Create `vm/osname-vm.sh`
+2. Use cloud-init for provisioning
+3. Follow VM script template
+4. Test VM creation and boot
+5. Submit PR
+
+## Cloud-Init Provisioning
+
+VMs are provisioned using cloud-init:
+
+```yaml
+#cloud-config
+hostname: myvm
+timezone: UTC
+
+packages:
+  - curl
+  - wget
+
+users:
+  - name: ubuntu
+    ssh_authorized_keys:
+      - ssh-rsa AAAAB3...
+
+bootcmd:
+  - echo "VM starting..."
+
+runcmd:
+  - apt-get update
+  - apt-get upgrade -y
+```
+
+## Common VM Operations
+
+- **Create VM with cloud-init** → [misc/cloud-init.func/](../misc/cloud-init.func/)
+- **Configure networking** → Cloud-init YAML documentation
+- **Setup SSH keys** → [misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md](../misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md)
+- **Debug VM creation** → [EXIT_CODES.md](../EXIT_CODES.md)
+
+## VM Templates
+
+Common VM templates available:
+
+- **Ubuntu LTS** - Latest stable Ubuntu
+- **Debian Stable** - Latest stable Debian
+- **OPNsense** - Network security platform
+- **Home Assistant** - Home automation
+- **Kubernetes** - K3s lightweight cluster
+- **Proxmox Backup** - Backup server
+
+---
+
+**Last Updated**: December 2025
+**Maintainers**: community-scripts team