thrillwiki_django_no_react/shared/scripts/unraid/README.md

ThrillWiki Unraid VM Automation

This directory contains scripts and configuration files for automating the creation and deployment of ThrillWiki VMs on Unraid servers using Ubuntu autoinstall.

Files

• vm-manager.py - Main VM management script with direct kernel boot support
• thrillwiki-vm-template.xml - VM XML configuration template for libvirt
• cloud-init-template.yaml - Ubuntu autoinstall configuration template
• validate-autoinstall.py - Validation script for autoinstall configuration

Key Features

Direct Kernel Boot Approach

The system now uses direct kernel boot instead of GRUB-based boot for maximum reliability:

1. Kernel Extraction: Automatically extracts Ubuntu kernel and initrd files from the ISO
2. Direct Boot: VM boots directly using extracted kernel with explicit autoinstall parameters
3. Reliable Autoinstall: Kernel cmdline explicitly specifies autoinstall ds=nocloud-net;s=cdrom:/

Schema-Compliant Configuration

The autoinstall configuration has been validated against Ubuntu's official schema:

• ✅ Proper network configuration structure
• ✅ Correct storage layout specification
• ✅ Valid shutdown configuration
• ✅ Schema-compliant field types and values

Usage

Environment Variables

Set these environment variables before running:

export UNRAID_HOST="your-unraid-server"
export UNRAID_USER="root"
export UNRAID_PASSWORD="your-password"
export SSH_PUBLIC_KEY="your-ssh-public-key"
export REPO_URL="https://github.com/your-username/thrillwiki.git"
export VM_IP="192.168.20.20"  # or "dhcp" for DHCP
export VM_GATEWAY="192.168.20.1"

Basic Operations

# Create and configure VM
./vm-manager.py create

# Start the VM
./vm-manager.py start

# Check VM status
./vm-manager.py status

# Get VM IP address
./vm-manager.py ip

# Complete setup (create + start + get IP)
./vm-manager.py setup

# Stop the VM
./vm-manager.py stop

# Delete VM and all files
./vm-manager.py delete

Configuration Validation

# Validate autoinstall configuration
./validate-autoinstall.py

How It Works

VM Creation Process

1. Extract Kernel: Mount Ubuntu ISO and extract vmlinuz and initrd from /casper/
2. Create Cloud-Init ISO: Generate configuration ISO with autoinstall settings
3. Generate VM XML: Create libvirt VM configuration with direct kernel boot
4. Define VM: Register VM as persistent domain in libvirt

Boot Process

1. Direct Kernel Boot: VM starts using extracted kernel and initrd directly
2. Autoinstall Trigger: Kernel cmdline forces Ubuntu installer into autoinstall mode
3. Cloud-Init Data: NoCloud datasource provides configuration from CD-ROM
4. Automated Setup: Ubuntu installs and configures ThrillWiki automatically

Network Configuration

The system supports both static IP and DHCP configurations:

• Static IP: Set VM_IP to desired IP address (e.g., "192.168.20.20")
• DHCP: Set VM_IP to "dhcp" for automatic IP assignment

Troubleshooting

VM Console Access

Connect to VM console to monitor autoinstall progress:

ssh root@unraid-server
virsh console thrillwiki-vm

Check VM Logs

View autoinstall logs inside the VM:

# After VM is accessible
ssh ubuntu@vm-ip
sudo journalctl -u cloud-init
tail -f /var/log/cloud-init.log

Validation Errors

If autoinstall validation fails, check:

1. YAML syntax in cloud-init-template.yaml
2. Required fields according to Ubuntu schema
3. Proper data types for configuration values

Architecture Benefits

1. Reliable Boot: Direct kernel boot eliminates GRUB-related issues
2. Schema Compliance: Configuration validated against official Ubuntu schema
3. Predictable Behavior: Explicit kernel parameters ensure consistent autoinstall
4. Clean Separation: VM configuration, cloud-init, and kernel files are properly organized
5. Easy Maintenance: Modular design allows independent updates of components

This implementation provides a robust, schema-compliant solution for automated ThrillWiki deployment on Unraid VMs.