thrillwiki_django_no_react/shared/scripts/unraid/TEMPLATE_VM_SETUP.md

Template VM Setup Instructions

Prerequisites for Template-Based Deployment

Before using the template-based deployment system, you need to:

1. Create the template VM named thrillwiki-template-ubuntu on your Unraid server
2. Configure SSH access with your public key
3. Set up the template with all required software

Step 1: Create Template VM on Unraid

1. Create a new VM on your Unraid server:

   • Name: thrillwiki-template-ubuntu
   • OS: Ubuntu 24.04 LTS
   • Memory: 4GB (you can adjust this later for instances)
   • vCPUs: 2 (you can adjust this later for instances)
   • Disk: 50GB (sufficient for template)

2. Install Ubuntu 24.04 LTS using standard installation

Step 2: Configure Template VM

SSH into your template VM and run the following setup:

Create thrillwiki User

# Create the thrillwiki user with password 'thrillwiki'
sudo useradd -m -s /bin/bash thrillwiki
echo 'thrillwiki:thrillwiki' | sudo chpasswd
sudo usermod -aG sudo thrillwiki

# Switch to thrillwiki user for remaining setup
sudo su - thrillwiki

Set Up SSH Access

IMPORTANT: Add your SSH public key to the template VM:

# Create .ssh directory
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Add your public key (replace with your actual public key)
echo "YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/***REMOVED***
chmod 600 ~/.ssh/***REMOVED***

To get your public key (run this on your Mac):

# Generate key if it doesn't exist
if [ ! -f ~/.ssh/thrillwiki_vm ]; then
    ssh-keygen -t rsa -b 4096 -f ~/.ssh/thrillwiki_vm -N "" -C "thrillwiki-template-vm-access"
fi

# Show your public key to copy
cat ~/.ssh/thrillwiki_vm.pub

Copy this public key and paste it into the template VM's REMOVED file.

Install Required Software

# Update system
sudo apt update && sudo apt upgrade -y

# Install essential packages
sudo apt install -y \
    git curl wget build-essential \
    python3 python3-pip python3-venv python3-dev \
    postgresql postgresql-contrib postgresql-client \
    nginx \
    htop tree vim nano \
    software-properties-common

# Install UV (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.cargo/env

# Add UV to PATH permanently
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

# Configure PostgreSQL
sudo systemctl enable postgresql
sudo systemctl start postgresql

# Create database user and database
sudo -u postgres createuser thrillwiki
sudo -u postgres createdb thrillwiki
sudo -u postgres psql -c "ALTER USER thrillwiki WITH PASSWORD 'thrillwiki';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE thrillwiki TO thrillwiki;"

# Configure Nginx
sudo systemctl enable nginx

# Create ThrillWiki directories
mkdir -p ~/thrillwiki ~/logs ~/backups

# Set up basic environment
echo "export DJANGO_SETTINGS_MODULE=thrillwiki.settings" >> ~/.bashrc
echo "export DATABASE_URL=[DATABASE-URL-REMOVED] >> ~/.bashrc

Pre-install Common Python Packages (Optional)

# Create a base virtual environment with common packages
cd ~
python3 -m venv base_venv
source base_venv/bin/activate
pip install --upgrade pip

# Install common Django packages
pip install \
    django \
    psycopg2-binary \
    gunicorn \
    whitenoise \
    python-decouple \
    pillow \
    requests

deactivate

Clean Up Template

# Clean package cache
sudo apt autoremove -y
sudo apt autoclean

# Clear bash history
history -c
history -w

# Clear any temporary files
sudo find /tmp -type f -delete
sudo find /var/tmp -type f -delete

# Shutdown the template VM
sudo shutdown now

Step 3: Verify Template Setup

After the template VM shuts down, verify it's ready:

# From your Mac, check the template
cd /path/to/your/thrillwiki/project
./scripts/unraid/template-utils.sh check

Step 4: Test Template Deployment

Create a test VM from the template:

# Deploy a test VM
./scripts/unraid/template-utils.sh deploy test-thrillwiki-vm

# Check if it worked
ssh thrillwiki@<VM_IP> "echo 'Template VM working!'"

Template VM Configuration Summary

Your template VM should now have:

• ✅ Username: thrillwiki (password: thrillwiki)
• ✅ SSH Access: Your public key in /home/thrillwiki/.ssh/***REMOVED***
• ✅ Python: Python 3 with UV package manager
• ✅ Database: PostgreSQL with thrillwiki user and database
• ✅ Web Server: Nginx installed and enabled
• ✅ Directories: ~/thrillwiki, ~/logs, ~/backups ready

SSH Configuration on Your Mac

The automation scripts will set this up, but you can also configure manually:

# Add to ~/.ssh/config
cat >> ~/.ssh/config << EOF

# ThrillWiki Template VM
Host thrillwiki-vm
    HostName %h
    User thrillwiki
    IdentityFile ~/.ssh/thrillwiki_vm
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
EOF

Next Steps

Once your template is set up:

1. Run the automation setup:

   ./scripts/unraid/setup-template-automation.sh
   

2. Deploy VMs quickly:

   ./scripts/unraid/template-utils.sh deploy my-vm-name
   

3. Enjoy 5-10x faster deployments (2-5 minutes instead of 20-30 minutes!)

Troubleshooting

SSH Access Issues

# Test SSH access to template (when it's running for updates)
ssh -i ~/.ssh/thrillwiki_vm thrillwiki@TEMPLATE_VM_IP

# If access fails, check:
# 1. Template VM is running
# 2. Public key is in ***REMOVED*** 
# 3. Permissions are correct (700 for .ssh, 600 for ***REMOVED***)

Template VM Updates

# Start template VM on Unraid
# SSH in and update:
sudo apt update && sudo apt upgrade -y
~/.cargo/bin/uv --version  # Check UV is still working

# Clean up and shutdown
sudo apt autoremove -y && sudo apt autoclean
history -c && history -w
sudo shutdown now

Permission Issues

# If you get permission errors, ensure thrillwiki user owns everything
sudo chown -R thrillwiki:thrillwiki /home/thrillwiki/
sudo chmod 700 /home/thrillwiki/.ssh
sudo chmod 600 /home/thrillwiki/.ssh/***REMOVED***

Your template is now ready for lightning-fast VM deployments! ⚡