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

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

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

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

```bash
# 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**:
   ```bash
   ./scripts/unraid/setup-template-automation.sh
   ```

2. **Deploy VMs quickly**:
   ```bash
   ./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
```bash
# 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
```bash
# 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
```bash
# 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! ⚡
