Installer validation matrix¶
This document summarizes the checks and component effects that the Windows Native Service installer (scripts/windows/service/install.ps1 + Common.ps1) actually performs.
Checks that are not in the script are not invented.
Evidence status:
| Platform | Live E2E |
|---|---|
| Windows Native Service | PASS (Windows lab, August 2026) — details: Windows Service E2E |
| Ubuntu systemd | NOT E2E VALIDATED |
| Linux / Windows Docker | NOT E2E VALIDATED |
Related: Test strategy, Update and rollback, Windows service installation.
Exit codes (summary)¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Administrator required |
| 2 | Invalid environment |
| 3 | Prerequisite |
| 4 | Dirty repo / git |
| 5 | Dependency download |
| 6 | Vet/test |
| 7 | Build |
| 8 | Application check |
| 9 | Backup |
| 10 | Migration |
| 11 | Service update |
| 12 | Firewall |
| 13 | Health |
| 14 | Rollback failed |
| 15 | Port conflict (EXIT_PORT_CONFLICT / Linux EXIT_PORT) |
| 16 | Docker N/A |
| 17 | systemd N/A |
Validation steps (Windows install)¶
| Step | Validation | How | Success Criterion | Failure Behavior | Exit Code | Mutates System? | Rollback Required? | Windows | Linux | Docker |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Administrator | Assert-Administrator |
Elevated token | Abort | 1 | No | No | Yes | root (1) | Varies |
| 2 | OS / architecture | Assert-WindowsAmd64 |
Windows AMD64 | Abort | 3 | No | No | Yes | arch check | Host OS |
| 3 | Repository root | Get-RepoRoot / go.mod |
Repo found | Abort | 3 | No | No | Yes | Yes | Yes |
| 4 | Env existence | Assert-EnvFileExists |
.env present |
Abort | 2 | No | No | Yes | Yes | Yes |
| 5 | Configuration readable | Port/env read | Valid HTTP_PORT etc. |
Abort | 2 | No | No | Yes | Yes | Yes |
| 6 | Git | Ensure-GitAndGo |
git on PATH |
Abort or winget install | 3 | Maybe (winget) | No | Yes | Yes | Optional |
| 7 | Go | Ensure-GitAndGo |
go on PATH |
Abort or winget install | 3 | Maybe (winget) | No | Yes | Yes | Image build |
| 8 | Runtime state | Path inspection | present/absent report | Continue | — | No | No | Yes | Yes | Compose state |
| 9 | Service state | Get-Service |
Scenario selection | Continue | — | No | No | Yes | systemd | containers |
| 10 | Scenario | Get-IQVInstallScenario |
CleanInstall / PreservedRuntimeReinstall / ServiceRepair | Continue | — | No | No | Yes | Analog | Analog |
| 11 | MongoDB service | Assert-MongoServiceAndPort |
Service Running | Abort | 3 | No | No | Yes | External check | External/bundled |
| 12 | MongoDB port | TCP 27017 Listen | Listening | Abort | 3 | No | No | Yes | Yes | Network |
| 13 | HTTP port ownership | Assert-IQVHttpPortForInstall |
Free or own SCM PID (ServiceRepair) | Abort on foreign | 15 | No | No | Yes | MainPID | Managed mapping |
| 14 | Dependencies | go mod download / verify |
Exit 0 | Abort | 5 | Module cache | No | Yes | Yes | Build |
| 15 | Vet | go vet ./... |
Exit 0 | Abort | 6 | No | No | Yes | Yes | Optional |
| 16 | Tests | go test ./... -count=1 (unless -SkipTests) |
Exit 0 | Abort | 6 | No | No | Yes | Yes | Optional |
| 17 | Build | go build |
Binary produced | Abort | 7 | Temp binary | No | Yes | Yes | Image |
| 18 | Application check | Binary check |
Exit 0 | Abort | 8 | No | No | Yes | Yes | Health later |
| 19 | Backup | Runtime backup (if present) | Backup dir | Abort | 9 | Yes | Snapshot | Yes | Yes | Image tag |
| 20 | Stop / port release | Stop service; wait port | Port released | Fail path | 11/15 | Yes | Yes (txn) | Yes | Yes | compose |
| 21 | Binary deploy | Copy to runtime | Binary in place | Txn fail → recover | 11 | Yes | Yes | Yes | Yes | recreate |
| 22 | Config preserve/copy | Preserve default; copy on CleanInstall; -ReplaceRuntimeConfig |
Hash/policy | Txn fail → recover | 2/11 | Yes (CleanInstall) | Yes | Yes | preserve-if-exists | no silent .env overwrite |
| 23 | Migration | App migrate (unless skip) | Exit 0 | Abort; no DB rollback | 10 | Yes (DB) | No DB rollback | Yes | Yes | Yes |
| 24 | Service registration | service install CreateService/argv |
Registered | Txn recover | 11 | Yes | Yes | Yes | unit write | compose |
| 25 | Delayed start | Automatic Delayed | Configured | Txn recover | 11 | Yes | Yes | Yes | enable | restart policy |
| 26 | DB dependency | Depends on MongoDB service | Set | Txn recover | 11 | Yes | Yes | Yes | After= | depends_on |
| 27 | Recovery | 5s/10s/30s; reset 86400 | Set | Txn recover | 11 | Yes | Yes | Yes | Restart= | — |
| 28 | Firewall | Domain+Private rule (unless skip) | Rule present (idempotent) | Abort | 12 | Yes | Best-effort | Yes | Optional | Optional |
| 29 | Service start | Start-Service | Running | Txn recover | 11 | Yes | Yes | Yes | systemctl | up |
| 30 | Health | /health/live + /health/ready |
HTTP healthy | Fail → recover / exit 13 | 13 | No | Yes | Yes | Yes | Yes |
| 31 | Metadata | deployment metadata write | Written only on success path | Fail path does not mark success | 11 | Yes | Preserve failed state | Yes | Yes | Yes |
Linux/Docker columns are IMPLEMENTED behavior analogs; for live E2E they are NOT E2E VALIDATED.
Component: check / install / change¶
| Component | Checked | Installed Automatically | Modified | Preserved | Removed on Uninstall | Notes |
|---|---|---|---|---|---|---|
| Go | Yes | Yes via winget unless -SkipPrerequisiteInstall |
PATH may refresh | N/A | No | GoLang.Go |
| Git | Yes | Yes via winget unless -SkipPrerequisiteInstall |
PATH may refresh | N/A | No | Git.Git |
| MongoDB | Yes (service + port) | No — not auto-installed | No | Untouched | No | Must already be Running |
| Go modules | download/verify | Module cache | Cache | N/A | No | |
| Binary | After build | Deployed to runtime bin\ |
Replaced on deploy | Kept on safe uninstall | Only with -RemoveRuntime |
|
.env / runtime config |
Exists + validate | CleanInstall: copy source → runtime | Only CleanInstall or -ReplaceRuntimeConfig |
Default preserve (PreservedRuntimeReinstall / ServiceRepair / update) | Only with -RemoveRuntime |
Self-copy protected |
| Windows service | Present/absent | Create / repair | ImagePath/account/recovery | N/A | Yes (unregister) | No duplicate create |
| Firewall | Rule count / presence | Create if missing | Idempotent | N/A | Yes (rule removed) | Domain+Private |
| Backups | Directory | Created on mutate paths | New stamp on real update | Yes on safe uninstall | Only -RemoveRuntime |
|
| Logs | Directory | Created | Appended by app | Yes on safe uninstall | -RemoveLogs / -RemoveRuntime |
|
| Deployment metadata | Written on success | Created | Updated on success deploy | Yes on safe uninstall | -RemoveRuntime |
No secrets |
| MongoDB collections | Via migration | Migrations apply | Schema/data per migrate | Uninstall does not touch | No | No migration rollback |
| Docker | N/A (native path) | No | No | — | — | Separate deployment |
| systemd unit | N/A (Windows) | Linux path | Linux writes unit | — | Linux uninstall | NOT E2E VALIDATED |
Prerequisite note¶
- MongoDB is not auto-installed. The installer only verifies that the Windows service is Running and that TCP 27017 is listening; otherwise exit 3.
- Go / Git: If missing and
-SkipPrerequisiteInstallis not set, installation viawingetis attempted. With-SkipPrerequisiteInstall, missing tools → exit 3.
Live E2E note¶
Windows Native Service lab E2E results are documented as PASS in windows-service-e2e.md (45 items; reboot, NO-OP, ForceRedeploy, rollback exit 11, preserved reinstall, ServiceRepair port ownership, step counter 29/29).
Corresponding live scenarios for Linux systemd and Docker are NOT E2E VALIDATED: linux-systemd-e2e.md, docker-e2e.md, known-untested-scenarios.md.