Add GuruRMM Agent MSI installer (WiX 5) — Phase 1 MVP
Signed Windows installer using our Azure Trusted Signing pipeline. Phase 1 scope: installs signed agent to Program Files, creates ProgramData dir, Apps & Features entry with proper publisher, clean install + uninstall. Phase 2 deferred: service registration, MSI properties for site-code injection, agent install/uninstall custom actions, firewall rules. Verified end-to-end on Windows workstation: - wix build produces 1.16 MB MSI - sign.ps1 signs it against gururmm-public-trust cert profile - msiexec /qn installs silently, signature chain verifies on installed binary - msiexec /x uninstalls cleanly, retains ProgramData Tooling prerequisites documented in installer/README.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
97
projects/msp-tools/guru-rmm/installer/README.md
Normal file
97
projects/msp-tools/guru-rmm/installer/README.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# GuruRMM Agent MSI Installer
|
||||
|
||||
Signed Windows installer for the GuruRMM agent. Builds on Windows via WiX 5,
|
||||
signed with Azure Trusted Signing. Produces a `gururmm-agent-<version>.msi`
|
||||
suitable for double-click install, silent install via `msiexec /qn`, or GPO
|
||||
Software Installation deployment.
|
||||
|
||||
## Status
|
||||
|
||||
**Phase 1 (current):** MVP — installs binary to `C:\Program Files\GuruRMM\`,
|
||||
creates `C:\ProgramData\GuruRMM\` data directory, Apps & Features entry with
|
||||
proper publisher, clean silent install + uninstall.
|
||||
|
||||
**Phase 2 (planned):**
|
||||
|
||||
- `ServiceInstall` element to register the Windows service on install
|
||||
- MSI properties for `SITE_CODE`, `SERVER_URL`, `API_KEY` passed at install time
|
||||
- Custom actions to invoke the agent's native `install` / `uninstall` subcommands
|
||||
- Firewall rule registration (if the tunnel subscriber path requires inbound)
|
||||
- Start menu entry (optional; most customers don't need it for background agent)
|
||||
|
||||
## Prerequisites (build host)
|
||||
|
||||
- Windows 10 / 11 / Server 2019+ (WiX v5 is Windows-only per upstream)
|
||||
- .NET SDK 8 — `winget install --id Microsoft.DotNet.SDK.8 -e`
|
||||
- WiX v5 — `dotnet tool install --global wix --version 5.0.2`
|
||||
- Windows SDK signtool — typically already present if Visual Studio Build Tools
|
||||
or Windows SDK is installed
|
||||
- Azure Trusted Signing `sign.ps1` + dlib at `C:\tools\trusted-signing\`
|
||||
- `az login` active session with the `gururmm-build-signer` SP, or an
|
||||
interactive user with the `Artifact Signing Certificate Profile Signer`
|
||||
role on the `gururmm-public-trust` certificate profile
|
||||
|
||||
## Build
|
||||
|
||||
```powershell
|
||||
cd installer
|
||||
.\build-msi.ps1 -Version 0.6.1
|
||||
```
|
||||
|
||||
Defaults:
|
||||
- Downloads `gururmm-agent-windows-amd64-<version>.exe` from
|
||||
`https://rmm-api.azcomputerguru.com/downloads/`
|
||||
- Refuses to package an unsigned agent (verifies signature before packaging)
|
||||
- Signs the resulting MSI against the `gururmm-public-trust` cert profile
|
||||
- Emits `<msi>.sha256` alongside
|
||||
|
||||
Flags:
|
||||
- `-SkipSign` — build without signing (dev/test)
|
||||
- `-KeepSource` — don't delete `src/gururmm-agent.exe` after build
|
||||
- `-SourceUrl` — override download origin (e.g., for staging)
|
||||
|
||||
## Install
|
||||
|
||||
```powershell
|
||||
# Interactive (UAC prompt → "Verified publisher: Arizona Computer Guru LLC")
|
||||
.\gururmm-agent-0.6.1.msi
|
||||
|
||||
# Silent (no UI, return code 0 = success, writes verbose log)
|
||||
msiexec /i gururmm-agent-0.6.1.msi /qn /l*v install.log
|
||||
|
||||
# Silent with (future) site-code baking once Phase 2 custom actions land
|
||||
msiexec /i gururmm-agent-0.6.1.msi /qn SITE_CODE=xyz123 SERVER_URL=wss://rmm-api.example.com/ws /l*v install.log
|
||||
```
|
||||
|
||||
## Uninstall
|
||||
|
||||
```powershell
|
||||
# Via Apps & Features: "GuruRMM Agent" → Uninstall
|
||||
# Or silent:
|
||||
msiexec /x gururmm-agent-0.6.1.msi /qn
|
||||
|
||||
# By ProductCode if original MSI isn't handy:
|
||||
msiexec /x {PRODUCT-CODE-GUID-HERE} /qn
|
||||
```
|
||||
|
||||
Uninstall removes `C:\Program Files\GuruRMM\` contents but **preserves
|
||||
`C:\ProgramData\GuruRMM\`** (logs, config, device identity). Manually delete
|
||||
that directory if doing a full purge.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `gururmm.wxs` | WiX installer definition — canonical source |
|
||||
| `build-msi.ps1` | Build + sign wrapper |
|
||||
| `src/gururmm-agent.exe` | Downloaded signed agent at build time (gitignored) |
|
||||
| `gururmm-agent-*.msi` | Build output (gitignored) |
|
||||
| `gururmm-agent-*.wixpdb` | WiX debug symbols (gitignored) |
|
||||
| `install-test.log` | Install log from local smoke tests (gitignored) |
|
||||
|
||||
## UpgradeCode
|
||||
|
||||
The UpgradeCode `4c0aef59-9d08-4781-a3b4-a1c99b3b2e28` is the **permanent
|
||||
identity** of the GuruRMM agent product family. Never change it. All future
|
||||
versions must ship with this same UpgradeCode so MSI upgrades work
|
||||
automatically via `msiexec /i newer.msi`.
|
||||
Reference in New Issue
Block a user