CanbiZ 3998b80194 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.

2025-12-01 11:40:38 +01:00

3.3 KiB

Raw Blame History

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/ - Cloud-init provisioning documentation
CONTRIBUTION_GUIDE.md - Contribution workflow
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:

Read: misc/cloud-init.func/README.md
Study: A similar existing script in /vm
Understand cloud-init configuration
Test locally
Submit PR

Contributing a New VM

Create vm/osname-vm.sh
Use cloud-init for provisioning
Follow VM script template
Test VM creation and boot
Submit PR

Cloud-Init Provisioning

VMs are provisioned using cloud-init:

#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/
Configure networking → Cloud-init YAML documentation
Setup SSH keys → misc/cloud-init.func/CLOUD_INIT_FUNC_USAGE_EXAMPLES.md
Debug VM creation → 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

3.3 KiB Raw Blame History