fix(installer): stop it lying, stop it leaking, and make it findable
Nine fixes from a review of the installer against its actual audience: DT leads at sister sites who are not Windows, IIS or Python specialists and who will lean on an AI assistant to get through it. TRUTHFULNESS. The preflight was advisory - an operator read 'IIS is not installed', pressed Next, answered five more pages and the install died partway through with Python already on the box. The results page now blocks while anything is failing, repaints on every run instead of latching after the first, and offers 'Check again' so a fixed problem does not mean starting over. On failure the wizard said 'Nothing was left running', which is false in every path because the stages run with -OnFailure never: it now says the server is part-configured, that re-running is safe, and how to remove it. The final page no longer reads 'ShopDB-Flask is ready' after a failed install. SECRETS. The generated MySQL root password went to Write-Host in a process the wizard runs hidden - so nobody saw it - and stdout is forwarded into the setup log operators are told to send to support, so it was permanently recorded for everyone who did not need it. It now goes to an ACL'd file. Database dumps, which contain every user password hash, landed in a ProgramData directory readable by every user on the box; the directory is now locked at creation. UPGRADES ON REMOTE-DATABASE SITES. mysqldump was looked for only under local MySQL install paths, so a site whose database is on another host silently skipped every pre-upgrade backup - after stage 2 had already stopped the pool and replaced the tree. Find-MysqlTool now prefers a client shipped in the bundle, stage 2 stages it onto the server, preflight reports when it is missing, and mysqlclient\ is an optional locked payload. UNINSTALL. A subpath install is an IIS Application, not a site; removing only the site left the application pointing at a deleted directory, so the parent site - at West Jefferson, the live classic ASP - served 503 on that path forever while Add/Remove Programs reported success. Uninstall now reads MOUNT_PATH and removes the application. The firewall rule was created as "$SiteName $SitePort" and removed as the literal 'ShopDB-Flask 8090', which matches nothing. DAY-2 TOOLING. Every shortcut now passes -AppRoot and -SitePort, and the console forwards them through its own elevation and 32-bit relaunches instead of discarding them - a non-default directory or port made it report a healthy site as broken, from a shortcut the installer wrote. 'Open ShopDB-Flask' resolved to a hardcoded localhost:8090 that was wrong for every subpath install; it now asks the console, which reads the address the installer recorded, and no longer demands administrator to open a browser. SMOKE TEST. The parent-site port lookup filtered for an http binding and defaulted to 80, so an https-only parent site failed a working install with a red dialog. DOCS AND /api/docs. The installer was invisible: nothing in docs/, README.md or CLAUDE.md mentioned it, so a DT lead or their assistant landed on the manual IIS runbook and hand-built the very server the installer then refuses to upgrade. docs/INSTALL-WINDOWS.md and docs/OPERATE-WINDOWS.md are now the canonical route, the two manual runbooks are bannered as reference-only, README and CLAUDE.md route by target, and llms.txt tells an assistant which document to follow and to ask for 'check -Json' before diagnosing. Both ship on the server, along with openapi.json and llms.txt - without those the self-hosted /api/docs was broken on every installed box, which matters most to the sites least able to debug it. Stage 5 now checks it actually serves. shopdb-admin.ps1 gains 'check -Json': one structured, secret-free block covering version, publishing method, IIS state, HTTP reachability, database, Python version, plugins and errors. That is the cheapest useful answer to 'the operator will ask an LLM' - it works with no infrastructure, which a install-time MCP server could not.
This commit is contained in:
cproudlock
@@ -25,6 +25,11 @@ param(
|
||||
'check','sessions','plugins','add-plugin','verify','uninstall')]
|
||||
[string] $Command = 'menu',
|
||||
[string] $Path = '',
|
||||
# Machine-readable output for 'check'. The people running this are expected to
|
||||
# ask an AI assistant for help, and pasting a screenshot of a console into a
|
||||
# chat window loses most of what matters. One structured blob they can paste
|
||||
# gives the assistant real state to reason about instead of guesses.
|
||||
[switch] $Json,
|
||||
[string] $AppRoot = 'C:\shopdb-flask',
|
||||
[string] $SiteName = 'shopdb-flask',
|
||||
[string] $AppPool = 'shopdbflask',
|
||||
@@ -46,13 +51,27 @@ $AppCmd = Join-Path $env:windir 'System32\inetsrv\appcmd.exe'
|
||||
# than fix every launcher, relaunch under the native PowerShell. 'Sysnative' is
|
||||
# the alias that lets a 32-bit process reach the real System32, and it exists
|
||||
# ONLY for 32-bit processes - hence the guard.
|
||||
|
||||
# Every relaunch below must carry the ORIGINAL arguments through. They used to be
|
||||
# dropped, so a console started from the Start Menu with -AppRoot D:\shopdb
|
||||
# relaunched itself with the C:\shopdb-flask default and reported a healthy
|
||||
# install as missing - and the operator had done nothing wrong.
|
||||
function Get-ForwardedArgs {
|
||||
$forward = @('-NoProfile', '-ExecutionPolicy', 'Bypass',
|
||||
'-File', ('"' + $PSCommandPath + '"'), $Command)
|
||||
if ($Path) { $forward += @('-Path', ('"' + $Path + '"')) }
|
||||
if ($AppRoot) { $forward += @('-AppRoot', ('"' + $AppRoot + '"')) }
|
||||
if ($SiteName) { $forward += @('-SiteName', ('"' + $SiteName + '"')) }
|
||||
if ($AppPool) { $forward += @('-AppPool', ('"' + $AppPool + '"')) }
|
||||
if ($SitePort) { $forward += @('-SitePort', $SitePort) }
|
||||
if ($Json) { $forward += '-Json' }
|
||||
return $forward
|
||||
}
|
||||
|
||||
if ([Environment]::Is64BitOperatingSystem -and -not [Environment]::Is64BitProcess) {
|
||||
$native = Join-Path $env:windir 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'
|
||||
if (Test-Path $native) {
|
||||
$relaunch = @('-NoProfile', '-ExecutionPolicy', 'Bypass',
|
||||
'-File', ('"' + $PSCommandPath + '"'), $Command)
|
||||
if ($Path) { $relaunch += @('-Path', ('"' + $Path + '"')) }
|
||||
Start-Process -FilePath $native -ArgumentList $relaunch -Wait -NoNewWindow
|
||||
Start-Process -FilePath $native -ArgumentList (Get-ForwardedArgs) -Wait -NoNewWindow
|
||||
return
|
||||
}
|
||||
}
|
||||
@@ -65,13 +84,14 @@ if ([Environment]::Is64BitOperatingSystem -and -not [Environment]::Is64BitProces
|
||||
# instead of reporting a false state.
|
||||
$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
|
||||
$principal = New-Object Security.Principal.WindowsPrincipal($identity)
|
||||
if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
|
||||
# 'open' just launches a browser. Prompting for administrator to do that trains
|
||||
# people to click through UAC, and the Start Menu shortcut uses this command.
|
||||
if ($Command -ne 'open' -and
|
||||
-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
|
||||
Write-Host ''
|
||||
Write-Host ' Administrator rights are needed to read IIS state.' -ForegroundColor Yellow
|
||||
Write-Host ' Re-launching elevated - approve the prompt.' -ForegroundColor Yellow
|
||||
$argList = @('-NoExit', '-NoProfile', '-ExecutionPolicy', 'Bypass',
|
||||
'-File', ('"' + $PSCommandPath + '"'), $Command)
|
||||
if ($Path) { $argList += @('-Path', ('"' + $Path + '"')) }
|
||||
$argList = @('-NoExit') + (Get-ForwardedArgs)
|
||||
try {
|
||||
Start-Process -FilePath 'powershell.exe' -ArgumentList $argList -Verb RunAs | Out-Null
|
||||
} catch {
|
||||
@@ -326,6 +346,14 @@ function Show-Logs {
|
||||
}
|
||||
|
||||
function Open-Site {
|
||||
# The installer records the address it actually published at. Prefer it: this
|
||||
# command runs unelevated, and .env is ACL'd, so working the address out from
|
||||
# MOUNT_PATH and IIS may not be possible from here.
|
||||
$recorded = Join-Path $AppRoot '.installed-url'
|
||||
if (Test-Path $recorded) {
|
||||
$u = (Get-Content $recorded -TotalCount 1).Trim()
|
||||
if ($u) { Start-Process $u; Say " opened $u" 'Green'; return }
|
||||
}
|
||||
$deploy = Get-Deployment
|
||||
if ($deploy.Subpath) {
|
||||
if ($deploy.Port -eq 80) { $u = "http://{0}/{1}/login" -f $env:COMPUTERNAME, $deploy.Alias }
|
||||
@@ -334,7 +362,7 @@ function Open-Site {
|
||||
$u = "http://{0}:{1}/login" -f $env:COMPUTERNAME, $SitePort
|
||||
}
|
||||
Start-Process $u
|
||||
Say ' opened in your browser' 'Green'
|
||||
Say " opened $u" 'Green'
|
||||
}
|
||||
|
||||
function Backup-Db {
|
||||
@@ -385,7 +413,90 @@ function Backup-Db {
|
||||
}
|
||||
}
|
||||
|
||||
function Get-CheckState {
|
||||
<#
|
||||
Everything an outside reader needs to reason about this server, gathered
|
||||
without changing anything. Secrets are NEVER included: the database password
|
||||
lives in DATABASE_URL and this reports the host, port, name and user only.
|
||||
#>
|
||||
$deploy = Get-Deployment
|
||||
$db = Get-DbParts
|
||||
$state = [ordered]@{
|
||||
collected = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
|
||||
computername = $env:COMPUTERNAME
|
||||
approot = $AppRoot
|
||||
installed = (Test-Path (Join-Path $AppRoot 'shopdb\__init__.py'))
|
||||
version = ''
|
||||
publishedas = if ($deploy.Subpath) { "subpath /$($deploy.Alias) under '$($deploy.Parent)'" } else { "own site '$SiteName' on port $SitePort" }
|
||||
baseurl = $deploy.BaseUrl
|
||||
apppool = 'unknown'
|
||||
poolstate = 'unknown'
|
||||
sitestate = 'unknown'
|
||||
responding = $false
|
||||
httpstatus = 0
|
||||
database = $null
|
||||
pythonversion = ''
|
||||
plugins = @()
|
||||
sbomcomponents = 0
|
||||
errors = @()
|
||||
}
|
||||
foreach ($pair in @(@('version', '.installed-version'))) {
|
||||
$f = Join-Path $AppRoot $pair[1]
|
||||
if (Test-Path $f) { $state[$pair[0]] = (Get-Content $f -TotalCount 1).Trim() }
|
||||
}
|
||||
$state.apppool = $AppPool
|
||||
try {
|
||||
Import-Module WebAdministration -ErrorAction Stop
|
||||
if (Test-Path "IIS:\AppPools\$AppPool") { $state.poolstate = (Get-Item "IIS:\AppPools\$AppPool").State.ToString() }
|
||||
if ($deploy.Subpath) {
|
||||
$app = Get-WebApplication -Site $deploy.Parent -Name $deploy.Alias -ErrorAction SilentlyContinue
|
||||
$state.sitestate = if ($app) { 'application present' } else { 'application MISSING' }
|
||||
} else {
|
||||
$s = Get-Website -Name $SiteName -ErrorAction SilentlyContinue
|
||||
$state.sitestate = if ($s) { $s.State.ToString() } else { 'site MISSING' }
|
||||
}
|
||||
} catch { $state.errors += "IIS: $($_.Exception.Message)" }
|
||||
|
||||
try {
|
||||
$r = Invoke-WebRequest -Uri ($deploy.BaseUrl + '/') -UseBasicParsing -TimeoutSec 20
|
||||
$state.responding = $true
|
||||
$state.httpstatus = [int] $r.StatusCode
|
||||
} catch { $state.errors += "HTTP: $($_.Exception.Message)" }
|
||||
|
||||
if ($db) {
|
||||
$state.database = [ordered]@{ host = $db.Host; port = $db.Port; name = $db.Name; user = $db.User; reachable = $false }
|
||||
$mysql = Find-MysqlClient
|
||||
if ($mysql) {
|
||||
$q = "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='$($db.Name)';"
|
||||
$n = $q | & $mysql "-u$($db.User)" "-p$($db.Pass)" "-h$($db.Host)" "-P$($db.Port)" -N 2>$null
|
||||
if ($LASTEXITCODE -eq 0) { $state.database.reachable = $true; $state.database.tables = [int] $n }
|
||||
} else { $state.errors += 'no mysql client found, database not probed' }
|
||||
} else { $state.errors += 'no .env found' }
|
||||
|
||||
$py = Join-Path $AppRoot 'venv\Scripts\python.exe'
|
||||
if (Test-Path $py) { $state.pythonversion = (& $py -c "import sys; print('%d.%d.%d' % sys.version_info[:3])" 2>$null | Select-Object -First 1) }
|
||||
|
||||
$dir = Join-Path $AppRoot 'plugins'
|
||||
if (Test-Path $dir) {
|
||||
$state.plugins = @(Get-ChildItem $dir -Directory -EA SilentlyContinue |
|
||||
Where-Object { Test-Path (Join-Path $_.FullName 'manifest.json') } |
|
||||
Select-Object -ExpandProperty Name)
|
||||
}
|
||||
$sbom = Join-Path $AppRoot 'sbom.cdx.json'
|
||||
if (Test-Path $sbom) {
|
||||
try { $state.sbomcomponents = (Get-Content $sbom -Raw | ConvertFrom-Json).components.Count } catch { }
|
||||
}
|
||||
return $state
|
||||
}
|
||||
|
||||
function Invoke-Check {
|
||||
if ($Json) {
|
||||
# ONLY the JSON goes to stdout, so it can be redirected to a file or piped
|
||||
# without a banner in the middle of the document.
|
||||
Get-CheckState | ConvertTo-Json -Depth 6
|
||||
return
|
||||
}
|
||||
|
||||
Head 'Health check'
|
||||
$flask = Join-Path $AppRoot 'venv\Scripts\flask.exe'
|
||||
if (-not (Test-Path $flask)) { Say ' application not installed' 'Red'; return }
|
||||
@@ -393,6 +504,9 @@ function Invoke-Check {
|
||||
$env:FLASK_APP = 'shopdb'
|
||||
try { & $flask db-utils preflight 2>&1 | ForEach-Object { Say " $_" } }
|
||||
finally { Pop-Location }
|
||||
Say ''
|
||||
Say ' For help from an AI assistant, paste the output of:' 'DarkGray'
|
||||
Say ' shopdb-admin.ps1 check -Json' 'White'
|
||||
}
|
||||
|
||||
function Show-Sessions {
|
||||
|
||||
Reference in New Issue
Block a user