# Proxmox Ollama Template VM 102 Runbook

Created from Godzilla/Hermes runbook. Public-safe version replaces private site values with placeholders.

## Purpose

Document the process for preparing VM 102 as a reusable Proxmox Ubuntu/Ollama template and provide a clean replication checklist.

## Public-Safe Placeholder Rules

- Replace `PROXMOX_HOST_OR_IP` with the real Proxmox host only when running commands internally.
- Replace `VMID`, `NEWID`, and `STALE_STORAGE_ID` before execution.
- Do not publish passwords, private keys, API keys, or private connection strings.
- Use `PASTE_PUBLIC_KEY_HERE` instead of embedding site-specific SSH public keys in public documentation.

## Critical Safety Correction

Do **not** delete SSH host keys while still actively configuring the VM over SSH.

Avoid this during active setup:

```bash
sudo rm -f /etc/ssh/ssh_host_*
```

Use Cloud-Init to handle clone identity and SSH key regeneration instead.

## 1. Overview

Document VM 102 as a reusable Ubuntu/Ollama template with Cloud-Init, QEMU Guest Agent, safe SSH handling, and repeatable clone testing.

Status/type: **Intel/AMD host readiness, storage cleaned, VM install complete, no SSH host key deletion during active setup.**


## 2. Safety correction

The prior failure pattern was deleting SSH host keys while still configuring over SSH. For template identity, use Cloud-Init and clone-time regeneration instead.

Status/type: **High risk**

### Avoid during active SSH setup

```bash
sudo rm -f /etc/ssh/ssh_host_*
```

### Safer cleanup pattern

```bash
sudo cloud-init clean --logs
sudo truncate -s 0 /etc/machine-id
sudo rm -f /var/lib/dbus/machine-id
sudo ln -sf /etc/machine-id /var/lib/dbus/machine-id
```


## 3. Storage verification

Verify active storage, remove stale storage entries only after confirming they point to missing or incorrect mounts.

Status/type: **Verified before conversion**

### Inspect storage and mounted disks

```bash
lsblk -o NAME,SIZE,MODEL,SERIAL,FSTYPE,LABEL,MOUNTPOINT
df -h
pvesm status
cat /etc/pve/storage.cfg
```

### Remove stale storage entry if verified stale

```bash
pvesm remove STALE_STORAGE_ID
```


## 4. Access method

Use a dedicated key from the Hermes/Godzilla server to administer Proxmox. Public docs use placeholders and do not publish private keys or site IPs.

Status/type: **Credential-safe**

