ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(installer): stop it lying, stop it leaking, and make it findable
Some checks failed
CI / backend (push) Failing after 7s
Details
CI / naming (push) Successful in 2s
Details
CI / frontend (push) Successful in 9s
Details
CI / migrations-mysql (push) Failing after 7s
Details

Browse Source 
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
2026-08-03 14:39:38 -04:00
parent e58f376643
commit aea2905de0
17 changed files with 1004 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/BACKUP-RESTORE.md
View File

@@ -142,8 +142,40 @@ version both are no-ops.
- `curl -s -X POST -H "Content-Type: application/json" -d '{}' http://localhost:5001/api/auth/login | jq .`
should return a `VALIDATION_ERROR`, not a 500.
## Windows sites (installer-built)
On a server installed from the Windows installer, everything above is wrapped by
the operator console. Do not run mysqldump by hand:
```powershell
cd C:\shopdb-flask
.\shopdb-admin.ps1 backup # C:\ProgramData\ShopDB-Flask\backups
.\shopdb-admin.ps1 backup D:\backups
```
The dump is verified complete before it is reported as good; a truncated one is
deleted rather than left to be discovered when it is needed. An upgrade takes its
own backup automatically before touching the schema, and restores from it if a
migration fails.
Two Windows-specific notes:
- The backup directory is locked to Administrators and SYSTEM, because a dump
contains every row including user password hashes. Keep it that way.
- `mysqldump` must be present. It ships with the bundled-database option; a site
using a remote MySQL needs `mysqlclient\` in its installer bundle, or the
pre-upgrade backup is skipped. `shopdb-admin.ps1 check` reports this.
Restoring is the standard `mysql < dump.sql`, then
`.\shopdb-admin.ps1 restart`. Also restore `C:\shopdb-flask\instance\` if you are
rebuilding a server - it holds uploaded branding and map blueprints, which the
database does not.
See [OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
## See also
- [DEPLOY.md](DEPLOY.md) - first-time deploy
- [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) - Windows Server install
- [UPGRADE.md](UPGRADE.md) - upgrade procedure (back up first)
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys

8
docs/DEPLOY-WINDOWS-IIS.md
View File

@@ -1,5 +1,13 @@
# Deploy shopdb-flask to Windows IIS (MySQL 5.6)
> **Not the route for a new site.** Sister sites install from the Windows
> installer — one `.exe`, no manual IIS work: **[INSTALL-WINDOWS.md](INSTALL-WINDOWS.md)**.
>
> This is the **manual** procedure for the West Jefferson server, which was built
> by hand against its existing MySQL 5.6 and predates the installer. Keep it for
> that box.
Runbook for standing up a single-site instance on the production Windows Server
that already runs the classic ASP shopdb, using IIS + HttpPlatformHandler +
waitress, against the existing MySQL 5.6. This is the test-instance path; keep

8
docs/INSTALL-WINDOWS-IIS.md
View File

@@ -1,5 +1,13 @@
# ShopDB - Windows + IIS install runbook
> **Not the route for a new site.** Sister sites install from the Windows
> installer — one `.exe`, no manual IIS work: **[INSTALL-WINDOWS.md](INSTALL-WINDOWS.md)**.
>
> This document is the **manual** procedure, kept for reference and for
> hand-built servers that predate the installer. Note that the installer will not
> adopt a server built this way without `-AdoptExisting`, on purpose.
A step-by-step, **tested** install for a new site on Windows Server / Windows 11
with IIS in front of the Flask app (HttpPlatformHandler -> waitress), backed by
MySQL. This runbook was validated end to end on a win11 + IIS + MySQL 5.6 box.

201
docs/INSTALL-WINDOWS.md Normal file
View File

@@ -0,0 +1,201 @@
# Install ShopDB-Flask on Windows Server
**This is the route for a new site.** You run one `.exe`, answer a few questions,
and get a working application. Nothing here needs an internet connection, and you
do not need to know IIS, Python or MySQL.
If you are looking after an existing hand-built server, see
[DEPLOY-WINDOWS-IIS.md](DEPLOY-WINDOWS-IIS.md) instead — that is the manual
procedure, and the installer will not adopt a server it did not build.
---
## Before you start
You need **four things**. The installer supplies everything else.
| | What | How to check |
|---|---|---|
| 1 | Windows Server 2019 or newer | `winver` |
| 2 | The **IIS Web Server role** installed | Server Manager → Manage → Add Roles → Web Server (IIS). Or run the PowerShell below. |
| 3 | Administrator rights on the box | Right-click PowerShell → "Run as administrator" works |
| 4 | A decision about the database — see [Which database?](#which-database) | — |
Installing IIS, if it is missing (this needs no internet):
```powershell
Install-WindowsFeature -Name Web-Server -IncludeManagementTools
```
The installer **checks all of this before it changes anything**, and it will not
let you continue until the check passes. You do not have to get it right first
time.
### Which database?
Two options. Pick before you start, because they ask different questions.
- **Use the bundled MySQL** — the installer puts MySQL 8.0 on this server and
creates the database for you. Choose this when the server has no database
today. Simplest option, nothing to arrange in advance.
- **Use an existing MySQL** — the database already exists somewhere, and you have
a hostname, a database name, a username and a password for it. Choose this if
your site already runs MySQL, or a DBA looks after it.
If you are unsure: if nobody has given you database credentials, you want the
bundled option.
---
## Installing
1. Copy the installer `.exe` onto the server. It is one file and needs no
network.
2. **Right-click it → Run as administrator.** Without this it cannot configure
IIS, and it will tell you so.
3. Work through the wizard. The pages are:
| Page | What it wants | If unsure |
|---|---|---|
| **Server check** | Nothing — it reports what it found | Fix anything red, then "Check again". You cannot continue while something is red, and nothing has been changed yet. |
| **Features** | Which parts of the product this site uses | The defaults are fine. You can add more later; removing needs a new installer. |
| **Database** | Bundled or existing — see above | Bundled |
| **Database details** | Host, port, name, user, password | Only asked for the existing-database option |
| **Address** | How people reach the site | See [Own address or subpath?](#own-address-or-subpath) |
| **Client addresses** | Whether a proxy sits in front | See [Client addresses](#client-addresses) |
| **Location** | Where to install | `C:\shopdb-flask` is fine |
4. The install takes a few minutes. Most of it is Python and the database schema.
5. At the end you get the address to open. **Write it down** — it is also on the
Start Menu as "Open ShopDB-Flask".
### Own address or subpath?
- **Its own address** — `http://yourserver:8090/`. Choose this on a server that
is not already running a website. Simplest.
- **Under this server's existing address** — `http://yourserver/shopdb/`. Choose
this when the server already serves something else and you do not want a second
port or a new DNS name. This is what West Jefferson uses.
You cannot change your mind later without re-running the installer, because the
web interface has the address compiled into it.
### Client addresses
The application records who connects, and some features decide what to show based
on it. The wizard asks one question:
- **Clients connect to this server directly** — the normal answer. Pick this
unless you know otherwise.
- **A proxy or load balancer sits in front** — pick this only if your network
team has told you traffic reaches this server through something else first.
Getting this wrong is not dangerous, but the site will record every visitor as
coming from the server itself, and features that depend on location will not
work. It can be changed later by re-running the installer.
---
## First login
Open the address the installer gave you. With no users in the database yet, the
page offers to **create the first administrator**, then runs a short setup wizard
for site details, features and the floor map.
That first account is a normal administrator account. Use a real password —
this is the account that creates everyone else.
---
## Did it work?
From the Start Menu, open **ShopDB-Flask Console** and pick option 1, or:
```powershell
cd C:\shopdb-flask
.\shopdb-admin.ps1 status
```
You want to see the site started, the pool started, and `responding : yes`.
Day-to-day tasks — restarting, backups, logs, upgrades — are in
[OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
---
## If the install fails
**The server is left part-configured.** Whatever had been done before the failure
is still there. That is deliberate: it means re-running is able to pick up where
it stopped.
1. Read the error. It names the cause and what to do about it.
2. Fix that, then **run the same installer again**. Re-running is safe — it skips
what is already done and does not touch your database or `.env`.
3. If you would rather start clean, remove it from **Settings → Apps** first.
The full log is at:
```
C:\ProgramData\ShopDB-Flask\logs\shopdb-install-<date>.log
```
It records every step, including everything that was created. Send this if you
need help.
### Getting help from an AI assistant
These installs are often done with an assistant open in another window. Give it
real state rather than a description:
```powershell
.\shopdb-admin.ps1 check -Json
```
That prints one structured block covering the version, how the site is published,
IIS state, database reachability, Python version, installed features and any
errors. Paste it in. **It contains no passwords.** The install log is also safe
to share — the installer keeps secrets out of it deliberately.
Offline API reference for this server is served at `/api/docs` on the site
itself, and `docs\` in the install directory holds these runbooks.
---
## Upgrading
Run a newer installer over the top. It:
- backs the database up first, **verifies the dump is complete**, and refuses to
continue if it cannot;
- restores from that backup if the schema migration fails;
- refuses to install an **older** build over a newer one;
- keeps your `.env`, your data and your `web.config`.
Nothing else is required. See [UPGRADE.md](UPGRADE.md).
> **Before your first upgrade:** confirm `mysqldump` is available — the console's
> health check reports it. Without it the pre-upgrade backup is skipped, and that
> is the one you would want if a migration went wrong. It ships with the bundled
> database option; for an existing remote database, ask for `mysqlclient\` to be
> included in your installer bundle.
---
## Removing it
**Settings → Apps → ShopDB-Flask**, or Add/Remove Programs.
That removes the website, the application pool, the firewall rule and the
application directory. It deliberately **does not** drop the database and does
not uninstall MySQL, so your data survives.
Take a backup first: `.\shopdb-admin.ps1 backup`
---
## Notes for the person who builds the installer
Building a bundle for a site is a separate job, documented in
[../deploy/windows/installer/README.md](../deploy/windows/installer/README.md).
Sites receive a finished `.exe`; they do not build one.

195
docs/OPERATE-WINDOWS.md Normal file
View File

@@ -0,0 +1,195 @@
# Running ShopDB-Flask on Windows Server
Day-to-day operation of a site installed with the Windows installer. If you are
installing for the first time, start with [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md).
Everything here goes through one tool, installed alongside the application:
```
C:\shopdb-flask\shopdb-admin.ps1
```
The Start Menu folder **ShopDB-Flask** has shortcuts for the common tasks. Run it
with no arguments for a menu, or pass a command directly. It needs
Administrator — it will ask, except for `open`.
---
## The commands
| Command | What it does | Safe at any time |
|---|---|---|
| `status` | Is it published, running, responding; database and table count | yes |
| `restart` | Recycles the application pool. **Use this after any config change.** | yes — drains requests rather than cutting them off |
| `stop` / `start` | Takes the site down / brings it back | yes, but `stop` makes it unavailable |
| `logs` | Last lines of the application and install logs | yes |
| `check` | Full health check | yes |
| `check -Json` | The same, machine-readable — see [Getting help](#getting-help) | yes |
| `verify` | Which build this is, and whether what is installed still matches it | yes |
| `sessions` | IIS worker processes and memory | yes |
| `plugins` | Which features are installed, which are available | yes |
| `add-plugin -Path <name>` | Turns on a feature this build ships | changes the site; restarts it |
| `backup [-Path <dir>]` | Writes a verified `.sql` dump | yes, but see below |
| `open` | Opens the site in a browser | yes |
Examples:
```powershell
.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 restart
.\shopdb-admin.ps1 backup D:\backups
.\shopdb-admin.ps1 verify -Path leaflet
```
---
## Backups
```powershell
.\shopdb-admin.ps1 backup
```
Writes to `C:\ProgramData\ShopDB-Flask\backups` unless you pass a directory. The
dump is **verified complete** before it is reported as good — a truncated backup
is deleted rather than left to be discovered later.
Two things to know:
- **The dump contains everything, including user password hashes.** The directory
is locked to Administrators and SYSTEM. Keep it that way, and treat copies as
sensitive.
- **Store it off this server.** A backup on the server does not survive the
server.
An upgrade takes its own backup automatically, before it touches the schema.
Restore, and the Linux/Docker equivalents, are in
[BACKUP-RESTORE.md](BACKUP-RESTORE.md).
---
## Upgrading
Run a newer installer over the top. Nothing else. It backs up first, refuses to
go backwards, and restores if a migration fails. See
[UPGRADE.md](UPGRADE.md).
---
## Adding a feature
```powershell
.\shopdb-admin.ps1 plugins # what is here
.\shopdb-admin.ps1 add-plugin -Path warranty # turn one on
```
Only features **shipped in this build** can be added. Each site's installer is
built for that site's chosen feature set, so a feature nobody asked for is not on
the server at all — adding it means a new installer built from an updated
profile. `plugins` shows you which is which.
---
## When something is wrong
Work down this list.
**1. Is it actually down?**
```powershell
.\shopdb-admin.ps1 status
```
`responding : NO` with the pool `Started` usually means the application failed to
start, not that IIS is broken.
**2. What does it say?**
```powershell
.\shopdb-admin.ps1 logs
```
Application logs are in `C:\shopdb-flask\logs`, install logs in
`C:\ProgramData\ShopDB-Flask\logs`.
**3. Try a restart.** It fixes anything that is a stuck worker, and tells you
immediately if it is not:
```powershell
.\shopdb-admin.ps1 restart
```
**4. Check the database is reachable** — `status` reports the host and whether it
could count tables. A site that starts but shows no data is usually a database
problem, not an application one.
**5. Confirm nothing has drifted:**
```powershell
.\shopdb-admin.ps1 verify
```
This flags packages that no longer match what shipped — which usually means
somebody ran a `pip install` on the server by hand.
---
## Getting help
Give an assistant real state rather than describing the symptom:
```powershell
.\shopdb-admin.ps1 check -Json
```
One structured block: version, how the site is published, IIS and pool state,
whether it responds, database host and reachability, Python version, installed
features, and any errors. **It contains no passwords** and is safe to paste into
a chat window or a ticket.
The install log is also safe to share — secrets are deliberately kept out of it.
Offline reference on the server itself:
- `/api/docs` on the site — the full API reference, self-hosted, no internet.
- `C:\shopdb-flask\docs\` — these runbooks.
- `C:\shopdb-flask\sbom.cdx.json` — every component this build contains.
---
## Answering "are we affected by this vulnerability?"
The server carries its own bill of materials, so this does not need the build box
or an internet connection:
```powershell
.\shopdb-admin.ps1 verify -Path <component-name>
```
It reports whether the component is here, at what version, and whether it
actually **ships** or is only used to build the software. Example:
```
matches for 'leaflet':
leaflet 1.9.4 SHIPPED
```
Nothing found means this server does not carry it.
---
## Where things live
| | |
|---|---|
| Application | `C:\shopdb-flask` |
| Configuration and secrets | `C:\shopdb-flask\.env` (locked down — do not loosen) |
| Application logs | `C:\shopdb-flask\logs` |
| Install logs | `C:\ProgramData\ShopDB-Flask\logs` |
| Backups | `C:\ProgramData\ShopDB-Flask\backups` |
| Bill of materials | `C:\shopdb-flask\sbom.cdx.json` |
| Which build this is | `C:\shopdb-flask\.installed-version` |
If the bundled MySQL was installed, its generated root password was written once
to `C:\ProgramData\ShopDB-Flask\mysql-root-password.txt`. **Move it into your
password manager and delete that file.** It cannot be recovered.

24
docs/UPGRADE.md
View File

@@ -111,9 +111,33 @@ print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())
PY
```
## Windows sites (installer-built)
Run a newer installer `.exe` over the existing install. That is the whole
procedure - none of the manual steps above apply.
It backs the database up first and verifies the dump, applies the core and plugin
migrations, restores from that backup if a migration fails, and refuses to
install an older build over a newer one. Your `.env`, your data and your
`web.config` are kept.
Before the first upgrade, confirm `mysqldump` is available
(`.\shopdb-admin.ps1 check`). Without it the pre-upgrade backup is skipped, which
is the one you would want if a migration went wrong.
Afterwards:
```powershell
.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 verify
```
See [OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
## See also
- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
- [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) - Windows Server install
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys
- [DEPLOY.md](DEPLOY.md) - first-time deploy runbook
- `CHANGELOG.md` - what changed in each release

23
docs/llms.txt
View File

@@ -5,6 +5,29 @@ network devices, measuring tools, applications, knowledge base, USB, warranties)
for GE Aerospace sites. This file is the quick entrypoint; the full machine
spec is the OpenAPI at `/api/docs/openapi.json` (browse it at `/api/docs`).
## Installing and operating this server (read this before answering "how do I install/fix it")
The people running these servers are often not Windows, IIS or Python
specialists, and they ask assistants for help. Two documents are authoritative:
- `docs/INSTALL-WINDOWS.md` - installing a NEW site. One offline installer `.exe`.
- `docs/OPERATE-WINDOWS.md` - restart, logs, backups, upgrades, troubleshooting.
Both ship in `docs/` inside the install directory on every installed server.
Do NOT walk someone through `docs/INSTALL-WINDOWS-IIS.md` or
`docs/DEPLOY-WINDOWS-IIS.md` for a new site. Those are the MANUAL procedure, kept
only for hand-built servers that predate the installer; following them produces a
server the installer then refuses to upgrade.
Day-2 operations all go through `shopdb-admin.ps1` in the install directory
(default `C:\shopdb-flask`): `status`, `restart`, `logs`, `check`, `verify`,
`backup`, `plugins`, `open`. Before diagnosing anything, ask for the output of
`shopdb-admin.ps1 check -Json` - it reports version, publishing method, IIS and
pool state, HTTP reachability, database host and reachability, Python version,
installed plugins and errors, and it contains no secrets. `verify -Path <name>`
answers "does this server carry component X" from the on-box CycloneDX SBOM.
Python is 3.14 and the wheelhouse is locked to it; an upgrade against a venv
built by a different minor version is refused by design.
## Base URL
Prod (West Jefferson): `https://tsgwp00525.wjs.geaerospace.net/shopdb`
All API paths are under `/api` (e.g. `<base>/api/assets`). Dev: `http://localhost:5001`.