aea2905de0
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.
196 lines
5.8 KiB
Markdown
196 lines
5.8 KiB
Markdown
# 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.
|