Deploy shopdb-flask to Windows IIS (MySQL 5.6)

Runbook for standing up a single-site instance on the production Windows Server that already runs the classic ASP shopdb, using IIS + HttpPlatformHandler + waitress, against the existing MySQL 5.6. This is the test-instance path; keep developing on the Linux dev box and redeploy as needed.

The Docker path in DEPLOY.md does NOT apply on Windows (gunicorn is Linux only, and there is no MySQL container here). This file replaces it for IIS.

Notation: APP_ROOT = the deploy folder, e.g. C:\shopdb-flask. The IIS site physical path must be APP_ROOT (where wsgi.py lives).

0. Prerequisites on the box

Python 3.12 (same minor as dev). py -3.12 --version to confirm.
IIS with the HttpPlatformHandler module: https://www.iis.net/downloads/microsoft/httpplatformhandler
URL Rewrite module (only for the optional real-client-IP rule).
Network access to the MySQL 5.6 server.
If the box is air-gapped, you cannot pip install live. On the dev box run pip download -r requirements.txt waitress -d wheels\ (on a matching Windows/Python target, or use --platform wheels), copy wheels\ over, and install with pip install --no-index --find-links wheels\ ....

1. Copy the code

Copy the repo to APP_ROOT, INCLUDING frontend/dist (the built SPA the API serves). Build it on dev first if stale:

# on the dev box
cd frontend && npm run build      # produces frontend/dist

Ship frontend/dist with the code (Node is not needed on the prod box).

2. Python venv + dependencies

cd C:\shopdb-flask
py -3.12 -m venv venv
venv\Scripts\python -m pip install --upgrade pip
venv\Scripts\pip install -r requirements.txt
venv\Scripts\pip install waitress

The DB driver is pymysql (pure Python) so no C compiler / MySQL client libs are needed. waitress is the WSGI server (installed separately, same as the Docker image installs gunicorn separately).

3. Prepare MySQL 5.6 (the utf8mb4 gotcha)

MySQL 5.6 defaults cannot index utf8mb4 VARCHAR(255) columns (767-byte prefix limit) and often defaults the server charset to latin1. The schema is utf8mb4, so the server needs Barracuda + large-prefix, made durable in my.ini under [mysqld], then restart the MySQL service:

[mysqld]
innodb_file_per_table = 1
innodb_file_format    = Barracuda
innodb_large_prefix   = 1

Then create the database as utf8mb4 and a least-privilege 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;

Without the [mysqld] flags, flask db upgrade fails with error 1071 ("Specified key was too long"). The migration chain emits ROW_FORMAT=DYNAMIC per table (see migrations/env.py), which fits the 3072-byte prefix those flags unlock.

4. Configure secrets and connection (.env)

Create APP_ROOT\.env (loaded by wsgi.py via load_dotenv()). Keep secrets here, not in web.config. Lock the file's ACLs to the IIS app-pool identity + administrators.

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=https://<the site's own hostname>

ProductionConfig.validate() refuses to boot if any of SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, CORS_ORIGINS is missing or left at a dev default. CORS_ORIGINS is the browser origin users hit (the IIS binding).

Generate a key: venv\Scripts\python -c "import secrets;print(secrets.token_urlsafe(64))".

5. Initialize schema, data, plugins, admin

Run from APP_ROOT with the venv active and .env present:

$env:FLASK_APP="shopdb"
venv\Scripts\flask db upgrade
venv\Scripts\flask seed reference-data

# Enable the plugins this site tracks (registry lives in the gitignored
# instance/plugins.json, so a fresh box starts with none enabled):
venv\Scripts\flask plugin list
venv\Scripts\flask plugin install computers
venv\Scripts\flask plugin install equipment
venv\Scripts\flask plugin install network
venv\Scripts\flask plugin install notifications
venv\Scripts\flask plugin install printers
venv\Scripts\flask plugin install usb
venv\Scripts\flask plugin install knowledgebase
venv\Scripts\flask plugin install slides
venv\Scripts\flask plugin install employees

