mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 15:31:08 -05:00
d504d41de2
- Add complete backend/ directory with full Django application - Add frontend/ directory with Vite + TypeScript setup ready for Next.js - Add comprehensive shared/ directory with: - Complete documentation and memory-bank archives - Media files and avatars (letters, park/ride images) - Deployment scripts and automation tools - Shared types and utilities - Add architecture/ directory with migration guides - Configure pnpm workspace for monorepo development - Update .gitignore to exclude .django_tailwind_cli/ build artifacts - Preserve all historical documentation in shared/docs/memory-bank/ - Set up proper structure for full-stack development with shared resources
132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
# 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.
|