Install CloudSmith — Online mode

Online mode downloads the Ubuntu 24.04 cloud image and all CloudSmith container images from the internet at install time. Use this mode when the management host has unrestricted outbound HTTPS access to ghcr.io and cloud-images.ubuntu.com.

Prerequisites

  • Windows Server 2022 or 2025 (Standard or Datacenter) with Hyper-V role installed
  • PowerShell 7.4 or later (pwsh --version to confirm)
  • 10 GB RAM available on the management host
  • 80 GB free disk space on the target VHDX drive
  • Outbound HTTPS (443) to ghcr.io and cloud-images.ubuntu.com
  • Port 443 inbound from operator workstations (installer creates the firewall rule)

If the management host is itself a Hyper-V VM, nested virtualization must be enabled on the parent host before running the installer:

# Run on the parent Hyper-V host
Set-VMProcessor -VMName '<management-vm-name>' -ExposeVirtualizationExtensions $true

Step 1 — Download the installer

Open an elevated PowerShell 7 session on the management host and run:

$installerUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/Install-CloudSmith.ps1'
$dest = "$env:TEMP\Install-CloudSmith.ps1"
Invoke-WebRequest -Uri $installerUrl -OutFile $dest

Step 2 — Verify the installer

$manifestUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/cloudsmith-online.sha256'
$manifest    = Invoke-WebRequest -Uri $manifestUrl -UseBasicParsing | Select-Object -ExpandProperty Content
$expected    = ($manifest -split '\s+')[0]
$actual      = (Get-FileHash -Path $dest -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "Hash mismatch — do not proceed" }
Write-Host "Hash verified: $actual"

Step 3 — Run the installer

# Default install: VM static IP 192.168.100.10, VHDX at C:\ProgramData\CloudSmith\
& $dest

# Custom static IP and VHDX path
& $dest -VmIp '10.10.50.20' -VhdxPath 'D:\Hyper-V\cloudsmith-docker.vhdx'

The installer runs the following steps automatically:

  1. Checks prerequisites — Hyper-V role, available RAM, disk space, nested virtualization.
  2. Creates the Hyper-V internal switch cloudsmith-internal.
  3. Downloads the Ubuntu 24.04 cloud image and creates a Generation 2 VM named cloudsmith-docker.
  4. Configures the VM: 4 GB RAM (dynamic, max 8 GB), 2 vCPU, static IP, auto-start on host boot.
  5. SSHs into the VM, installs Docker CE, and pulls CloudSmith container images from ghcr.io/cloudsmith-cloud/.
  6. Writes the Docker Compose file and starts the stack.
  7. Creates a Windows Firewall inbound rule forwarding port 443 to the VM’s static IP.

Installation takes 5–15 minutes depending on network speed. A progress bar tracks each phase.

Step 4 — Verify the install

# Confirm the VM is running
Get-VM -Name 'cloudsmith-docker' | Select-Object Name, State, Status

# Run the CloudSmith diagnostic helper (installed by the installer)
Invoke-CloudSmithDiag

Expected output: all six containers showing status Up — cloudsmith-api, cloudsmith-portal, cloudsmith-postgres, cloudsmith-prometheus, cloudsmith-loki, cloudsmith-otel.

Step 5 — Open the portal

Navigate to https://<management-host-fqdn> (or the static IP you configured, default https://192.168.100.10). On first access, CloudSmith redirects you to the first-run setup wizard.

See Getting started — first-run walkthrough for the complete post-install sequence including wizard completion, cluster registration, and Relay deployment.

Installer parameters

Parameter Default Description
-VmIp 192.168.100.10 Static IP address for the CloudSmith VM
-VhdxPath C:\ProgramData\CloudSmith\cloudsmith-docker.vhdx Destination path for the VHDX file
-VmName cloudsmith-docker Name of the Hyper-V VM
-VmMemoryGB 4 Startup RAM for the VM (dynamic memory; max 8 GB)
-VmCpuCount 2 vCPU count for the VM
-SwitchName cloudsmith-internal Name of the Hyper-V internal switch

Troubleshooting

Installer exits with “Hyper-V is not available”. Confirm the Hyper-V role is installed: Get-WindowsFeature -Name Hyper-V. If the management host is a VM, confirm nested virtualization is enabled on the parent.

Installer exits with “Insufficient RAM”. The installer requires at least 10 GB of physical RAM to be present. Run (Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB to see available RAM.

Container images fail to pull. Confirm outbound HTTPS 443 to ghcr.io is allowed from the management host. If a proxy is required, set HTTPS_PROXY in the environment before running the installer.

The VM is running but the portal is not reachable. Confirm the Windows Firewall rule exists: Get-NetFirewallRule -DisplayName 'CloudSmith Portal'. If absent, run Invoke-CloudSmithDiag -Fix to recreate it.