# First admin (password is generated and printed once):
venv\Scripts\flask seed admin --username admin --email admin@yourfacility.example.com

(Alternatively copy the dev box's instance/plugins.json to APP_ROOT\instance\ to reproduce the exact enabled set, then just run flask plugin upgrade-all.)

6. Create the IIS site + web.config

This describes the own-site method (the app gets its own IIS site + port). To mount the app at a subpath under an existing site instead (e.g. https://<host>/ops/ sharing the classic site's binding and cert), see docs/INSTALL-WINDOWS-IIS.md section 7b: same web.config, but the site is a New-WebApplication under the parent, MOUNT_PATH=/ops is set (web.config or .env), and the frontend is built with VITE_BASE_PATH=/ops/.

In IIS Manager, add a new Site (separate from the classic ASP site):
- Physical path: APP_ROOT
- Binding: a free port or a dedicated hostname (e.g. https 443 with the facility cert, or http on a test port like 8081 to start).
- App pool: No Managed Code, and an identity that can read APP_ROOT.
Copy deploy\windows\web.config to APP_ROOT\web.config and edit the paths (C:\shopdb-flask -> your APP_ROOT). It launches waitress-serve --port=%HTTP_PLATFORM_PORT% wsgi:app and sets FLASK_ENV=production + PYTHONPATH.
Create APP_ROOT\logs for the HttpPlatform stdout log.

Unlock the handler sections (locked server-wide by default; without this IIS returns HTTP 500.19 "section cannot be used at this path"):

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

Grant the app-pool identity read/execute on APP_ROOT and modify on APP_ROOT\logs (e.g. icacls APP_ROOT /grant "IIS AppPool\<pool>:(OI)(CI)RX" /T).
Recycle the app pool / restart the site.

TLS terminates at the IIS binding. The X-Forwarded-For URL Rewrite rule in the web.config (real client IP for audit logs / kiosk visitor-location) is commented out by default because it needs the URL Rewrite module - with it active but URL Rewrite absent, IIS returns HTTP 500.19. Install URL Rewrite and uncomment the <rewrite> block to enable it.

7. Smoke test

# SPA loads:
curl.exe -k https://<host>/                       # returns index.html
# API rejects an empty login with a validation error (health signal):
curl.exe -k -X POST https://<host>/api/auth/login -H "Content-Type: application/json" -d "{}"
# expect JSON containing VALIDATION_ERROR

Then log in through the browser as the admin from step 5 and confirm the dashboard renders.

8. Redeploying as dev advances

Because this is a test instance you keep iterating on:

Pull/copy new code to APP_ROOT (rebuild frontend/dist on dev if the UI changed).
venv\Scripts\pip install -r requirements.txt (if deps changed).
venv\Scripts\flask db upgrade (if new migrations).
Recycle the app pool.

Troubleshooting

Symptom	Cause / fix
Site 502 / process won't start	Check `APP_ROOT\logs\httpplatform*`. Usually a bad `processPath`, missing waitress, or `wsgi:app` not importable (set `PYTHONPATH`).
Boots but SQL echoes / debug on	`FLASK_ENV` not `production` (web.config env var or `.env`).
`flask db upgrade` error 1071	MySQL 5.6 `[mysqld]` flags in step 3 not applied / server not restarted.
ConfigError on boot	A required var (SECRET_KEY / JWT_SECRET_KEY / DATABASE_URL / CORS_ORIGINS) missing or left at a dev default in `.env`.
Login works, CORS errors in browser	`CORS_ORIGINS` does not match the exact origin (scheme + host + port) the browser used.
Audit logs show 127.0.0.1	Expected without the URL Rewrite X-Forwarded-For rule (step 6).

Docs

Install and operate

Data import

Plugins

Integrations

Project

ROADMAP

ADRs

Proposals

PROPOSAL-ge-enforce-plugin