fix(installer): correct a false security claim, and clear the should-fix list
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.
This commit is contained in:
cproudlock
@@ -1,7 +1,7 @@
|
||||
# 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)**.
|
||||
> 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
|
||||
@@ -140,12 +140,18 @@ Cleaner than a hand list: declare the set once in a site profile and apply it:
|
||||
```powershell
|
||||
venv\Scripts\flask plugin apply-profile deploy\site-profile.json # install + enable the chosen set, in dependency order
|
||||
venv\Scripts\flask plugin upgrade-all
|
||||
venv\Scripts\flask plugin prune-schema --yes --force # lean DB: drop tables of plugins this site did NOT install (ADR-014)
|
||||
venv\Scripts\flask plugin prune-schema --yes --force # FIRST PROVISIONING ONLY - see the warning below
|
||||
```
|
||||
|
||||
(Alternatively copy the dev box's `instance/plugins.json` to `APP_ROOT\instance\`
|
||||
to reproduce the exact set, then just run `flask plugin upgrade-all`.)
|
||||
|
||||
> **`prune-schema --force` is for first provisioning only.** It drops the tables
|
||||
> of plugins this site did not install *even when they hold rows*. On a site that
|
||||
> already has data, run `flask plugin prune-schema` with no flags first and read
|
||||
> what it says it would drop. Re-running with `--force` after a feature has been
|
||||
> used deletes that feature's records with no prompt and no backup.
|
||||
|
||||
## 6. Create the IIS site + web.config
|
||||
|
||||
This describes the own-site method (the app gets its own IIS site + port). To
|
||||
|
||||
@@ -23,7 +23,7 @@ sane, then use manual for day-to-day work.
|
||||
|
||||
| Need | Version | Check |
|
||||
| --- | --- | --- |
|
||||
| Python | 3.13 (64-bit) - matches CI; prod images run 3.12 | `python --version` |
|
||||
| Python | 3.14 (64-bit) - matches CI, the container image and the Windows installer wheelhouse | `python --version` |
|
||||
| Node.js | 18+ | `node --version` |
|
||||
| MySQL | 8.0 (or Docker, below) | `mysql --version` |
|
||||
| Git | any recent | `git --version` |
|
||||
@@ -33,7 +33,7 @@ reopen the terminal so PATH updates):
|
||||
|
||||
```powershell
|
||||
winget install Git.Git # includes Git Bash (naming hook needs it)
|
||||
winget install Python.Python.3.13
|
||||
winget install Python.Python.3.14
|
||||
winget install OpenJS.NodeJS.LTS # LTS; may install v24, fine for this SPA
|
||||
winget install Microsoft.VisualStudioCode
|
||||
winget install Oracle.MySQL # or Docker.DockerDesktop for the DB
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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)**.
|
||||
> 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
|
||||
|
||||
@@ -5,7 +5,7 @@ and get a working application. Nothing here needs an internet connection, and yo
|
||||
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
|
||||
[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.
|
||||
|
||||
---
|
||||
@@ -17,9 +17,9 @@ 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) | — |
|
||||
| 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):
|
||||
|
||||
@@ -35,10 +35,10 @@ time.
|
||||
|
||||
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
|
||||
- **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
|
||||
- **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.
|
||||
|
||||
@@ -51,29 +51,29 @@ bundled option.
|
||||
|
||||
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
|
||||
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. |
|
||||
| **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** | 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
|
||||
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
|
||||
- **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
|
||||
- **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.
|
||||
|
||||
@@ -85,9 +85,9 @@ web interface has the address compiled into it.
|
||||
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
|
||||
- **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
|
||||
- **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
|
||||
@@ -102,7 +102,7 @@ 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 —
|
||||
That first account is a normal administrator account. Use a real password -
|
||||
this is the account that creates everyone else.
|
||||
|
||||
---
|
||||
@@ -118,7 +118,7 @@ cd C:\shopdb-flask
|
||||
|
||||
You want to see the site started, the pool started, and `responding : yes`.
|
||||
|
||||
Day-to-day tasks — restarting, backups, logs, upgrades — are in
|
||||
Day-to-day tasks - restarting, backups, logs, upgrades - are in
|
||||
[OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
|
||||
|
||||
---
|
||||
@@ -130,9 +130,9 @@ 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
|
||||
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.
|
||||
3. If you would rather start clean, remove it from **Settings -> Apps** first.
|
||||
|
||||
The full log is at:
|
||||
|
||||
@@ -155,7 +155,7 @@ real state rather than a description:
|
||||
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.
|
||||
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.
|
||||
@@ -174,7 +174,7 @@ Run a newer installer over the top. It:
|
||||
|
||||
Nothing else is required. See [UPGRADE.md](UPGRADE.md).
|
||||
|
||||
> **Before your first upgrade:** confirm `mysqldump` is available — the console's
|
||||
> **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
|
||||
@@ -184,7 +184,7 @@ Nothing else is required. See [UPGRADE.md](UPGRADE.md).
|
||||
|
||||
## Removing it
|
||||
|
||||
**Settings → Apps → ShopDB-Flask**, or Add/Remove Programs.
|
||||
**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
|
||||
|
||||
@@ -11,7 +11,7 @@ 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`.
|
||||
Administrator - it will ask, except for `open`.
|
||||
|
||||
---
|
||||
|
||||
@@ -20,11 +20,11 @@ Administrator — it will ask, except for `open`.
|
||||
| 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 |
|
||||
| `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 |
|
||||
| `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 |
|
||||
@@ -50,7 +50,7 @@ Examples:
|
||||
```
|
||||
|
||||
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
|
||||
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:
|
||||
@@ -85,7 +85,7 @@ go backwards, and restores if a migration fails. See
|
||||
|
||||
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
|
||||
the server at all - adding it means a new installer built from an updated
|
||||
profile. `plugins` shows you which is which.
|
||||
|
||||
---
|
||||
@@ -119,7 +119,7 @@ immediately if it is not:
|
||||
.\shopdb-admin.ps1 restart
|
||||
```
|
||||
|
||||
**4. Check the database is reachable** — `status` reports the host and whether it
|
||||
**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.
|
||||
|
||||
@@ -129,7 +129,7 @@ problem, not an application one.
|
||||
.\shopdb-admin.ps1 verify
|
||||
```
|
||||
|
||||
This flags packages that no longer match what shipped — which usually means
|
||||
This flags packages that no longer match what shipped - which usually means
|
||||
somebody ran a `pip install` on the server by hand.
|
||||
|
||||
---
|
||||
@@ -147,13 +147,13 @@ 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.
|
||||
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.
|
||||
- `/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.
|
||||
|
||||
---
|
||||
|
||||
@@ -178,12 +178,50 @@ 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) |
|
||||
| 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` |
|
||||
|
||||
@@ -133,9 +133,30 @@ in place:
|
||||
A client that somehow hits waitress directly is not a trusted proxy, so its
|
||||
`remote_addr` is its own real peer address. Either way, real client IP.
|
||||
|
||||
If the IIS rule is ever removed, the allowlist stops matching (fails closed to
|
||||
401 for token-less clients) - it does NOT become spoofable, but the fleet
|
||||
falls back to cached manifests. Keep the rule on.
|
||||
**If the IIS rule is ever removed, the allowlist becomes SPOOFABLE.** This
|
||||
document previously claimed the opposite; it was wrong, and the reasoning matters.
|
||||
|
||||
IIS does not set `X-Forwarded-For` on its own - the rewrite rule is the only
|
||||
thing that does. Remove the rule and IIS still *forwards* whatever
|
||||
`X-Forwarded-For` the caller sent. waitress trusts that header because it arrives
|
||||
from `127.0.0.1`, which is IIS, and sets `remote_addr` from it. So a caller who
|
||||
sends `X-Forwarded-For: 10.134.48.5` gets `remote_addr = 10.134.48.5`, matches
|
||||
the allowlist and fetches manifests token-less from anywhere on the network.
|
||||
|
||||
The rule is not a nicety that improves logging. It is the control that makes
|
||||
`remote_addr` trustworthy, and everything downstream - the allowlist, the
|
||||
dashboard visitor-location lookup, per-host login rate limiting - depends on it.
|
||||
|
||||
Three consequences worth stating plainly:
|
||||
|
||||
- The Windows installer enables the rule when told IIS faces clients directly
|
||||
(`-ClientIpSource direct`), installs URL Rewrite from the bundle to make that
|
||||
possible offline, and its stage-5 check fails if the rule is not live.
|
||||
- On a hand-built server, verify it: `deploy/windows/web.config` must have the
|
||||
`<rewrite>` block ACTIVE, not inside the `SHOPDB-CLIENTIP` comment markers.
|
||||
- Behind a real reverse proxy the rule is the wrong answer, because `REMOTE_ADDR`
|
||||
is then the proxy. There, the proxy must set `X-Forwarded-For` itself and be
|
||||
the only thing that can reach IIS. `-ClientIpSource proxy` covers that case.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user