Quick Start¶

Get your first VM running in 5 minutes with Solti-Platforms.

Prerequisites¶

Proxmox VE 8.x host
SSH access with sudo privileges
Ansible installed locally
Collection installed: ansible-galaxy collection install jackaltx.solti_platforms

Step 1: Clone Repository¶

git clone https://github.com/jackaltx/solti-platforms.git
cd solti-platforms

Step 2: Configure Inventory¶

Create inventory.yml:

---
all:
  hosts:
    magic:
      ansible_host: proxmox.example.com
      ansible_user: lavender
      proxmox_storage: local-lvm
      proxmox_bridge: vmbr0

Update ansible_host with your Proxmox hostname.

Step 3: Build Template¶

Build a Rocky Linux 9 template:

./manage-platform.sh -h magic -t rocky9 proxmox_template build

This will:

Download Rocky 9 cloud image (~800MB)
Create VM with UEFI/Secure Boot
Import disk to Proxmox storage
Configure cloud-init
Convert to template

Expected output:

Template rocky9-template created successfully!
VMID: 9000
Name: rocky9-template
Status: Template ready for cloning

Time: ~3-5 minutes (depending on download speed)

Step 4: Create VM¶

Create a VM from the template:

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9

This will:

Find rocky9-template automatically
Generate VM name: rocky9-260125 (today's date)
Assign next available VMID (e.g., 500)
Clone template as linked clone
Configure cloud-init with your SSH key

Expected output:

VM created successfully!
Name: rocky9-260125
VMID: 500
Template: rocky9-template (9000)
Disk: 32G (linked clone)

Step 5: Start VM¶

ssh magic.example.com "sudo qm start 500"

Step 6: Connect¶

Wait ~30 seconds for cloud-init to complete, then:

# Get IP address
ssh magic.example.com "sudo qm guest cmd 500 network-get-interfaces"

# SSH into VM (using cloud-init configured key)
ssh lavender@<vm-ip-address>

You should be logged in without a password (SSH key authentication via cloud-init).

What Just Happened?¶

Template Creation¶

The proxmox_template role:

Downloaded official Rocky Linux 9 cloud image
Verified checksum
Created VM with recommended settings:
UEFI boot with Secure Boot keys
32GB disk (resizable)
8GB RAM, 4 CPU cores
virtio-scsi-pci disk controller
virtio network adapter
Configured cloud-init drive
Converted to template at VMID 9000

VM Creation¶

The proxmox_vm role:

Looked up template by distribution name (rocky9)
Generated unique VM name with date stamp
Found next available VMID in range 500-8999
Created linked clone (fast, space-efficient)
Configured cloud-init:
User: lavender (your SSH user)
SSH key: From ~/.ssh/id_ed25519.pub
Network: DHCP

Common Customizations¶

Explicit VM Name¶

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9 \
  -e vm_name="my-server"

Custom Resources¶

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9 \
  -e vm_memory=16384 \
  -e vm_cores=8 \
  -e vm_disk_min_size="100G"

Full Clone (Instead of Linked)¶

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9 \
  -e vm_linked_clone=false

Build All Templates¶

Build Rocky 9, Rocky 10, Debian 12 templates:

./manage-platform.sh -h magic proxmox_template build --all-distros

Cleanup¶

Remove a VM:

# Stop VM
ssh magic.example.com "sudo qm stop 500"

# Destroy VM
ssh magic.example.com "sudo qm destroy 500"

Remove a template:

./manage-platform.sh -h magic -t rocky9 proxmox_template destroy

Troubleshooting¶

Template build fails with "Permission denied"¶

Ensure sudo access:

ssh magic.example.com "sudo qm list"

VM creation fails with "Template not found"¶

Verify template exists:

ssh magic.example.com "sudo qm list | grep template"

Expected output:

9000 rocky9-template    0 template  0.00 0

Cannot SSH into VM¶

Check VM IP address:

ssh magic.example.com "sudo qm guest cmd 500 network-get-interfaces"

Verify cloud-init completed:

ssh magic.example.com "sudo qm cloudinit dump 500 user"

Next Steps¶

Read Architecture Overview to understand the roles
Explore Proxmox Template Role for advanced template options
Learn about Proxmox VM Role smart features
Review Management Tools for script usage

Example Workflow¶

Here's a complete workflow for creating a test environment:

# 1. Build templates (one-time setup)
./manage-platform.sh -h magic proxmox_template build --all-distros

# 2. Create test VMs
./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=rocky9 \
  -e vm_name="test-web"

./manage-platform.sh -h magic proxmox_vm create \
  -e vm_template_distribution=debian12 \
  -e vm_name="test-db"

# 3. Start VMs
ssh magic.example.com "sudo qm start 500"
ssh magic.example.com "sudo qm start 501"

# 4. Deploy applications (using other Ansible playbooks)
ansible-playbook -i test-inventory.yml deploy-web.yml
ansible-playbook -i test-inventory.yml deploy-db.yml

# 5. Run tests
ansible-playbook -i test-inventory.yml test-suite.yml

# 6. Cleanup
ssh magic.example.com "sudo qm stop 500 && sudo qm destroy 500"
ssh magic.example.com "sudo qm stop 501 && sudo qm destroy 501"

This workflow demonstrates:

Template reuse across multiple VMs
Automated VM provisioning
Integration with deployment playbooks
Ephemeral test environments