2c415a1712
CLIENT IP / SPOOFABILITY. docs/geenforce-api-cutover.md claimed that removing the IIS rewrite rule made the allowlist fail closed and that it does NOT become spoofable. The opposite is true. IIS never sets X-Forwarded-For on its own; the rule is the only thing that does. Remove it and IIS still forwards whatever X-Forwarded-For the CALLER sent, waitress trusts it because it arrives from 127.0.0.1, and remote_addr becomes attacker-controlled - so a token-less caller can fetch manifests from anywhere on the network. The document and the _trusted_client_ip docstring now say so, waitress runs with --trusted-proxy-count=1, and stage 5 checks the rule is actually live rather than assuming it. The wizard question is rephrased to something an operator can verify with their network team instead of guessing at. NON-ASCII. The style gate only ever checked .py/.vue/.js/.ts, so documentation accumulated em-dashes, arrows and box-drawing characters against this repo's own convention - including in files added this week. Cleaned, and the gate now uses INCLUDES_ALL so Markdown, JSON and YAML are covered. PLUGIN DEFAULTS. The wizard pre-ticked measuringtools and printedparts, both of which ship default_enabled=false, so every site taking the defaults installed and enabled them against their manifests. Inno has no JSON parser so the list must be hardcoded, but tests/test_installer_defaults.py now fails when it drifts. UPGRADES. The payload copy merges, so a plugin dropped from a site's profile kept its code forever - which defeats a lean build and leaves core's optional-import guards succeeding for a plugin the site no longer has. Stale plugin directories are now deregistered and removed before the copy. add-plugin used 'plugin install', which for the five default_enabled=false plugins left them installed but DISABLED - and printed a green success line anyway. It now goes through apply-profile, and the success line is gated on the exit code. Invoke-Flask records its own exit status, because $LASTEXITCODE keeps a stale value when flask.exe is missing and no native command runs. CHARSET. The utf8mb4 compiler hook lived inline in migrations/env.py, so it covered the CORE chain only: plugin baselines inherited the server default, which on a latin1 server means two charsets in one database. It is now shopdb/utils/mysql_charset.py, imported by both, and preflight reports the database's default charset. BACKUP HONESTY. The dump was described as 'all of your asset data'. Uploaded branding and floor-map images live in instance\ on disk, not in the database, so a restore from the .sql alone comes back with no map. backup now archives instance\ alongside it and says both are needed. VERSIONING. AppVersion was hardcoded at 0.9.0 while the product, the frontend and the newest tag said 0.7.0 - and 0.9.0 collides with a retired contract version. Both builders now generate version.iss from shopdb/__init__.py. Smaller: rollback overwrites .env before deleting it, as uninstall already did; appcmd unlocks are scoped to this site's location rather than server-wide, with the wide unlock as a fallback; DEVELOPMENT-SETUP says Python 3.14; the README plugin list gains printedparts; prune-schema --force is documented as first-provisioning-only; HTTPS is documented as not-the-default with the steps to add it; the DBA SQL is on the wizard's database page; the features page says unticking does not remove an installed feature; and the installer README states that bundle-lock cannot vouch for the exe itself - that needs signing or an out-of-band hash, neither of which is wired up.
7.3 KiB
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.
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 | 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:
.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 restart
.\shopdb-admin.ps1 backup D:\backups
.\shopdb-admin.ps1 verify -Path leaflet
Backups
.\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.
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.
Adding a feature
.\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?
.\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?
.\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:
.\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:
.\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:
.\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/docson 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:
.\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.
Adding HTTPS
The installer publishes over HTTP. It has no certificate to use and no way to get one on an air-gapped server, so it does not pretend otherwise. On an internal network behind the site firewall that is often accepted; confirm it against your own policy rather than assuming.
If you installed under an existing site (the subpath option) and that site already has a certificate, you are already on HTTPS - nothing to do.
For a site of its own, once you have a certificate in the machine store:
Import-Module WebAdministration
# 1. Add the binding. Get the thumbprint from the certificate you imported.
New-WebBinding -Name shopdb-flask -Protocol https -Port 443
$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Subject -like '*yourserver*' }
Get-Item "IIS:\SslBindings\0.0.0.0!443" -EA SilentlyContinue | Remove-Item -EA SilentlyContinue
New-Item "IIS:\SslBindings\0.0.0.0!443" -Value $cert
# 2. Open the port.
New-NetFirewallRule -DisplayName "shopdb-flask 443" -Direction Inbound `
-Protocol TCP -LocalPort 443 -Action Allow
Then update CORS_ORIGINS in C:\shopdb-flask\.env to the https:// address
and restart:
.\shopdb-admin.ps1 restart
That last step is not optional. CORS_ORIGINS is an exact origin match, so a
site reached over https:// while .env still says http:// loads the page and
then fails every data request - which looks like the application is broken rather
than a configuration mismatch.
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.