Introduction

NavEngine is a cloud infrastructure platform that connects to your Scale Computing, NodeWeaver, or OpenNebula clusters and lets you create, manage, and monetize virtual machines - all from a single dashboard. It gives infrastructure providers a complete control plane: automated billing, multi-hypervisor management, customer self-service, and built-in support - all operating under your own brand.

What This Documentation Covers

Getting Started

NavEngine is available in two deployment modes.

Self-Hosted

You run NavEngine on your own infrastructure using a provided qcow2 disk image. The NavEngine team assists with deployment to ensure everything runs correctly from the start. Review the minimum VM requirements and follow the deployment guide for your hypervisor platform:

• Scale Computing HC3
• NodeWeaver

Managed Cloud Instance

NavEngine provisions a dedicated organisation for you within the shared cloud platform. Your data and configuration are fully isolated from other organisations on the same infrastructure - no hardware setup required on your end.

Contact the NavEngine Team

To begin with either deployment option, reach out to the NavEngine team. Let them know which deployment path you prefer and they will begin the setup process with you.

Contact the NavEngine Team or Schedule an Onboarding Call

Admin Portal

The Admin Portal is the operational hub for infrastructure operators. From here you configure cloud services and products, manage client accounts, oversee orders, and handle support tickets. This guide walks through initial setup and covers all management sections.

Quick Start

A first-time setup involves four steps: resetting the Super Admin password, completing Company Settings, uploading required documents, and configuring SMTP. Once all four are complete, the Customer Portal becomes fully accessible to clients.

Step 1 - Super Admin Password Reset

The Super Admin account is created during provisioning. An email containing both the Admin Portal and Customer Portal URLs is sent to the Super Admin’s address. The Super Admin should reset their password using the link in that email and sign in to the Admin Portal to begin setup.

Step 2 - Company Settings

Several mandatory fields must be completed before the Customer Portal can leave maintenance mode and become accessible to clients. Navigate to Settings → Company Settings and complete the following tabs in order.

Tip: Right-click any screenshot in this guide and select Open image in new tab to view field labels at full resolution.

1. Company Information

Fill in all fields from Company Name through About Us, upload the company logo using the Upload Company Logo field, then click Move Out of Maintenance at the top right. Click Save and Update to apply your changes.

2. Country

Fill in the Country, Country Code, Currency, and Tax fields. Click Save and Update to apply.

3. Locations

Click Add Location and add at least one address. Once added, right-click the entry and select Set as Default to mark it as your primary address.

4. Payment Gateway

Click Add Gateway and configure a payment gateway. Ensure all credentials are entered accurately so that client payments are settled into your account.

Step 3 - PDF and Video

Navigate to the PDF and Video section and upload the following files. All four are required before the Customer Portal can leave maintenance mode.

Click Update Company Attachments to save.

Step 4 - SMTP Configuration

Navigate to the SMTP Configuration section, fill in all fields, and click Save. Use the Test Configuration button to send a test email to an address of your choosing. If the message arrives, the configuration is valid.

Once all four steps are complete, the Customer Portal is accessible to clients in full mode. The next step is connecting your clusters and building the product catalogue that clients will see in the Customer Portal.

Create Products

Products in NavEngine follow a fixed configuration hierarchy:

Cloud Service → Cloud Configuration → Product → Virtual Machine

Each layer must be created before the next. Once set up, products and their virtual machines appear in the Customer Portal immediately and are available for clients to purchase.

Step 1 - Cloud Service

Navigate to Cloud Services and click Add Cloud Service. Select a hypervisor platform from the dropdown menu to register it as a service endpoint.

Step 2 - Cloud Configuration

Navigate to Cloud Configuration and click Add Cloud Configuration. The form contains two sections:

• Cloud Service - cluster connection and resource settings. Under Service Type, select the Cloud Service created in Step 1. The Microsoft License and VLAN fields are optional and can be left blank.
• Payment Settings - billing parameters for this configuration.

Complete both sections and click Save.

After saving, live cluster resource statistics are visible on the Dashboard. If you have multiple cloud configurations, use the Select Cloud Configuration dropdown to switch between them.

Step 3 - Products and Services

