Get Started (SolusVM 2)
Fast path from a SolusVM 2 management node to a NodeRings-ready panel (compute resource, network, images, plan, API token)
This guide takes you from a fresh SolusVM 2 management node to a panel that is ready to sell through NodeRings: license, compute resource, network, IP block, OS images, plan, and Admin API token — then the NodeRings onboarding path.
NodeRings is the customer control plane: billing, marketplace, DNS, and VM UI stay in NodeRings. Customers never log into the SolusVM panel. The SolusVM API token stays on your agent — NodeRings mothership does not store it.
Using Proxmox or VirtFusion? Use Get started (Proxmox) or Get started (VirtFusion). One organization uses one hypervisor driver. Do not mix Proxmox, VirtFusion, and SolusVM in the same org or the same nr cluster register.
SolusVM 2 only. REST /api/v1 and a Bearer Admin token. SolusVM 1 (:5656, id + key, vserver-create) is a different product. Do not point NodeRings at a SolusVM 1 master.
One control plane per compute resource. Do not let WHMCS, Blesta, or another orchestrator provision the same SolusVM plans, locations, and compute resources that NodeRings will place. Two orchestrators double-book IPs and servers.
Marketplace create-VM shows the same five labels as Proxmox. On SolusVM 2 Instant Apps and Cloud-init are supported (compiled Admin API user_data, not SolusVM Applications and not a cidata ISO). Firewall, Snapshots, and Backups are not supported in the first NodeRings release.
Before you start
| You need | Minimum |
|---|---|
| OS for the management node | AlmaLinux 9/10, Debian 12/13, or Ubuntu 22.04/24.04. Not Ubuntu 26.04. |
| Hardware (management node) | 4 cores / 8 threads, 8 GB RAM (4 GB absolute minimum), 40 GB free disk, KVM (VT-x/AMD-V) if this box is also the hypervisor |
| License | WebPros activation code for SolusVM 2 (see License) |
| Compute resource | At least one active KVM host (all-in-one management+hypervisor is fine for a lab) |
| Agent VM | Ubuntu 22.04+, 2 vCPU, 4 GB RAM, outbound HTTPS — separate from the management node in production |
| Domain | One you control (DNS or HTTPS verify) |
| Guest IPs | Public (or lab) IPv4 block in SolusVM; the panel assigns guest addresses (NodeRings IPAM is not used) |
| OS images | KVM cloud-init images in SolusVM |
| Admin API token | Dedicated token for the agent (see API token) |
Documentation examples use TEST-NET-3 (RFC 5737). Replace with your real addresses.
SolusVM 2 panel
Finish this before you register a NodeRings agent. Copy these integers when you are done: compute resource id, location id, plan id, OS image version id (not the parent OS image id).
One compute resource per NodeRings node. NodeRings always pins create to that CR. Extra hosts in SolusVM auto-balance would make placement dishonest — NodeRings will not use auto-balance.
Management node
Install on a fresh OS. Purge leftover KVM/libvirt, VirtFusion, Proxmox, or custom bridges before the installer runs. The management node listens on HTTPS 443 and RabbitMQ TCP 5671.
Set hostname and a stable IP
Give the box a resolvable name or use its management IP. SolusVM stores this as the frontend host (certificates, API, console proxy).
hostnamectl set-hostname mn.example.com
# Put the management IPv4 in /etc/hosts if you have no public DNS yetUse a static address. DHCP that changes after install breaks the panel URL and the license IP lock.
Download and run the installer
As root:
curl https://installer.dev.solusvm.com/latest -o installer
chmod +x ./installer
./installer -accept-eula -admin-email [email protected] -hostname 203.0.113.10-hostname is the address browsers and the agent will use (FQDN or IP). For a public FQDN the installer can issue Let’s Encrypt. For a private IP it uses a self-signed certificate — browsers warn; the agent must trust that cert or skip verify only in lab.
The current installer is 2.0.x (Docker Swarm stack under /usr/local/solus). Installation logs go to the installer output and /var/log/solus.
Log in
Open https://<hostname-or-ip>/admin. Username is the email you passed. Password and a one-time login link are printed at the end of the installer — save them (for example /root/solusvm-credentials.txt mode 600 on the box). Do not commit them to git.
Official requirements: SolusVM 2 installation.
License
A license does not create a compute resource. It only unlocks how many CRs and VMs you may add.
Activate in Settings → License (or SolusVM License) with the WebPros / Plesk activation code from the client area or purchase email. It looks like XXXXX-XXXXX-XXXXX-XXXXX-XXXXX.
Do not paste the store SKU line (for example SVM2-MNV… plus Mini/Micro counts). That is a product identifier, not an activation code. SolusVM rejects it as incorrect activation code format.
Typical SKUs:
| License | What it unlocks |
|---|---|
| Management Node | Add compute resources (no VMs on the MN itself) |
| Management Node w/ Virtualization | Add CRs and run KVM on the management node |
| Compute Resource Mini | One CR, max 5 VMs |
| Compute Resource Micro | One CR, max 2 VMs |
| Compute Resource Unlimited (Standard) | One CR, unlimited VMs |
GET /meta shows isLicenseActive. Confirm Mini/Standard/Micro limits in the license page before you add a CR — an unlicensed panel reports Mini limit 0 and create fails.
Compute resource
Compute Resources → Add Compute Resource. A license only unlocks a slot — this page is empty until you add a host.
Compute Resources list
Step 1 of 3
Create the resource
Set name (for example edge-1), host (SSH address of the hypervisor — on all-in-one this is the management node IP), login root, SSH port 22, agent port 8080.
Authentication: SSH key (preferred) or password. The management node must be able to SSH to that host.
Pick a license type
Mini, Micro, or Standard must match what you paid for. On Management Node w/ Virtualization, you can add this same box as the hypervisor; SolusVM then reports is_management_node.
Attach a location
Use the built-in Default location or create one (for example ams). Copy the location id. NodeRings create always sends this location. The SolusVM plan must list it under available locations.
Wait until Active
Commissioning installs the SolusVM agent, libvirt, and dependencies. Status goes commissioning → configure network → active. Do not register the NodeRings node until status is active, KVM is on, and the resource is not locked.
Copy the compute resource id from the table (this is the NodeRings node).
Compute resource ports (SolusVM’s agent, not NodeRings): SSH 22, agent 8080, VNC proxy 7778. NodeRings talks to the management node :443 only.
Network
After commissioning, SolusVM asks you to set up network. NodeRings does not configure CR networking.
| Type | When to use |
|---|---|
| Bridged | Guests sit on the same L2 as the uplink (typical colo / LAN). Interface is the NIC or OVS bridge guests should use (eno1, br-ext, …). |
| Routed | The compute resource routes guest traffic (NAT/gateway). LAN hosts need a route to the guest prefix via the CR, or guests will not be reachable off-box. |
Bridging the uplink on an all-in-one management node (Docker Swarm + NetworkManager + OVS) can drop SSH for a minute while br-ext / br-int come up. Use console/KVM access the first time. Leave the management IPv4 on the external bridge, not a second duplicate address on the physical NIC.
Confirm a test VM (optional but recommended) gets an address and can ping the gateway before you connect NodeRings.
IPv4 block
Network → IP Blocks (page title is IP Addresses). Register an IPv4 prefix in SolusVM on this compute resource. SolusVM assigns the guest address (primary_ip). Guest DNS comes from the block (ns_1 / ns_2). NodeRings does not run IPAM for SolusVM.
IPv4 block on the compute resource
Step 1 of 1
| Field | Example |
|---|---|
| Block name | pub-203-0-113 |
| Type | IPv4 |
| List type | Range |
| Gateway | 203.0.113.1 |
| Netmask | 255.255.255.0 |
| Nameservers | 1.1.1.1, 8.8.8.8 |
| From–to | 203.0.113.10 – 203.0.113.20 |
Network → IP Blocks → Add IP Block (or Compute Resources → the CR → IP blocks).
Create the block
Name it, type IPv4, range, gateway, netmask, nameservers. Do not include the management IP, gateway, or other infrastructure unless you intend to assign them to guests.
Assign the compute resource
Attach the block to the CR you will sell on. Unassigned blocks cannot be used as primary_ip.
Keep this CIDR on the compute resource (here 203.0.113.0/24). NodeRings does not copy it into IPAM. IPv6 in SolusVM is optional; the first release uses IPv4 as primary_ip.
OS images
A VM template in NodeRings is a SolusVM OS image version id, not the parent OS image id, and not a Proxmox VMID. Open the version; the id is in the admin URL (or the ID column on the version list).
Images → Operating Systems. Stock distros (AlmaLinux, Debian, Ubuntu, Rocky, …) appear after install. Each row is a parent; expand it — versions are what you register (Ubuntu 24.04 is a version id, not the Ubuntu parent id).
Operating Systems
Step 1 of 2
Enable the versions you will sell
Open each distro → versions (Ubuntu 22.04, Ubuntu 24.04, Debian 12, and so on). Prefer cloud-init images. Visible + available for KVM. Confirm each version supports SSH keys.
Copy each version id
NodeRings template_id = version id. The parent image id (Ubuntu as a row) is the wrong number.
SolusVM already generates guest cloud-init and owns guest networking. Do not create NodeRings cloud-init ISO templates for these VMs. Optional NodeRings user-data (users, SSH, packages, hostname) is a string on create — never NodeRings network-data.
Plan
Each NodeRings plan points at one SolusVM plan id. Create the plan in the panel (NodeRings will not POST /plans).
Compute Resources → Plans → Create Plan.
Plans
Step 1 of 2
Create a KVM plan
Name it (for example nr-shared-2c-4g). Virtualization KVM (not Virtuozzo/OpenVZ). Set vCPU, RAM, and disk to match the SKU you will sell.
Storage type and image format
Must exist on that compute resource. File-based (fb) with qcow2 is the default after a typical install (/var/lib/libvirt/images/). Use lvm / thinlvm / nfs only if that storage is already on the CR.
Locations, OS versions, extra IPs
- Available locations must include the location on the CR.
- Available OS image versions must include every version you will register in NodeRings.
- Enable additional IPs if you will sell ADDITIONAL-IP.
Copy the plan id
The ID on the plans list is metadata.solusvm.plan_id later. Create a test VM in the SolusVM UI against this plan + CR + image if you can — a 422 here is cheaper than a failed marketplace live validation.
Turn off SolusVM “server created / password reset” mail to customers. NodeRings owns those emails. Do not enable customer panel SSO.
API token
Access → API Tokens → Generate API Token.
API Tokens
Step 1 of 3
Open API Tokens
In the left sidebar, Access → API Tokens. The list shows existing tokens (name, user, created). Click Generate API Token.
Name it for the agent
Name (for example noderings-agent). User must be an Admin (the install email). Tags are optional. Click Generate.
Copy the secret once
SolusVM shows the token once with Copy & Close. Store it in a password manager. You cannot view it again; you would have to generate a new token.
Save the token secret when it's shown. It cannot be read again. A client-role user is not enough — pick the Admin user.
SolusVM Admin tokens are not a Proxmox ACL grid. Use an Admin token. A client token that cannot create servers is not enough.
| What the token must do | API the operator will call |
|---|---|
| Identity / health | GET /account |
| Inventory | GET /compute_resources, GET /locations, GET /plans, GET /os_images, GET /ip_blocks |
| Users / projects | GET/POST /users, GET /projects (never user SSO tokens) |
| SSH keys | POST/GET/DELETE /ssh_keys |
| Servers | POST/GET/DELETE /servers, start/stop/restart, reinstall, suspend/resume, reset_password, ips, vnc_up |
| Tasks | GET /tasks/{id} |
| Usage | GET /usage/{cpu|memory|network|disks}/{uuid} (metrics exporter) |
Notes
- Platform URL is the management origin only (for example
https://mn.example.com) — no/api/v1, no:5656, no compute-resource IP. The operator appends/api/v1.
Smoke-test from a machine that can reach the panel (lab):
curl -sk -H "Authorization: Bearer $SOLUSVM_TOKEN" \
https://mn.example.com/api/v1/accountPorts the agent will use
| Path | Port | Who talks |
|---|---|---|
| Agent → NodeRings | 443 | Liqo + API |
| Agent → SolusVM management node | 443 | Operator, exporter, console gateway |
| Browser → NodeRings | 443 | Console is proxied; customers never hit the MN |
| Compute resource agent | 8080 | SolusVM only |
| Compute resource VNC | 7778 | SolusVM; NodeRings console uses MN websockify, not this port |
Checklist before NodeRings
| In SolusVM 2 | Why |
|---|---|
| Management node, valid TLS (or lab self-signed) | Agent HTTPS to :443 |
| License active | CR/VM limits |
| ≥1 compute resource active, KVM, not locked | Node = that CR |
| Location attached | location on create |
| IP block assigned; CIDR = future NodeRings prefix | primary_ip |
| Nameservers on the IP block | Guest DNS |
| Network type already working | NodeRings does not set bridges |
Storage matching the plan storage_type | Disk create |
| KVM plan; locations + OS versions allowed; extra IPs if selling them | plan_id |
| OS image versions with cloud-init and SSH keys | Templates |
| Admin API token saved | Agent Secret |
Onboarding path
Organisation, Stripe, and regions are the same as Proxmox and VirtFusion. Agent register and later steps wait on the SolusVM driver.
1. Organization
Create a provider organization, verify your domain, and complete your business profile before NodeRings unlocks infrastructure and billing.
Create organization
Step 1 of 5
Create a provider organization
In the sidebar, open the organization menu → Add organization → choose Provider (sells services to clients) → enter your company name → Create Organization.
Verify your domain
On Provider onboarding, enter the domain you will list on the marketplace (for example acme.com) and choose a verification method:
At your DNS host, add a TXT record:
- Name:
_nrings-challenge.<your-domain>(foracme.com, use_nrings-challenge.acme.com) - Value: the verification code shown in the dashboard
On your public web server, create:
- URL:
https://<your-domain>/.well-known/nrings-challenge.json - Content:
{ "_nrings-challenge": "<verification-code>" }(use the code from the dashboard)
Click Add Domain, apply the challenge, then Verify. DNS can take a few minutes to propagate.
Complete your organization profile
Fill in the details NodeRings uses for marketplace review and customer-facing listings:
- Organization name (legal company name)
- Support email, billing email, and support phone
- Business address (country, region, city, postcode)
- Tax identifiers (VAT ID, tax ID where applicable)
- DDoS provider and ASN (if you operate your own network)
- Provider logo (PNG or SVG, max 512 KB)
- Business owner name and social profiles (optional)
Request review
Click Request review and save. NodeRings reviews your listing; infrastructure unlocks after approval. Set up Stripe Connect under Organization → Billing → Payout when ready.
More detail: Organization · Domain verification.
2. Stripe Connect
Marketplace revenue is paid out through Stripe Connect. NodeRings charges the customer, keeps the platform commission for your tier, and transfers the rest to your Stripe account. Until Connect is active with charges and payouts enabled, you can still build infrastructure, but you cannot receive marketplace payouts.
A Community platform subscription is attached when you create the organization. Connect is available on Community and paid tiers. Open /billing/payout → Payout Methods → Connect Account.
Create Connect Account
Step 1 of 4
Choose how to connect
On Payout Methods → Connect Account, choose Create Connect Account or Use existing Stripe account. Creating a new account still opens Stripe's hosted onboarding (signing in there can reuse verified business and bank details, but NodeRings still gets a new Stripe account). Use existing connects the Stripe account you already use, including its balance and payout history. The existing account must be a Standard account that is not connected to another platform or to a different NodeRings organization. Disconnect a manual payout account first if one is configured.
Complete Stripe onboarding
If you created a new account, status is Pending and charges and payouts stay disabled until you finish Stripe's hosted form. Click Complete Setup & Onboarding, provide business and identity details, then return to the dashboard.
Confirm Active
When onboarding succeeds, the account shows Active with Charges Enabled and Payouts Enabled. You can set a payout schedule under Payout Schedule. If Stripe Connect is not available in your country, use Manual Payout instead (funds are held longer before release).
More detail: Billing & Payouts.
3. Region
A region is where you tell NodeRings where your infrastructure lives. It is the geography customers see when they pick a plan.
Regions page
Step 1 of 2
Pick the geography
Select country and city that reflect where your SolusVM compute resources actually run.
Choose datacenter
Select the facility from the list, or choose Other if you do not want to disclose the facility on the marketplace.
Choose availability zone
Pick zone_a, zone_b, or another zone only when the infrastructure is truly separate. If everything shares one fabric, use a single zone.
Save the region
Click Create Region. The region is then available when you attach nodes and plans.
More detail: Regions.
4. Agent
An agent is a lightweight k3s cluster on a VM inside your infrastructure. Do not install it on the SolusVM management node in production (same rule as not running the agent on a Proxmox host).
The agent must reach NodeRings (API + Liqo) and the SolusVM management node HTTPS :443.
Agents page
Step 1 of 3
Register the agent
Enter an agent name and the VM’s public IPv4 address.
Choose gateway region
Select the gateway region closest to your agent VM.
Provision on your agent VM
You must pass SolusVM as the driver (the default installs Proxmox). Prefer Create agent in the console: it copies a command that already includes --org-id. Use a service account token on the VM (do not run nr auth login):
export NR_API_TOKEN='<service-account-token>'
echo $NR_API_TOKEN
export SOLUSVM_URL="https://mn.example.com" # origin only, no /api/v1
export SOLUSVM_TOKEN="…" # agent Secret only
nr cluster register \
--name "Frankfurt SolusVM" \
--agent-ip 203.0.113.10 \
--gateway-region AMS01 \
--hypervisor-driver solusvm \
--org-id <org-uuid>The CLI installs k3s, Calico, Liqo peering, and solusvm-operator into solusvm-system (not proxmox-system or virtfusion-system).
Verify
On the agent:
nr cluster verify --name edge-svm-01Expect Helm namespace solusvm-system, CRDs in vm.solusvm.com, and Deployments for the SolusVM operator, exporter (svm_* on :9179), Alloy, and vnc-gateway.
The SolusVM token never leaves your agent. NodeRings mothership does not store it. Do not paste it into Helm --set, ~/.nr, or a mothership values file.
More detail: Agents · CLI & automation.
5. Platform and node
Your agent controls one platform (the SolusVM management node) and one or more nodes (each node is one compute resource).
Before you add a platform, confirm your agent is provisioned and green in /infrastructure/agents.
Platform
/infrastructure/platforms-nodes → Add Platform.
Platforms & Nodes page
Step 1 of 2
Add a platform
Give it a name, select driver SolusVM 2, and choose the agent you provisioned.
Set the endpoint URL
Enter the management-node origin only, for example https://mn.example.com. Do not append /api/v1. Do not use a compute-resource IP. Do not use SolusVM 1 :5656.
The agent must reach this URL. The operator probes GET /account. The endpoint URL cannot be changed after the platform is created.
Each endpoint URL can be registered once per organization. If this org already has a Proxmox or VirtFusion platform, create is rejected — one driver per org.
Node
A node is one SolusVM compute resource. Add a shared compute node. SolusVM orgs do not offer dedicated cores.
Add Node
Step 1 of 3
Add a node
Under your platform, click Add Node. Enter:
| Field | Meaning |
|---|---|
| Compute resource id | Host id from Compute Resources |
| Location id | Location attached to that CR |
They are not the same number.
Attach region
Select the region from §3 Region where this host physically sits.
Skip Proxmox-only fields
Do not fill vmbr0, local-lvm, VMID seed, vzdump, NIC model, MAC prefix, or dedicated/topology. Network type and storage type live in SolusVM.
Resource overallocation
Set CPU, memory, and storage overallocation percentages. A plan still cannot exceed a single node’s physical size.
More detail: Platforms & nodes.
6. VM templates
Register VM templates with the SolusVM OS image version id from OS images. No Proxmox VMID, no pvesh, no NodeRings cloud-init ISO edge.
The onboarding CLOUD_INIT checklist step auto-passes for a SolusVM org. Skip /infrastructure/cloud-init as a requirement. Optional user-data profiles are still allowed later.
VM Templates page
Step 1 of 4
Register in NodeRings
Click Create VM Template. Select node, distro, and the SolusVM OS image version id.
Cover the catalog you sell
Preflight expects every OS you list to be registered on the node. The version must be allowed on the SolusVM plan.
More detail: VM templates.
7. Guest IPs
SolusVM assigns guest addresses from the IP block on the compute resource. NodeRings does not run IPAM, outbound SMTP policy, or cloud-init templates for this driver: Network and Cloud-Init Templates are hidden in the sidebar, and marketplace preflight omits ip_available and cloud_init_template. Block SMTP in SolusVM Settings → Network rules if you need it.
Keep the IPv4 block attached to the compute resource. Extra IPv4 uses POST /servers/{id}/ips (ADDITIONAL-IP). On a running VM the guest NIC config is the customer’s job.
Onboarding steps for IPAM networks and prefixes auto-pass for SolusVM 2.
If the compute resource has no free IPv4 in its block, create fails. Confirm available addresses in SolusVM before selling.
8. Plans and addons
A plan is the VM size and price customers buy. Clone a shared plan template (no DC-* dedicated-core plans). Full reference: Plans & Addons.
Plans and Addons tabs
Step 1 of 6
Create a plan
Plans tab → Create Plan → shared billing type, region, and template. Set SolusVM plan id to the plan from Plan (metadata.solusvm.plan_id).
Match the SolusVM SKU
vCPU, RAM, and disk should match the SolusVM plan (or you accept SolusVM custom_plan overrides). The SVM plan must already allow the location and every OS version you registered.
Create addons
Required marketplace addon for SolusVM: ADDITIONAL-IP only. Do not require DAILY-BACKUP, WEEKLY-BACKUP, or snapshot storage. NodeRings does not create on-demand backups or snapshots on SolusVM in the first release.
More detail: Plans & Addons.
9. Preflight check
After plans and addons exist, NodeRings validates that your infrastructure can sell them before they appear in marketplace search.
Platform/node health uses svm_compute_resource_up (not pve_up or vf_hypervisor_up). Live validation provisions an OS-only pilot (SSH key, optional user-data, no Instant App).
Two stages, both required
| Stage | How it runs | Marketplace impact |
|---|---|---|
| Preflight | Automatic; re-runs every few minutes | Any red gate removes the plan from search until fixed |
| Live validation | Manual; you start each plan × node run | Plan lists only after at least one node passes preflight and live validation |
Preflight check dashboard
Step 1 of 5
Wait for preflight to go green
Fix red gates (agent, platform, node, templates, addons).
Run live validation per plan × node
Use Start validation for every combination you sell on.
Confirm marketplace ready
Summary shows Ready with no blockers, and live validation shows Validated: Yes for at least one node in the sell region.
Preflight quick fixes
| Red gate | Try this |
|---|---|
agent_online | Agent provisioned; platform linked to agent |
platform_online | Management HTTPS up; metrics flowing (svm_compute_resource_up) |
node_online | Node active, in plan region, not in maintenance; SVM CR active |
plan_physical_fit | Node has enough physical CPU, RAM, and disk for the plan |
plan_capacity | Node has sell headroom after overallocation; Mini CR max 5 VMs |
os_template | Register missing VM template (OS version id) on that node; version allowed on the SVM plan |
addons_created | Create ADDITIONAL-IP with the same billing type as the plan |
More detail: Preflight Check.
What customers get
| In NodeRings | Not in the first SolusVM release |
|---|---|
| Power, console (NodeRings noVNC), reinstall, password, SSH keys | SolusVM panel login / SSO |
Cloud-init user-data and Instant Apps (compiled user_data, not SolusVM Applications) | Cloud-init ISO, SolusVM one-click Applications |
| Additional IPv4 | Guest firewall, snapshots, on-demand backups |
| Billing, tickets, reviews | Dedicated CPU, NodeRings-allocated MAC |
Console is POST /vnc_up on the management node, proxied by the agent. Customers never open the SolusVM viewer.
Stuck?
| Problem | Read |
|---|---|
| Installer rejects the OS | Use Debian 12/13, Ubuntu 22.04/24.04, or AlmaLinux 9/10 — not Ubuntu 26.04 |
| License “incorrect activation code format” | Paste the WebPros activation code, not the SVM2-MNV… SKU |
| Compute Resources list empty | License only unlocks a slot; add the CR |
| Mini limit 0 | License not active, or you used the wrong SKU |
| SSH lost after bridged setup | Console access; IP belongs on br-ext, not a duplicate on eno1 |
| Agent not provisioned | §4 Agent; --hypervisor-driver solusvm; Helm namespace solusvm-system |
| Platform offline | Origin without /api/v1; token on the agent only; SolusVM 2 not :5656 |
| Wrong template id | Use OS image version id, not parent image id |
| Create 422 location/OS | SVM plan available_locations / available_os_image_versions |
| Console fails | Agent must reach management node 443 (websockify), not CR :7778 |
| Domain verify fails | Domain |
| Architecture / security | How it works |