shopdb-flask/docs/DEPLOY-WINDOWS-IIS.md

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.

This is the manual procedure for the the reference site server, which was built by hand against its existing MySQL 5.6 and predates the installer. Keep it for that box.

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.14 (same minor as dev and CI). py -3.14 --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 -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.14 -m venv venv
venv\Scripts\python -m pip install --upgrade pip
venv\Scripts\pip install -r requirements.txt

The DB driver is pymysql (pure Python) so no C compiler / MySQL client libs are needed. waitress is the WSGI server and ships in requirements.txt (unlike gunicorn, which the Docker image installs 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

# Install the plugins this site tracks (registry lives in the gitignored
# instance/plugins.json, so a fresh box starts with none installed). Run
# `flask plugin list` to see the current bundled set; the the bundled plugins are
# computers, employees, geenforce, knowledgebase, machines, measuringtools,
# network, notifications, printedparts, printers, slides, usb, warranty. Install
# only the ones this site wants:
venv\Scripts\flask plugin list
venv\Scripts\flask plugin install machines
venv\Scripts\flask plugin install printers
venv\Scripts\flask plugin install computers
venv\Scripts\flask plugin install network
venv\Scripts\flask plugin install notifications
venv\Scripts\flask plugin install usb
venv\Scripts\flask plugin install knowledgebase
venv\Scripts\flask plugin install slides
venv\Scripts\flask plugin install employees
venv\Scripts\flask plugin upgrade-all

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

Cleaner than a hand list: declare the set once in a site profile and apply it:

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

1. 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.
2. 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.
3. Create APP_ROOT\logs for the HttpPlatform stdout log.
4. 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
   

5. 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).
6. 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:

1. Pull/copy new code to APP_ROOT (rebuild frontend/dist on dev if the UI changed).
2. venv\Scripts\pip install -r requirements.txt (if deps changed).
3. venv\Scripts\flask db upgrade (if new migrations).
4. 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).