Files

cproudlock 96df19702e docs: one manual runbook, and ADR statuses that mean something

DEPLOY-WINDOWS-IIS was a second copy of the manual IIS procedure that had
diverged from the first: a different MySQL version (8.0, which reached end of
life in April), a different port, a different plugin list, and a profile file
that does not exist. Two runbooks for one procedure means a reader follows
whichever they found, and one of them was wrong. INSTALL-WINDOWS-IIS covers
everything it did plus a preflight step and the subpath method, so the one
section it uniquely had - redeploying a hand-built server - is folded in there,
with the plugin-chain step it was missing and a note to back up first, and the
duplicate is gone. Everything that pointed at it now points at the survivor.

Three ADR statuses said something untrue.

ADR-013 said PROPOSED while half of it had shipped and ADR-014 had been accepted
on top of it. A decision that has been implemented and depended upon is not
proposed, and leaving one that way devalues every other status in the index. The
catalog half is still unbuilt, which is the ordinary state of an accepted
decision: accepted means settled, not delivered.

ADR-016 said ACCEPTED for a design where nothing is built - the endpoint and
permissions it describes do not exist, so a reader goes looking for them. The
status stands, because the decision does; the header now says so plainly and
points at where today's credentials actually live.

ADR-003 and ADR-004 were ACCEPTED with their own Decision lines still opening
"**PROPOSED:**", which reads as though the decision was never taken.

And the dashboard proposal carried Status: ACCEPTED, which belongs to a decision
record. A proposal is a proposal; the contract it produced is the ADR.

2026-08-14 16:20:59 -04:00

12 KiB

Raw Blame History

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.

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.4 LTS (standard for new installs)	reachable from the app host. 8.0 reached end of life in April 2026 and no longer ships a standalone server MSI. 5.7+ still works on an existing server; 5.6 needs the flags in step 1.
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:

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

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)

$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

$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
}

# EVERY plugin owns its own Alembic chain (ADR-008), and `flask db upgrade`
# above ran only the core one. Skipping this is how a new column reaches
# production as a 1054 "Unknown column" error on the page that uses it.
venv\Scripts\flask plugin upgrade-all

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

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.

Create an app pool with No Managed Code:

Import-Module WebAdministration
New-WebAppPool -Name shopdbflask
Set-ItemProperty IIS:\AppPools\shopdbflask -Name managedRuntimeVersion -Value ""

Grant the app-pool identity access:

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

Unlock the handler sections (locked server-wide by default; without this IIS returns HTTP 500.19):

%windir%\system32\inetsrv\appcmd unlock config /section:system.webServer/handlers
%windir%\system32\inetsrv\appcmd unlock config /section:system.webServer/httpPlatform

Create the site (own port; the classic ASP site can keep 8080):

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.

Rebuild the frontend for the subpath (on the dev box, then copy dist):

cd frontend && VITE_BASE_PATH=/ops/ npm run build     # note the trailing slash

Create the Application under the existing site (instead of New-Website):

New-WebApplication -Site "Default Web Site" -Name ops -PhysicalPath APP_ROOT -ApplicationPool shopdbflask

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

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

Redeploying a hand-built server

A hand-built server has no installer to run, so an update is done by hand in the same order the installer would:

Copy the new code to the application root, rebuilding frontend/dist first if the UI changed.
venv\Scripts\pip install -r requirements.txt, if dependencies changed.
venv\Scripts\flask db upgrade for the core chain, then venv\Scripts\flask plugin upgrade-all for the plugin chains. Both, every time - the second is the one people skip, and it surfaces days later as a 1054 "Unknown column".
Recycle the application pool.

Take a database backup before step 3. The installer does this automatically and restores from it when a migration fails; by hand, it is yours to remember.

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.

12 KiB Raw Blame History