Getting started with CloudGrange
CloudGrange is an open-source platform management solution for Hyper-V (Windows Server Failover Clustering) and Azure Local hybrid cloud environments. It covers the full infrastructure lifecycle — cluster registration, workload management, module installation, update management, monitoring, and AI-assisted diagnostics — from a single web portal.
This guide helps you choose an install path and get CloudGrange running in your environment.
Prerequisites
Before you install, confirm the following:
- You have a supported management host. See System requirements for hardware, OS, and network requirements.
- You know which deployment model fits your environment:
| Model | Description | Guide |
|---|---|---|
| Online | Internet-connected host; Ubuntu image and container images pulled from GHCR at install time | Online install |
| Bundled | Restricted network; pre-staged Ubuntu image and container images bundled in a zip | Bundled install |
| Appliance | Fully pre-built VHDX; import and boot — portal reachable in ~3 minutes | Appliance install |
| Azure PaaS | Azure Container Apps + PostgreSQL Flexible Server; managed control plane in your Azure subscription | Azure PaaS install |
All three modes produce an identical running state: a Hyper-V Generation 2 VM named cloudgrange-docker running six Docker Compose containers.
What CloudGrange deploys
CloudGrange's control plane runs inside a dedicated Linux VM on your Windows Server management host. The installer provisions the VM automatically. You do not configure the VM manually.
| Component | Description |
|---|---|
cloudgrange-api |
.NET 9 REST API — serves the portal and all automation clients |
cloudgrange-portal |
React portal served by nginx |
cloudgrange-postgres |
PostgreSQL 16 — platform database |
cloudgrange-prometheus |
Prometheus — metrics collection |
cloudgrange-loki |
Loki — log aggregation |
cloudgrange-otel |
OpenTelemetry Collector — telemetry pipeline |
The management host exposes port 443 inbound. All other communication is outbound from the VM to your cluster nodes.
Choose your install path
Online install (recommended for connected sites)
Download and run a single PowerShell script. The installer pulls the Ubuntu cloud image and CloudGrange container images from the internet at runtime. Requires outbound HTTPS to ghcr.io and cloud-images.ubuntu.com.
Install CloudGrange — Online mode →
Bundled install (for restricted networks)
Download a ~1.2 GB zip containing all images. Transfer it to the management host and run the installer. No internet access required after transfer.
Install CloudGrange — Bundled mode →
Appliance install (fastest path to running)
Download a pre-built VHDX (~3–4 GB) that ships with all images pre-loaded. Import it into Hyper-V and the portal is reachable within 3 minutes. Suitable for fully air-gapped sites.
Install CloudGrange — Appliance mode →
After install — first steps
Once CloudGrange is running:
- Open the portal at
https://<management-host-fqdn>(or the static IP you configured). - Complete the first-run setup wizard — creates your local administrator account and platform organisation.
- Register your first cluster under Operations → Clusters → Register a cluster.
- Deploy the Relay service inside your cluster network so CloudGrange can communicate with cluster nodes.
See Getting started — first-run walkthrough for the complete post-install sequence.