On-premises installation (Model A)

This guide covers installing CloudSmith on a Windows Server 2025 management host using Hyper-V. The installer provisions a dedicated Ubuntu 24.04 LTS VM named cloudsmith-docker and runs all CloudSmith control-plane services inside it via Docker Compose.

Three delivery modes are available. All three produce an identical running state.

Prerequisites checklist

Complete all items before running the installer.

• Windows Server 2025 (Standard or Datacenter) installed and activated
• Hyper-V role installed: Install-WindowsFeature -Name Hyper-V -IncludeManagementTools -Restart
• PowerShell 7.4 or later: winget install Microsoft.PowerShell — required; the installer script declares #requires -Version 7.0 and will not run under Windows PowerShell 5.1. Launch the installer with pwsh -File Install-CloudSmith.ps1, not powershell.exe.
• At least 10 GB RAM available (run (Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB to confirm)
• At least 80 GB free disk space on the intended VHDX target drive
• If the management host is itself a Hyper-V VM: nested virtualization enabled on the parent host (see system-requirements.md) — required size on Azure: Standard_D4s_v3 or any size in the Dsv3 family. Dsv5 family does not currently expose nested virtualization for Windows guests.
• Port 443 inbound accessible from operator workstations (installer creates the firewall rule)
• Outbound HTTPS (443) to ghcr.io accessible from the management host (Online mode only)

Note — QEMU and ISO writer: The installer self-bootstraps qemu-img.exe (downloads QEMU for Windows silently if missing) and builds the cloud-init seed ISO via Windows in-box IMAPI2. No Windows ADK install is required. No manual QEMU install is required either; if it’s already on PATH the installer reuses it, otherwise it installs.

Sparse-VHDX safety: Hyper-V Generation 2 refuses to power on a VHDX file with the NTFS Sparse attribute (error 0xC03A001A). The installer handles this automatically by calling qemu-img convert -O vhdx -o subformat=dynamic and clearing the sparse flag with fsutil sparse setflag <path> 0 after conversion. If you convert images by hand, do the same.

Warning — nested virtualization: If nested virtualization is absent and the installer falls back to WSL2, the result is a lab/dev configuration that is not production-supported. Microsoft explicitly limits WSL2 Linux containers on Windows Server to development and testing use. Active regressions in WSL2 on Windows Server 2025 (microsoft/WSL issues #13416 and #13291) can cause containers to go down during normal operation. Do not use the WSL2 fallback for production workloads.

Online mode

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

Step 1 — Download the installer

# Open an elevated PowerShell 7 session on the management host
$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 — (Optional) Verify the installer script

# The SHA-256 manifest for each release is published on the GitHub Release page
# Download the manifest and compare
$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"

Note: Cosign-based signature verification of the installer is on the roadmap once the release pipeline ships signatures. Until then, SHA-256 integrity verification against the value published on the GitHub Release page is the available check.

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 performs the following steps automatically:

1. Checks prerequisites (Hyper-V role, RAM, disk space, nested virtualization).
2. Creates the Hyper-V internal switch cloudsmith-internal.
3. Downloads the Ubuntu 24.04 cloud image, creates a Generation 2 VM named cloudsmith-docker, and attaches the VHDX.
4. Configures the VM: 4 GB RAM (dynamic, max 8 GB), 2 vCPU, static IP, AutomaticStartAction Start, AutomaticStopAction ShutDown.
5. SSHs into the VM, installs Docker CE, and pulls the CloudSmith container images from ghcr.io/cloudsmith-cloud/.
6. Writes the Docker Compose file and starts the stack.
7. Configures 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

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

# Confirm all containers are running (requires SSH or Hyper-V Direct console)
# The installer installs a helper function:
Invoke-CloudSmithDiag

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

Bundled mode

Bundled mode packages the Ubuntu cloud image and CloudSmith container images inside the installer zip. Use this mode when the management host cannot reach ghcr.io or cloud-images.ubuntu.com at install time.

Step 1 — Download the bundle (from a connected machine)

$bundleUrl = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download/Install-CloudSmith-Bundled.zip'
Invoke-WebRequest -Uri $bundleUrl -OutFile 'Install-CloudSmith-Bundled.zip'

Step 2 — Verify the bundle

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

Note: Cosign blob signing for the bundle manifest is on the roadmap. When the signing pipeline ships, an additional cosign verify-blob step will confirm authenticity of the manifest itself. Until then, verify the SHA-256 hash matches the value published on the GitHub Release page.

Step 3 — Transfer to the management host

Transfer Install-CloudSmith-Bundled.zip and cloudsmith-bundle.sha256 to the management host by your standard secure file-transfer method (USB, SMB, SCP, etc.).

Step 4 — Extract and run

# On the management host (elevated PowerShell 7)
Expand-Archive -Path 'Install-CloudSmith-Bundled.zip' -DestinationPath 'C:\CloudSmithInstall'

& 'C:\CloudSmithInstall\Install-CloudSmith.ps1' -Mode Bundled

# Custom paths
& 'C:\CloudSmithInstall\Install-CloudSmith.ps1' -Mode Bundled `
    -VmIp '10.10.50.20' `
    -VhdxPath 'D:\Hyper-V\cloudsmith-docker.vhdx'

The install steps are identical to Online mode. No internet access is required after extraction.

Appliance mode

Appliance mode imports a pre-built, signed VHDX that ships with Ubuntu 24.04, Docker CE, and all CloudSmith container images already loaded. The portal is reachable approximately 3 minutes after import completes.

Step 1 — Download the appliance artifacts

# Download from a connected machine
$base = 'https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/latest/download'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.vhdx"         -OutFile 'cloudsmith-appliance.vhdx'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.sha256"       -OutFile 'cloudsmith-appliance.sha256'
Invoke-WebRequest -Uri "$base/cloudsmith-appliance.sha256.sig"   -OutFile 'cloudsmith-appliance.sha256.sig'
Invoke-WebRequest -Uri "$base/Import-CloudSmithAppliance.ps1"    -OutFile 'Import-CloudSmithAppliance.ps1'
Invoke-WebRequest -Uri "$base/cloudsmith-cosign.pub"             -OutFile 'cloudsmith-cosign.pub'

Step 2 — Verify integrity and authenticity

# Step 2a — Integrity: SHA-256 hash check (PowerShell native, no extra tooling required)
$manifest = Get-Content 'cloudsmith-appliance.sha256'
$expected = ($manifest -split '\s+')[0]
$actual   = (Get-FileHash -Path 'cloudsmith-appliance.vhdx' -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "VHDX hash mismatch — do not import" }
Write-Host "Integrity verified: $actual"

# Step 2b — Authenticity: cosign signature verification of the manifest
# Requires cosign to be available. The Import-CloudSmithAppliance.ps1 script
# performs this step automatically. To run manually:
cosign verify-blob `
    --key 'cloudsmith-cosign.pub' `
    --signature 'cloudsmith-appliance.sha256.sig' `
    'cloudsmith-appliance.sha256'

Note: The cosign signing workflow described here (.sha256.sig file and cloudsmith-cosign.pub key) is the planned mechanism for Appliance artifacts. The exact signing workflow may be refined when the signing pipeline ships.

Warning: Do not import the VHDX before completing both verification steps. A tampered or corrupted VHDX that passes only the hash check (but not the signature) indicates the manifest itself may have been replaced. Treat any verification failure as a security incident.

Step 3 — Transfer to the management host

Transfer all five files to the management host. The VHDX (~3–4 GB) is the largest file; plan transfer time accordingly.

Step 4 — Import and start

# On the management host (elevated PowerShell 7)
& '.\Import-CloudSmithAppliance.ps1'

# With custom paths
& '.\Import-CloudSmithAppliance.ps1' `
    -VhdxSourcePath 'D:\Transfer\cloudsmith-appliance.vhdx' `
    -VhdxDestPath 'D:\Hyper-V\cloudsmith-docker.vhdx' `
    -VmIp '10.10.50.20'

Import-CloudSmithAppliance.ps1 performs verification automatically (steps 2a and 2b above), copies the VHDX to the destination, creates and configures the cloudsmith-docker VM, and starts it. No internet access is required.

Step 5 — Wait for first boot

# Poll until the portal responds (typically 2–4 minutes)
$ip = '192.168.100.10'   # or your --VmIp value
do {
    Start-Sleep -Seconds 10
    $result = Test-NetConnection -ComputerName $ip -Port 443 -InformationLevel Quiet -WarningAction SilentlyContinue
    Write-Host "Waiting for portal... $(Get-Date -Format 'HH:mm:ss')"
} until ($result)
Write-Host "Portal is up. Navigate to https://$ip"

Post-installation

First login

Navigate to https://<management-host-fqdn> (or the VM’s static IP if DNS is not configured). You will be redirected to Keycloak for authentication.

Default credentials:

Change the admin password immediately after first login. See the Getting started guide for the full first-run walkthrough.

Verification commands

# Confirm VM is running and auto-start is configured
Get-VM -Name 'cloudsmith-docker' | Select-Object Name, State, AutomaticStartAction

# Confirm Docker Compose stack inside the VM
# SSH into the VM (the installer configures SSH key-based auth)
ssh cloudsmith@192.168.100.10 'docker compose -f /opt/cloudsmith/docker-compose.yml ps'

Expected: six containers running — cloudsmith-api, cloudsmith-portal, cloudsmith-postgres, cloudsmith-prometheus, cloudsmith-loki, cloudsmith-otel.

Backup

The VHDX file at C:\ProgramData\CloudSmith\cloudsmith-docker.vhdx (or your custom --vhdx-path) contains the entire CloudSmith data volume. Include this file in your backup strategy.

Recommended approach for consistent backups:

# Checkpoint the VM, back up the VHDX, then delete the checkpoint
$vmName = 'cloudsmith-docker'
$snap   = Checkpoint-VM -Name $vmName -SnapshotName 'pre-backup' -Passthru
Copy-Item 'C:\ProgramData\CloudSmith\cloudsmith-docker.vhdx' `
          "D:\Backups\cloudsmith-docker-$(Get-Date -Format 'yyyyMMdd').vhdx"
Remove-VMSnapshot -VMName $vmName -Name 'pre-backup'

Alternatively, use pg_dump inside the VM for database-only backups between full VHDX snapshots.

Updating CloudSmith

# On the management host (elevated PowerShell 7)
Update-CloudSmith

Update-CloudSmith pulls new container images from ghcr.io/cloudsmith-cloud/ inside the VM and performs a rolling restart of the Docker Compose stack. No VM reboot is required for standard updates. A progress indicator shows each container as it restarts.

For Appliance mode, the standard update path pulls images in-place. Full VHDX replacement is not required for incremental version updates.

Uninstalling CloudSmith

# Removes the VM, VHDX, Hyper-V switch, and Windows Firewall rule
# Data in the VHDX is permanently deleted
Uninstall-CloudSmith

# Preserve the VHDX (does everything except delete the VHDX file)
Uninstall-CloudSmith -PreserveVhdx

WSL2 fallback (lab/dev only — not production-supported)

If the management host does not support Hyper-V (for example, a constrained lab environment with no nested virtualization support), the installer detects this and offers a WSL2 fallback mode.

WARNING: Hyper-V nested virtualization is not available on this host.
Falling back to WSL2 mode. THIS CONFIGURATION IS NOT PRODUCTION-SUPPORTED.
WSL2 Linux containers on Windows Server are limited to development and testing
by Microsoft's support policy. Active WSL2 regressions on Windows Server 2025
(microsoft/WSL #13416, #13291) may cause containers to stop unexpectedly.

Accept the prompt only if this host is explicitly a lab or development environment. Do not accept for production cluster management.

The WSL2 fallback produces the same six-container stack but managed by a Task Scheduler + WSL2 startup chain rather than the Hyper-V VM auto-start path.