# 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:

```bash
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

```bash
# 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

```bash
# 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:
```bash
ssh root@unraid-server
virsh console thrillwiki-vm
```

### Check VM Logs
View autoinstall logs inside the VM:
```bash
# 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.