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.
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. |
|