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.
234 lines
7.3 KiB
Markdown
234 lines
7.3 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.
|
|
|
|
---
|
|
|
|
## 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
.\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.
|