Navigate to Products and Services and click Add New Product. Select a Business Name, complete the Description field, then open the Cloud Service tab and select the Cloud Configuration from Step 2 using the Select Cloud Services by Service Type dropdown. Click Save.

The product is immediately visible in the Customer Portal under the associated business name. Clients can browse it, but they will not be able to make a purchase until at least one virtual machine is added in the next step.

Step 4 - Virtual Machines

Navigate to Virtual Machines and click New Product. Fill in all fields, noting the following:

• Service Type - select the Cloud Configuration created in Step 2.
• Compute / Memory / Storage - these are the baseline values for the machine. Clients can increase these resources from the Customer Portal after purchase.
• Gold Copy - leave set to Standard unless specifically required for your deployment.

Click Save. The virtual machine is immediately available for purchase on the Customer Portal.

Client Management

The Clients section lists every account registered on the Customer Portal. For each client you can review their complete purchase history, active products, and open support tickets.

Available actions per client:

• Suspend the client account to revoke access
• Allow bypass payment to let the client purchase products without going through a payment gateway (useful for internal accounts or trial arrangements)

Order Management

The Orders section provides a consolidated view of all purchases across every client. Each order record shows the purchasing client, allocated compute, memory, and storage resources, total cost, and subscription validity period.

Actions available per order:

Ticket Management

The Tickets section displays all support tickets raised by clients from the Customer Portal. Tickets are marked Open or Resolved. To close a ticket after resolving the issue, open the ticket and click Resolve Issue.

Customer Portal

The Customer Portal is the self-service interface for end users. It allows clients to register an account, browse and purchase virtual machines, manage their subscriptions, and raise support tickets - without requiring direct contact with the administrator.

The Customer Portal can be browsed without signing in, as long as it is not in maintenance mode. If the portal shows a maintenance screen, initial Admin Portal setup has not been completed. See the Admin Portal Quick Start for the steps required to bring it out of maintenance mode.

Quick Start

Step 1 - Create an Account

Navigate to the Customer Portal home page and click Register in the top-right corner. Complete the two-page registration form, accept the Terms and Conditions, and verify your email address using the one-time password (OTP) sent to you. Once verified, your account is active and you are signed in automatically.

If you already have an account, click Login instead and enter your credentials.

Purchase Products

Step 1 - Browse the Marketplace

Navigate to Marketplace → Products and Services, or scroll to the products section on the home page. The page lists all products published by your service provider. Select a product to view the virtual machine configurations available under it.

Step 2 - Configure Your Machine

Select a virtual machine from the product listing. Set your desired Disk, Memory, CPU, and Duration values. The values shown are minimums - you can increase any of them here, and they can also be upgraded after purchase from the My Products section.

Step 3 - Complete Payment

Select a payment method - OZOW, PayFast, PayPal, or PesaPal - and complete the checkout. Once payment is confirmed, the virtual machine is provisioned and appears immediately in your Products section.

Product Management

Navigate to My Products in the top-right menu and open the Products tab to view all active subscriptions. Click any active product to view its details and available actions.

Available Actions

Before using Backup: the backup image replaces your currently running machine - it is not a silent background copy. Your previous live machine is moved to Archives and can be restored from there if needed.

Purchases

Navigate to My Products → Purchase History to view a record of all transactions on your account. Each entry shows the product name, order date, subscription duration, and total amount charged. Click View Receipt on any entry to download a PDF receipt for that transaction.

Archives Management

The Archives section holds virtual machines that were displaced by a backup operation. When you apply a backup to an active product, the backup becomes the new running machine and the previous machine is moved here rather than deleted - giving you the option to recover it.

From Archives you can:

• Restore - make the archived machine your active machine again, replacing the current live instance
• Delete - permanently remove the archived machine and free the associated storage

Ticket Management

Navigate to the Tickets section to view all support tickets you have raised. To open a new request, click Raise a Ticket, fill in the subject and description, and optionally attach a screenshot or supporting image.

Tickets are visible to the administrator in the Admin Portal and are marked Open or Resolved. You will receive a notification when your ticket is resolved.

Profile Management

Navigate to My Profile to update your personal details, including your profile picture, display name, and contact information. Click Update to save any changes.

Self-Hosting

NavEngine ships as a qcow2 disk image with Ignition embedded in the OEM partition. On first boot the image self-provisions and starts the application stack.

