Getting started — first-run walkthrough

This guide picks up after you’ve completed the platform install. Pick the install path that matches your deployment first:

• On-premises: On-premises install →
• Azure PaaS: Azure PaaS install →

Step 1 — Open the portal

After your install finishes, open the portal URL in a browser.

CloudSmith deploys with no external identity provider configured. On first hit, the portal sends you straight into the setup wizard.

Step 2 — Complete the first-run wizard

The wizard is four steps. You only see it once — it locks after completion.

1. Welcome — review the brief and continue.
2. Platform — name your platform (e.g. CloudSmith Prod), set the public URL (the portal URL from Step 1), pick a timezone.
3. Administrator — create the local administrator account. Choose a username (e.g. admin), an email, and a password of at least 8 characters. This account stays active as your break-glass even after you add an external identity provider.
4. Review & complete — confirm and select Complete setup. CloudSmith creates your platform organisation, your admin user, assigns the PlatformAdmin role, and signs you in automatically.

You land on the dashboard. Because no cluster is registered yet, the dashboard shows a first-run walkthrough card with three numbered steps — Register cluster, Deploy Relay, Verify connectivity. The next sections walk you through it.

Step 3 — Optional: connect an external identity provider

Skip this step if you only need the local administrator for now. Add it later under Platform Management → Identity Providers.

To add an IdP now:

1. Open Platform Management → Identity Providers in the left navigation.
2. Select Add identity provider and pick the type:
   • Microsoft Entra ID — supply tenant ID, client ID, client secret.
   • Active Directory (LDAP) — supply domain, bind DN, bind password.
   • Generic OIDC — supply authority URL, client ID, client secret.
   • Keycloak — supply realm URL, client ID, client secret.
3. The provider is saved with status Configured. You can edit, disable, or remove it later.

The local administrator stays active no matter how many external IdPs you add.

Step 4 — Register your first cluster

CloudSmith reaches each managed cluster through a Relay — a per-site Linux service that bridges the platform to your on-prem network. You’ll register the cluster first, then deploy the Relay onto your site network.

1. In the left navigation, open Clusters.
2. Select Register a cluster. The 3-step wizard opens.

3. Step 1 — Cluster details:

   Field	Value
   Cluster name	A friendly name (e.g. prod-hci-01)
   Site	Optional — pick or skip; you can assign later
   Cluster type	Hyper-V WSFC or Azure Local

4. Step 2 — Deploy the Relay. The wizard generates an enrollment token and shows a copy-pasteable docker run command:

   docker run -d --name cloudsmith-relay --restart=always \
     -e RELAY_PAAS_URL=https://<your-portal-url> \
     -e RELAY_ENROLLMENT_TOKEN=<one-time-token> \
     -e RELAY_DISPLAY_NAME=relay-prod-hci-01 \
     -v cloudsmith-relay-identity:/var/lib/cloudsmith-relay/identity \
     ghcr.io/cloudsmith-cloud/cloudsmith-relay:latest
   

   Run this on a Linux host (Docker, Podman, or Kubernetes-friendly) inside the same network as your cluster nodes. The Relay reaches out to the platform over HTTPS port 443; no inbound firewall changes are required on your premises.

5. Step 3 — Add hosts (optional). You can install a lightweight per-host Agent on each Hyper-V host for richer local data, OR let the Relay reach hosts via PowerShell Remoting. Either choice works — skip this step for now if you’re not sure.
6. Select Register cluster. The cluster appears in the list with status Pending until the Relay connects.

Once the Relay starts and enrolls, the cluster status flips to Healthy and inventory begins flowing in.

Step 5 — View inventory and health

1. Open Operations → Clusters and click your cluster.
2. The cluster page has tabs for hosts, VMs, networks, and storage. Each populates as the Relay finishes its first scan (30–90 seconds for a typical cluster).
3. Open Operations → Inventory to see VMs across all registered clusters in one view.
4. Open Operations → Monitoring for the workload-monitoring module’s view (requires the monitoring module to be installed under Platform Management → Modules).

If a panel sits empty after a minute, check Platform Management → Sites for the Relay’s heartbeat — last-seen should be within the last 30 seconds.

Step 6 — Next steps

Troubleshooting

The wizard already ran — I see a login page instead. Setup is one-shot and locks after the first completion. Sign in as the local administrator you created. If you’ve lost those credentials, recovery requires a DB-level reset of the core.platform_setup row — see on-premises.html for the recovery procedure.

The Relay won’t connect. Confirm outbound HTTPS 443 from the Relay host to <your-portal-url> is allowed. The Relay logs every connection attempt (docker logs cloudsmith-relay); look for Enrolled successfully followed by WebSocket connection established.

The cluster shows Pending but the Relay is connected. The first inventory scan can take 30–90 seconds. If it sits Pending past two minutes, check the Relay logs for inventory scan lines and confirm WinRM or the Agent is reachable from the Relay host to each cluster node.

An identity provider was added but users still can’t sign in. Confirm the IdP’s redirect URI matches your portal URL exactly (including trailing slash). After adding an IdP, the operator who added it stays signed in as the local administrator until their next sign-in.