puqcloud/pve-os-builder repository overview

⁠Proxmox OS Template Builder (puqcloud/pve-os-builder)

A self-contained Docker appliance designed to automate the generation of production-ready Proxmox VE Virtual Machine Templates (.vma.zst), specifically engineered for the PUQ Proxmox KVM WHMCS Module⁠ and automated hosting infrastructure.

Features an integrated NFS-Ganesha Storage Server (allowing direct Proxmox VE storage mounting), a modern Console-Style Dark Web UI, an autonomous OS customization engine (virt-customize, vma, zstd, cloud-init), and a resilient sequential image downloader with auto-retry logic.

⁠Key Highlights

• 🚀 Zero Manual Steps in Proxmox: Mount this container directly as an NFS backup storage in Proxmox VE. Newly generated templates appear immediately in the Proxmox GUI backup browser for instant one-click VM restoration.
• 🛡️ PUQ WHMCS Module Compliant:
  • Pre-configures root SSH password authentication (PermitRootLogin yes, PasswordAuthentication yes).
  • Automatically installs cloud-init, cloud-initramfs-growroot, and cloud-utils-growpart for dynamic disk expansion upon provisioning.
  • Pre-configures qemu-guest-agent for full lifecycle status reporting in WHMCS.
  • Cleans /etc/machine-id, removes stale SSH host keys, and purges default cloud user accounts (ubuntu, debian, centos, rocky, almalinux).
• ⚡ Hardware-Agnostic & VM-Safe:
  • Supports /dev/kvm hardware virtualization acceleration when available.
  • Automatically falls back to QEMU TCG software emulation mode inside virtual machines without crashing when /dev/kvm is absent.
• 🔄 Sequential Resilient Downloader:
  • Single-worker FIFO queue prevents network saturation and socket exhaustion.
  • Enforced IPv4-first resolution avoids dual-stack IPv6 socket timeouts in container environments.
  • Automatic 10-second retry loop for temporary network glitches, with clean HTTP 3xx redirect socket disposal.
• 🌐 Multi-Region & Localization Groups:
  • Build regional template variations (e.g. EU, US, Canada, China Mainland, India, Global UTC) with tailored timezones, system locales, regional APT/DNF package mirrors, and custom post-provisioning bash scripts.
• 📁 Bi-directional JSON Catalog Sync:
  • Live configuration catalogs (images_catalog.json, localization_groups.json) synchronize automatically between the embedded SQLite database and /data/configs on disk.

⁠Quick Start (Docker Compose)

The recommended deployment uses network_mode: host to allow Proxmox VE nodes to seamlessly mount the built-in NFS storage on port 2049 without complex port mapping.

⁠1. Create docker-compose.yml

services:
  pve-os-builder:
    container_name: pve-os-builder
    image: puqcloud/pve-os-builder:latest
    restart: unless-stopped
    network_mode: host
    privileged: true
    environment:
      - TZ=America/Winnipeg
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=admin-secure-password
      - JWT_SECRET=change-this-to-a-very-long-random-secret-key
      - PORT=8080
      - LIBGUESTFS_BACKEND=direct
    volumes:
      - ./data/db:/data/db
      - ./data/downloads:/data/downloads
      - ./data/configs:/data/configs
      - ./data/repository:/data/repository
      - ./data/scratch:/data/scratch
      # Optional: KVM acceleration if running on bare-metal or nested virtualization
      # - /dev/kvm:/dev/kvm

⁠2. Start the Service

docker compose up -d

Open your browser at http://<SERVER_IP>:8080 and log in with your configured ADMIN_USER and ADMIN_PASSWORD.

⁠Alternative: Docker CLI (docker run)

docker run -d \
  --name pve-os-builder \
  --restart unless-stopped \
  --network host \
  --privileged \
  -e TZ=America/Winnipeg \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=admin-secure-password \
  -e JWT_SECRET=change-this-to-a-very-long-random-secret-key \
  -e PORT=8080 \
  -e LIBGUESTFS_BACKEND=direct \
  -v $(pwd)/data/db:/data/db \
  -v $(pwd)/data/downloads:/data/downloads \
  -v $(pwd)/data/configs:/data/configs \
  -v $(pwd)/data/repository:/data/repository \
  -v $(pwd)/data/scratch:/data/scratch \
  puqcloud/pve-os-builder:latest

⁠Direct Proxmox VE Storage Integration

The builder exports /data/repository over NFS at the mount path /export using an embedded read-only NFS-Ganesha service.

⁠Option A: One-Command Mount via Proxmox CLI

Run this command on your Proxmox VE host:

pvesm add nfs os-builder-storage \
  --server <BUILDER_IP> \
  --export /export \
  --content backup \
  --options ro

⁠Option B: Mount via Proxmox Web GUI

1. Log into your Proxmox VE Web GUI (https://<PROXMOX_IP>:8006).
2. Navigate to Datacenter -> Storage -> Add -> NFS.
3. Configure the storage parameters:
   • ID: os-builder-storage
   • Server: <BUILDER_IP>
   • Export: /export
   • Content: VZDump backup file
   • Options: ro
4. Click Add.

⁠Restoring Templates in Proxmox VE

1. In Proxmox VE, click on any node and expand os-builder-storage.
2. Click Backups to see all generated OS templates (e.g. vzdump-qemu-9000-debian-13-eu.vma.zst).
3. Select a template and click Restore.
4. Select your target storage (e.g. local-lvm or ceph), assign a VM ID, and click Restore.
5. Once restored, right-click the VM and choose Convert to Template.

⁠Environment Variables

⁠Persistent Storage Volumes

All container state is persisted in /data:

data/
├── db/
│   └── pve-builder.db            # Embedded SQLite database (WAL mode)
├── downloads/                    # Cached upstream cloud images (Debian, Ubuntu, AlmaLinux, etc.)
├── configs/
│   ├── images_catalog.json       # Editable OS base image catalog
│   └── localization_groups.json  # Regional localization definitions
├── repository/
│   └── dump/                     # Standard Proxmox backup storage directory
│       ├── vzdump-qemu-9000.vma.zst
│       └── vzdump-qemu-9000.notes
└── scratch/                      # Transient scratch directory for active build jobs

⁠Supported Operating Systems

Pre-configured in the default catalog with direct upstream download mirrors:

⁠Built-in Security Controls

• NFS Client IP Restrictions: Restrict NFS export access directly from the Web Console (Proxmox Storage page) to allow only specific Proxmox VE node IPs (e.g. 192.168.1.50, 192.168.1.51) or private subnets (e.g. 10.0.0.0/24).
• Read-Only NFS Exports: The NFS server exports the repository with ro (read-only) options, preventing accidental deletion or tampering from client nodes.
• Root Password Protection: Root passwords and provider SSH keys configured in Profiles are securely injected into templates during build time.
• JWT Session Protection: All REST API endpoints require valid signed JWT authentication tokens.

⁠Public Repository Browser

In addition to NFS storage, the builder serves a public HTTP/HTML directory browser at / (or /repository) allowing remote Proxmox nodes or automated provisioning scripts to download templates directly over HTTP:

wget -O /var/lib/vz/dump/vzdump-qemu-9000-debian-13-eu.vma.zst \
  http://<BUILDER_IP>:8080/repository/vzdump-qemu-9000-debian-13-eu.vma.zst

⁠Documentation & Commercial Support

• WHMCS Module Documentation: PUQ Proxmox KVM WHMCS Module⁠
• Official Website: PUQcloud⁠
• Technical Support: [email protected]⁠

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.
Free and open-source software for personal, commercial, hosting provider, and datacenter use.