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.
255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# 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.
|
|
|
|
`APP_ROOT` below = the deploy folder, e.g. `C:\shopdb-flask` (where `wsgi.py`
|
|
lives). Run PowerShell as Administrator.
|
|
|
|
---
|
|
|
|
## 0. Prerequisites
|
|
|
|
| Need | Notes |
|
|
| --- | --- |
|
|
| **Python 3.14** (64-bit) | `python --version` |
|
|
| **IIS** with **HttpPlatformHandler** | https://www.iis.net/downloads/microsoft/httpplatformhandler (direct MSI: `download.microsoft.com/download/8/1/3/813AC4E6-9203-4F7A-8DD5-F3D54D10C5CD/httpPlatformHandler_amd64.msi`) |
|
|
| **MySQL 8.0** (standard for new installs) | reachable from the app host. 5.7+ is supported on an existing server; 5.6 needs the flags in step 1. CI and the container image both target 8.0. |
|
|
| URL Rewrite (optional) | only for the real-client-IP rule; skip it and the app still runs |
|
|
|
|
The app itself pulls in `waitress` and `tzdata` from `requirements.txt` (step 4).
|
|
|
|
---
|
|
|
|
## 1. MySQL: flags (5.6 only) + database + user
|
|
|
|
On **MySQL 5.6 only**, add to `my.ini`/`my.cnf` under `[mysqld]` and restart MySQL
|
|
(5.7+/8.0 need none of this):
|
|
|
|
```
|
|
innodb_file_per_table = 1
|
|
innodb_file_format = Barracuda
|
|
innodb_large_prefix = 1
|
|
```
|
|
|
|
Without them, `flask db upgrade` fails with **error 1071** ("key too long") - the
|
|
migrations use `ROW_FORMAT=DYNAMIC`, which needs the 3072-byte prefix these unlock.
|
|
|
|
Then create the database (utf8mb4) and an app user:
|
|
|
|
```sql
|
|
CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
CREATE USER 'shopdb'@'%' IDENTIFIED BY 'CHANGE_ME';
|
|
GRANT ALL PRIVILEGES ON shopdb_flask.* TO 'shopdb'@'%';
|
|
FLUSH PRIVILEGES;
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Deploy the app files
|
|
|
|
Copy the release (the repo minus `venv/`, `.git/`, `node_modules/`,
|
|
`frontend/src/`) to `APP_ROOT`. It must contain `wsgi.py`, `shopdb/`, `plugins/`,
|
|
`migrations/`, `requirements.txt`, and the pre-built `frontend/dist/`.
|
|
|
|
---
|
|
|
|
## 3. Virtual env + dependencies
|
|
|
|
```powershell
|
|
cd APP_ROOT
|
|
python -m venv venv
|
|
venv\Scripts\python -m pip install -r requirements.txt
|
|
```
|
|
|
|
This installs Flask, SQLAlchemy, PyMySQL, **waitress** (the WSGI server IIS
|
|
launches) and **tzdata** (Windows has no IANA tz database; without it the
|
|
notifications plugin fails with "No time zone found with key America/New_York").
|
|
|
|
---
|
|
|
|
## 4. Secrets + connection (.env)
|
|
|
|
Create `APP_ROOT\.env` (read by `wsgi.py` via `load_dotenv()`). Lock its ACLs to
|
|
the app-pool identity + admins.
|
|
|
|
```
|
|
FLASK_ENV=production
|
|
SECRET_KEY=<64+ random chars>
|
|
JWT_SECRET_KEY=<another 64+ random chars>
|
|
DATABASE_URL=mysql+pymysql://shopdb:CHANGE_ME@<mysql-host>:3306/shopdb_flask?charset=utf8mb4
|
|
CORS_ORIGINS=http://<the site's own hostname-or-ip:port>
|
|
```
|
|
|
|
Generate a key: `venv\Scripts\python -c "import secrets;print(secrets.token_urlsafe(64))"`.
|
|
Production **refuses to boot** if any of `SECRET_KEY`, `JWT_SECRET_KEY`,
|
|
`DATABASE_URL`, `CORS_ORIGINS` is missing or a dev default.
|
|
|
|
---
|
|
|
|
## 5. Preflight (catch problems before installing)
|
|
|
|
```powershell
|
|
$env:FLASK_APP="shopdb"
|
|
venv\Scripts\flask db-utils preflight
|
|
```
|
|
|
|
Checks Python, required env, DB connectivity, and the MySQL 5.6 index flags, and
|
|
prints exactly what to fix. Fix any **FAIL** before continuing.
|
|
|
|
---
|
|
|
|
## 6. Schema + data + plugins + admin
|
|
|
|
```powershell
|
|
$env:FLASK_APP="shopdb"
|
|
|
|
venv\Scripts\flask db upgrade # creates every table (to head)
|
|
venv\Scripts\flask seed reference-data # statuses, machine/location/rel types
|
|
venv\Scripts\flask seed permissions
|
|
venv\Scripts\flask seed settings
|
|
|
|
# enable the plugins this site tracks (registry is empty on a fresh box).
|
|
# usb + employees install DISABLED by default - enable them later in the wizard
|
|
# if the site wants those (they create extra tables).
|
|
foreach ($p in "computers","machines","network","notifications","printers","knowledgebase","slides","warranty") {
|
|
venv\Scripts\flask plugin install $p
|
|
}
|
|
|
|
# first admin (password generated + printed once - store it):
|
|
venv\Scripts\flask seed admin --username admin --email admin@yourfacility.example.com
|
|
```
|
|
|
|
> Prefer no CLI? Skip `seed admin` (and even the seed steps): start the site, and
|
|
> the login page offers to **create the first admin** on a fresh instance, then
|
|
> the setup wizard can seed reference data. Either path works.
|
|
|
|
---
|
|
|
|
## 7. IIS site
|
|
|
|
Two supported deployment methods:
|
|
|
|
- **Method A - own site (recommended, default):** the app gets its own IIS
|
|
site, port (or hostname), app pool, and venv. Steps 1-5 below.
|
|
- **Method B - subpath under an existing site:** the app runs as an IIS
|
|
**Application** (e.g. `/ops`) under a site you already have (such as the
|
|
classic ASP site or Default Web Site), so it shares that site's binding and
|
|
TLS cert: `https://<host>/ops/`. Do steps 1-4 below, then follow **7b**
|
|
instead of step 5.
|
|
|
|
1. Copy `deploy\windows\web.config` to `APP_ROOT\web.config`. If `APP_ROOT` is not
|
|
`C:\shopdb-flask`, fix the paths inside it. Create `APP_ROOT\logs`.
|
|
2. Create an app pool with **No Managed Code**:
|
|
```powershell
|
|
Import-Module WebAdministration
|
|
New-WebAppPool -Name shopdbflask
|
|
Set-ItemProperty IIS:\AppPools\shopdbflask -Name managedRuntimeVersion -Value ""
|
|
```
|
|
3. Grant the app-pool identity access:
|
|
```powershell
|
|
icacls APP_ROOT /grant "IIS AppPool\shopdbflask:(OI)(CI)RX" /T
|
|
icacls APP_ROOT\logs /grant "IIS AppPool\shopdbflask:(OI)(CI)M" /T
|
|
mkdir APP_ROOT\instance 2>NUL
|
|
icacls APP_ROOT\instance /grant "IIS AppPool\shopdbflask:(OI)(CI)M" /T
|
|
```
|
|
4. **Unlock the handler sections** (locked server-wide by default; without this
|
|
IIS returns **HTTP 500.19**):
|
|
```powershell
|
|
%windir%\system32\inetsrv\appcmd unlock config /section:system.webServer/handlers
|
|
%windir%\system32\inetsrv\appcmd unlock config /section:system.webServer/httpPlatform
|
|
```
|
|
5. Create the site (own port; the classic ASP site can keep 8080):
|
|
```powershell
|
|
New-Website -Name shopdb-flask -Port 8090 -PhysicalPath APP_ROOT -ApplicationPool shopdbflask
|
|
New-NetFirewallRule -DisplayName "shopdb-flask 8090" -Direction Inbound -Protocol TCP -LocalPort 8090 -Action Allow
|
|
Start-Website shopdb-flask
|
|
```
|
|
|
|
IIS launches `waitress-serve --port=%HTTP_PLATFORM_PORT% wsgi:app` per the
|
|
web.config and reverse-proxies the site port to it. First request takes ~15s
|
|
(the app boots + connects to MySQL).
|
|
|
|
### 7b. Method B: subpath under an existing site
|
|
|
|
The mount path must match in **three places**: the IIS Application alias, the
|
|
`MOUNT_PATH` the backend sees, and the `VITE_BASE_PATH` the frontend was built
|
|
with. `/ops` is the example throughout; any alias works.
|
|
|
|
1. Rebuild the frontend for the subpath (on the dev box, then copy `dist`):
|
|
```bash
|
|
cd frontend && VITE_BASE_PATH=/ops/ npm run build # note the trailing slash
|
|
```
|
|
2. Create the Application under the existing site (instead of `New-Website`):
|
|
```powershell
|
|
New-WebApplication -Site "Default Web Site" -Name ops -PhysicalPath APP_ROOT -ApplicationPool shopdbflask
|
|
```
|
|
3. Tell the backend its mount path: in `APP_ROOT\web.config`, uncomment the
|
|
`MOUNT_PATH` environment variable (value `/ops`), or set `MOUNT_PATH=/ops`
|
|
in `APP_ROOT\.env`. `wsgi.py` then serves everything under the prefix
|
|
(requests outside it get a plain 404 naming the mount).
|
|
4. Recycle the app pool. The app is at `http(s)://<host>/ops/` and the API at
|
|
`/ops/api/...`.
|
|
|
|
The handler mappings in the app's web.config apply only inside the
|
|
Application, so the parent site's own handlers (classic ASP, static files)
|
|
are untouched. `CORS_ORIGINS` in `.env` is origin-only (scheme + host + port,
|
|
no path), so it is the same for both methods.
|
|
|
|
> The `X-Forwarded-For` URL Rewrite rule in web.config is **commented out by
|
|
> default**. It needs the URL Rewrite module; with it active but the module
|
|
> absent, IIS returns 500.19. Install URL Rewrite, then uncomment the
|
|
> `<rewrite>` block, to record real client IPs in audit logs.
|
|
>
|
|
> Two companion requirements, or the app keeps seeing 127.0.0.1:
|
|
> `allowedServerVariables` is locked at server level by default (500.52 when
|
|
> the block activates) - unlock once with
|
|
> `appcmd unlock config -section:system.webServer/rewrite/allowedServerVariables`.
|
|
> And waitress 2+ strips X-Forwarded-For from untrusted proxies, so the
|
|
> waitress `arguments` line must carry
|
|
> `--trusted-proxy=127.0.0.1 --trusted-proxy-headers=x-forwarded-for`
|
|
> (the shipped web.config already does).
|
|
|
|
---
|
|
|
|
## 8. Smoke test + first run
|
|
|
|
```powershell
|
|
(Invoke-WebRequest http://localhost:8090/ -UseBasicParsing).StatusCode # 200 (SPA)
|
|
Invoke-WebRequest http://localhost:8090/api/auth/login -Method POST `
|
|
-Body '{"username":"admin","password":"<the printed password>"}' `
|
|
-ContentType application/json -UseBasicParsing # 200 + token
|
|
```
|
|
|
|
Browse to `http://<host>:8090`, sign in as the admin, and the **setup wizard**
|
|
walks through site name, features (per-plugin: create tables here vs connect a DB),
|
|
floor-map upload, and starter data. Multiple Flask apps can share one IIS box -
|
|
each gets its own site, app pool, port, and venv.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause / fix |
|
|
| --- | --- |
|
|
| `flask db upgrade` -> error **1071** | MySQL 5.6 without the step-1 flags (or server not restarted). |
|
|
| IIS **500.19** | handler sections not unlocked (step 7.4), or the `<rewrite>` block active without URL Rewrite. |
|
|
| IIS **500.52** after enabling the rewrite block | `allowedServerVariables` locked at server level - `appcmd unlock config -section:system.webServer/rewrite/allowedServerVariables`. |
|
|
| Audit log shows only **127.0.0.1** with the rewrite block active | waitress strips untrusted proxy headers - `--trusted-proxy=127.0.0.1 --trusted-proxy-headers=x-forwarded-for` missing from the waitress `arguments`. |
|
|
| **500** with an empty HttpPlatform log | app-pool identity can't read `APP_ROOT` / run the venv (step 7.3), or `.env` missing/invalid. |
|
|
| "internal error" toggling plugins, or uploads fail | app pool cannot WRITE `APP_ROOT\instance` (plugin registry, logos, photos, files live there) - step 7.3 grants it Modify. |
|
|
| "No time zone found with key America/New_York" | `tzdata` not installed (`pip install tzdata`). |
|
|
| Nav missing Machines/PCs/... | plugins not installed (step 6 `flask plugin install`), or site not recycled. |
|
|
| Method B: blank page / assets 404 under `/ops` | frontend `dist` built without `VITE_BASE_PATH=/ops/` (step 7b.1). |
|
|
| Method B: SPA loads but every API call 404s | `MOUNT_PATH` unset or not matching the Application alias (step 7b.3). |
|
|
| ConfigError on boot | a required `.env` var missing or left at a dev default. |
|