### Generate a dedicated key locally

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -f ~/.ssh/godzilla_proxmox_ed25519 -N '' -C 'godzilla-hermes-proxmox-access'
cat ~/.ssh/godzilla_proxmox_ed25519.pub
```

### Add public key on Proxmox

```bash
mkdir -p /root/.ssh
chmod 700 /root/.ssh
cat >> /root/.ssh/authorized_keys <<'EOF'
PASTE_PUBLIC_KEY_HERE
EOF
chmod 600 /root/.ssh/authorized_keys
```

### Connect to Proxmox with placeholder host

```bash
ssh -i ~/.ssh/godzilla_proxmox_ed25519 -o BatchMode=yes -o StrictHostKeyChecking=accept-new root@PROXMOX_HOST_OR_IP
```


## 5. Inspect VM

Before changing anything, confirm Proxmox version, VM configuration, VM status, storage status, ISO availability, and guest-agent status.

Status/type: **Proxmox host**

### Verify host and VM configuration

```bash
hostname
pveversion
qm config 102
```

### Verify VM state, storage, and ISO files

```bash
qm status 102
qm list
pvesm status
ls -lah /mnt/pve/backup-iso-sdb/template/iso
```

### Check QEMU Guest Agent from Proxmox

```bash
qm agent 102 ping
qm agent 102 network-get-interfaces
qm status 102 --verbose
```


## 6. Template prep

Set CPU type to host for better Ollama CPU feature exposure. Add a visible description documenting Cloud-Init and SSH host key guardrails.

Status/type: **Action**

### Set CPU type to host

```bash
qm set 102 --cpu host
```

### Add operational description

```bash
qm set 102 --description "Ollama Ubuntu template base. QEMU guest agent enabled. CPU host. Use cloud-init; do not manually delete SSH host keys during prep."
```


## 7. Cloud-Init

Cloud-Init should provide clone identity and network/user initialization instead of manual SSH host key deletion.

Status/type: **Action**

### Add Cloud-Init drive and defaults

```bash
qm set 102 --ide0 local-lvm:cloudinit
qm set 102 --ciuser luis --ipconfig0 ip=dhcp
```

### Verify Cloud-Init config

```bash
qm config 102 | grep -E "ide0|ciuser|ipconfig0"
```


## 8. Guest packages

Inside the Ubuntu guest, install and enable qemu-guest-agent, cloud-init, and OpenSSH before converting to a template.

Status/type: **Inside VM**

### Install required guest packages

```bash
sudo apt update
sudo apt install -y cloud-init qemu-guest-agent openssh-server
sudo systemctl enable --now qemu-guest-agent
sudo systemctl enable --now ssh
```

### Verify inside guest

```bash
systemctl is-active qemu-guest-agent
systemctl is-active ssh
```

### Verify from Proxmox host

```bash
qm agent VMID ping
qm agent VMID network-get-interfaces
```


## 9. Guest cleanup

Run only after package installation and SSH verification are complete. Do not delete SSH host keys manually during active remote setup.

Status/type: **Optional**

### Clean guest identity safely

```bash
sudo cloud-init clean --logs
sudo truncate -s 0 /etc/machine-id
sudo rm -f /var/lib/dbus/machine-id
sudo ln -sf /etc/machine-id /var/lib/dbus/machine-id
sudo rm -f /var/lib/dhcp/*
sudo rm -f /var/lib/systemd/network/*.lease
```


## 10. Shutdown

After Ubuntu install and setup are confirmed complete, shut down the VM from Proxmox before removing ISO and converting.

Status/type: **Action**

### Shutdown from Proxmox

```bash
qm shutdown 102 --timeout 180 || qm stop 102
qm status 102
```


## 11. Finalize template

Remove installer ISO so clones do not boot into the installer. Boot from installed disk only, refresh Cloud-Init, then convert to template.

Status/type: **Action**

### Finalize VM 102 as template

```bash
qm set 102 --delete ide2
qm set 102 --boot order=scsi0
qm cloudinit update 102 || true
qm template 102
```

### Verify final template config

```bash
qm config 102
qm list
```


## 12. Replication checklist

Use these settings when building the next reusable Ollama template VM.

Status/type: **Reference**

### Recommended VM settings

```bash
Name: ollama-template
VMID: choose unused ID, example 9000 or 102
OS: Ubuntu Server ISO
Machine: q35
BIOS: OVMF / UEFI
SCSI Controller: VirtIO SCSI single
Disk: local-lvm, 32G minimum
CPU Type: host
Cores: 8 preferred
RAM: 16GB minimum; 32GB+ preferred for production
Network: VirtIO, bridge vmbr0
QEMU Guest Agent: Enabled
```


## 13. Clone test

A template is not operationally proven until a clone boots, receives networking, and responds to QEMU guest-agent calls.

Status/type: **Validation**

### Create and start a test clone

```bash
qm clone 102 103 --name ollama-test --full true --storage local-lvm
qm start 103
```

### Verify clone guest agent and network

```bash
qm agent 103 ping
qm agent 103 network-get-interfaces
```

### Repair guest agent inside clone if needed

```bash
sudo apt update
sudo apt install -y qemu-guest-agent cloud-init openssh-server
sudo systemctl enable --now qemu-guest-agent
sudo systemctl enable --now ssh
```


## 14. Production notes

The base template disk is intentionally small. Production clones should be expanded or given a dedicated model disk, and GPU passthrough/NVIDIA drivers should be applied to the clone, not the base template.

Status/type: **Operational notes**

### Inspect and resize clone disk as needed

```bash
qm config OLLAMA_CLONE_VMID
qm resize OLLAMA_CLONE_VMID scsi0 +200G
```

### GPU driver rule

```bash
Install NVIDIA drivers inside the Ollama VM clone, not on the Proxmox host, when using PCI passthrough.
```


## 15. Quick command reference

Short command set for inspection, Cloud-Init, conversion, clone testing, and guest-agent validation.

Status/type: **Reference**

### Inspect VM

```bash
qm config VMID
qm status VMID
qm list
```

### Set CPU and Cloud-Init

```bash
qm set VMID --cpu host
qm set VMID --ide0 local-lvm:cloudinit
qm set VMID --ciuser luis --ipconfig0 ip=dhcp
qm cloudinit update VMID
```

### Remove ISO and convert

```bash
qm set VMID --delete ide2
qm set VMID --boot order=scsi0
qm shutdown VMID --timeout 180 || qm stop VMID
qm template VMID
```

### Clone and test

```bash
qm clone VMID NEWID --name ollama-test --full true --storage local-lvm
qm start NEWID
qm agent NEWID ping
qm agent NEWID network-get-interfaces
```

## Final Template Verification Snapshot

Expected final VM template characteristics:

```text
agent: 1
bios: ovmf
boot: order=scsi0
ciuser: luis
cores: 8
cpu: host
ide0: local-lvm:vm-102-cloudinit,media=cdrom
ipconfig0: ip=dhcp
machine: q35
memory: 16384
name: ollama-template
ostype: l26
scsi0: local-lvm:base-102-disk-1,iothread=1,size=32G
scsihw: virtio-scsi-single
sockets: 1
template: 1
```

## Operational Notes for Ollama Production Clones

- The base template disk is 32GB. Ollama models may exceed this quickly.
- Expand the clone disk or add a second dedicated models disk for production.
- Apply GPU passthrough only to the actual Ollama VM clone when needed.
- Install NVIDIA drivers inside the Ollama VM clone, not on the Proxmox host, when using PCI passthrough.