Mike Swanson
148ac75a25
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>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# 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`.
|