Systems, templates, ISOs and apps

Since 0.10 the VPS systems have their own page: Systems. It has four tabs: the systems you offer, the Incus catalogue, the ISO library and the apps that install on first boot.

Systems you offer

The table shows each system with its icon, source, requirements, plans, status and number of VPSs. The Offered box makes it appear in (or disappear from) the clients' choice. Existing VPSs do not change.

With the pencil you edit:

• name and description, which clients see;
• family, which sets the icon;
• minimum RAM and disk: smaller plans cannot choose it;
• the plans that can use it (none ticked means all);
• the login user (root, or Administrator for Windows).

When creating or reinstalling, systems that do not fit the plan stay visible but disabled, with the reason.

The Incus catalogue

The Incus catalogue tab lists the VM images with cloud-init from images.linuxcontainers.org:

• AlmaLinux, Rocky Linux and CentOS Stream;
• Debian and Ubuntu;
• Fedora, openSUSE, Arch Linux, Alpine, openEuler.

Add puts it among the systems, already offered. The first VPS on a node downloads the image, the next ones start right away. “Tested with KoaVM” means static network, password and SSH have been tested on that family.

Your own templates

Your templates live on the nodes. They have the same name on every node (koavm-tpl-N) and the panel copies them where needed. The copy happens with the first VPS on a node that lacks them, or right away with To nodes. First the target node downloads the template from the other node with a one-time secret. If that fails, the data goes through the panel.

A new template is not offered: you turn it on when it is ready.

From a VPS

Template from a VPS: pick a VPS, give it a name and the panel does the rest:

1. it takes a snapshot of the VPS, which stays on and does not change;
2. it creates the template from the snapshot, compressed with zstd;
3. it deletes the snapshot.

VPSs created from the template start with cloud-init like the others: new name, network, password and SSH keys. The template has the source VPS disk, so new VPSs need at least that disk. The panel sets it as the minimum disk.

From a file

From a file: the URL of a qcow2 or raw disk, also compressed with xz, gzip, bzip2 or zstd. Distribution cloud images work, for example. The panel:

1. downloads the disk;
2. converts it to qcow2 if it is raw (no qemu-img needed);
3. uploads it to the node as a template.

The system must have cloud-init. The panel passes name, network and password on a NoCloud disk (“cidata”) and installs the Incus agent from its disk. The base system (e.g. ubuntu/24.04) is used to offer compatible apps. VMDK, VHDX and ZIP are not accepted.

Windows from an ISO

Windows from ISO builds a Windows Server 2016, 2019, 2022 or 2025 template with nothing for you to do. The ISO library needs:

• the Windows Server ISO (the evaluation one works too);
• the virtio-win drivers ISO, from the Fedora site (fedorapeople.org).

The panel:

1. creates a build VM in BIOS mode, with the ISOs attached over USB;
2. installs Windows by itself with a generated autounattend.xml: disk, virtio drivers, remote desktop, ping;
3. installs the virtio tools and cloudbase-init;
4. seals it with sysprep, makes the template and deletes the build VM.

It takes 20–40 minutes. The Screen button shows the VM screen, refreshed every 4 seconds.

Pick the edition by its number inside the ISO. In evaluation ISOs, 2 is Standard with desktop and 4 is Datacenter with desktop. The product key is optional. The unattended install accepts the Microsoft licence terms: the box in the window confirms you accept them.

On the first boot of a Windows VPS, cloudbase-init runs the panel script:

• Administrator password;
• static network, IPv6 included;
• computer name (at most 15 characters);
• remote desktop.

The disk grows by itself. After one hour the panel removes the clear-text password from the VM configuration. Windows VPSs need at least 2 GB of RAM. The Windows licence is not included.

ISO library

The ISO tab holds installation and rescue discs:

• add an ISO from a web address;
• the panel downloads it straight into an Incus volume on the chosen node;
• on the other nodes it downloads it when needed.

The type (Linux, Windows, drivers, other) is used by the Windows builder. “Clients can mount it” makes it visible to clients.

On the VPS page, CD / ISO › Mount an ISO attaches the ISO and, if you want, boots the VPS from the CD. Unmount removes it. For a manual install use the graphical console.

Graphical console

The console of VPSs on KoaVM nodes has two modes:

• Serial, for Linux;
• Graphical, the real VM screen (SPICE in the browser, through the panel).

Windows and VPSs booting from an ISO open the graphical one straight away. Ctrl+Alt+Del sends the key combination to the VM.

Apps

Apps install on the first boot of the VPS. The panel puts the script in the VPS with cloud-init and starts it as a separate service. Then it reads the status with the Incus agent.

The VPS page shows:

• the current step;
• at the end the address, user and password;
• the install log (/var/log/koavm-app.log).

cPanel, Plesk and DirectAdmin are off by default: turn them on if you sell their licences. Whoever picks them must accept the vendor's terms. For each app you can choose which plans can use it.

Your own app adds a bash script that runs as root with set -e. It has:

• the variables KOAVM_IP, KOAVM_HOSTNAME, KOAVM_FQDN, KOAVM_EMAIL and KOAVM_FIELD_<FIELD>;
• the helpers koa_step, koa_info key value, koa_install, koa_update and koa_pass.

The koa_info keys url, admin_user, admin_password and note show on the VPS page.

API and WHMCS

The /api/v1 API has:

• GET /apps;
• in POST /vps, the fields app (for example "wordpress") and app_options (for example {"license": "…"});
• GET /vps/{id}/app for the app status.

GET /images shows the type (linux or windows), requirements and plans of each system.

The WHMCS module has the Applicazione setting and a configurable option named Applicazione or Application. For Windows VPSs it saves Administrator as the service user.