SSH is intentionally disabled.

Minimum VM Specification

Why These Settings Are Required

The NavEngine image runs Flatcar Container Linux, which only includes VirtIO drivers. Four QEMU settings are non-negotiable - if any are wrong, the boot sequence fails before systemd starts and the hypervisor interprets the immediate reboot as a crash loop.

Deployment Guides

Select the guide for your hypervisor platform:

• Scale Computing HC3
• NodeWeaver

Post-Installation Checks

Once the VM is running on either platform,access your navengine instance on:

https://<public-ip>:4200

Scale Computing HC3 / HyperCore

Prerequisites

• Access to the HC3 web UI (typically https://<node-ip>)
• The built navengine.qcow2 image available on your workstation
• A VLAN with internet access already defined in HC3

Deployment Steps

Step 1 - Upload the disk image

1. Open a browser and navigate to https://<your-hc3-node-ip>.
2. Log in with your HC3 administrator credentials.
3. In the left sidebar scroll down to the Uploaded Disk Images section (below the VM list and cluster resource panels).
4. Click Upload (or the upload icon next to the section header).
5. Select navengine.qcow2 from your workstation and confirm.
6. Wait for the progress indicator to finish. When complete the filename appears in the Uploaded Disk Images list.

Step 2 - Create the VM

Important: The Boot From dropdown in the Create VM dialog only lists ISO/CD-ROM sources. Uploaded qcow2 disk images never appear there. Leave Boot From set to None - the navengine disk is attached separately in the next step.

1. Click + Create VM (the button in the top-right of the Virtual Machines panel).
2. Fill in the dialog:

3. Click Create. The VM tile appears in the Virtual Machines list showing 4 cores, 100 GB disk, 0% utilisation.

Step 3 - Add the navengine disk to the VM

1. Locate the new VM tile and click the disk / layers icon at the bottom of the tile (the stacked-layers icon in the row of action buttons).
2. The Add Drive dialog opens:
   • Source: select Uploaded
   • Disk Image: open the dropdown and select navengine.qcow2
3. Click Create.
4. HC3 clones the uploaded image onto the VM. A COMPLETED notification appears at the bottom-right of the screen once the clone finishes (wording: “Clone of block device … into virtual machine navengine-01”).

Step 4 - Delete the blank placeholder disk

CRITICAL - this step causes the reboot loop if skipped. Moving the blank disk to Don’t Boot is NOT sufficient. “Don’t Boot” only removes the disk from the BIOS boot sequence; the disk remains physically attached to the VM and the kernel still sees it as vda. When GRUB enumerates VirtIO disks the blank disk becomes hd0 and the navengine disk becomes hd1. GRUB’s OEM partition search starts at hd0, finds nothing there, and may not search further - leaving ignition.config.url unset. Without it, Ignition cannot find its config and Flatcar immediately reboots. The blank disk must be deleted entirely.

1. On the VM tile, click the disk / layers icon (same one used in Step 3).
2. The disk list shows both the navengine disk and the blank 100 GB disk.
3. Click on the blank disk entry (da33589d 100 GB or similar).
4. Click Delete and confirm. The blank disk is removed from the VM.

Step 5 - Change the boot order

1. Click the wrench / settings icon on the VM tile, then choose Boot Order (or look for a Modify Boot Order action in the VM detail view).
2. The Modify Boot Order dialog shows two sections:
   • Boot Order - devices the VM will try to boot from, in order
   • Don’t Boot - devices excluded from the boot sequence
3. The navengine disk (shown by its serial number and size, e.g. b5677b5a 13.2 GB) should appear in Boot Order. Only the VIRTIO network interface should remain in Don’t Boot.
4. If the navengine disk is not already at the top of Boot Order, drag it there using the handle (≡) on the right of its row.
5. Click Modify.

Step 6 - Start the VM and verify

1. Click Start on the VM tile (the power icon).
2. Click the console icon (monitor symbol) to open the graphical console.

Expected boot sequence:

Booting 'Flatcar default'
...

The first boot takes 5–10 minutes depending on your network configuration. After installation, the tty will render a login screen. You can proceed to access navengine on https://<public-ip>:4200

If the VM reboots in a loop:

Open the console at the moment of failure and look for [FAILED] lines.

NodeWeaver

Prerequisites

• Access to the Sunstone (or FireEdge) web UI - typically http://<one-ip>:9869 (Sunstone) or http://<one-ip>:2616 (FireEdge)
• oneadmin or a user with image management and VM instantiation rights
• The built navengine.qcow2 image on a host that NodeWeaver can reach (HTTP server, or the front-end host itself)
• A virtual network with internet access already defined in NodeWeaver

Deployment Steps

Step 1 - Upload the image

Via Sunstone UI

1. Log in to Sunstone.
2. In the left sidebar go to Storage → Images.
3. Click the green + button (top-right).
4. Fill in the Create Image form:
   • Name: navengine
   • Type: OS (not Datablock, not CDROM)
   • Datastore: choose your default image datastore (usually default or images)
   • Image location: choose Upload and select navengine.qcow2 from your workstation, or choose Provide a path and enter the absolute path on the front-end host if you have already copied the file there (faster for large images).
   • Format: qcow2
   • Persistent: leave unchecked - this lets you run multiple VMs from the same base image.
5. Click Create.
6. The image enters LOCKED state while it transfers. Wait until the status changes to READY (refresh the Images list; takes 1–5 minutes depending on datastore speed).

Via CLI (faster for large images)

Copy the qcow2 to the NodeWeaver front-end, then:

oneimage create \
  --name navengine \
  --type OS \
  --format qcow2 \
  --datastore default \
  --path /path/to/navengine.qcow2

Wait for oneimage show navengine to report STATE: READY.

Step 2 - Create a VM template

1. In Sunstone go to Templates → VM Templates.
2. Click + to create a new template.

General tab

Storage tab

1. Click Add another disk.
2. In the Disk 0 row:
   • Image: select navengine (the image you just uploaded)
   • Bus: VirtIO - open the dropdown and choose virtio. This is critical; the default ide will cause the restart loop.
   • Cache: writeback
   • IO: threads

Network tab

1. Click Add network interface.
2. In the NIC 0 row:
   • Network: select the virtual network that has internet access.
   • Model: VirtIO - set this explicitly; the default varies by NodeWeaver version and may be e1000.

OS & CPU tab

1. Expand Boot order: ensure disk0 is first (drag it to the top if needed).
2. Under Machine type: enter pc-q35-7.2 (or simply q35 - NodeWeaver passes this string directly to QEMU’s -machine argument). If you leave this blank NodeWeaver uses pc (i440fx) which does not support VirtIO-PCIe correctly.
3. Under BIOS / Firmware: select BIOS (SeaBIOS), NOT UEFI. If the field is absent the default is BIOS which is correct.

NodeWeaver raw template equivalent - if you prefer editing the template directly (Advanced / Template tab) the minimum additions are:

DISK = [ IMAGE="navengine", BUS="virtio", CACHE="writeback", IO="threads" ]
NIC  = [ NETWORK="<your-network>", MODEL="virtio" ]
OS   = [ BOOT="disk0", MACHINE="q35" ]

Context tab

NodeWeaver’s contextualization injects a cloud-init-like ISO into the VM. NavEngine uses Ignition (embedded in the OEM partition), not NodeWeaver contextualization. If the context ISO is attached NodeWeaver assigns it as a CDROM device which is harmless, but to keep the VM clean:

• Uncheck Add Network context and Add SSH key (they have no effect on a Flatcar image that ignores NodeWeaver context).
• You may leave the context block entirely blank or remove it.

Step 3 - Instantiate the VM

1. In Templates → VM Templates select navengine-template.
2. Click Instantiate (the play icon).
3. In the dialog:
   • VM name: navengine-01 (or any name)
   • Leave all other fields at template defaults.
4. Click Instantiate.

The VM appears in Instances → VMs with state PENDING → PROLOG → RUNNING.

Step 4 - Monitor the boot

1. In Instances → VMs click on your VM row.
2. Click the Console button (VNC or SPICE icon) to open the graphical console.

Expected boot sequence (same as HC3):

Flatcar Container Linux by Kinvolk  ...

First boot: allow 5–10 minutes.

If the VM reboots in a loop:

Check the console at the moment of failure. Common patterns and fixes: