From bf9e60e607e53cd24e4f505ba0e9eb8a077e09c7 Mon Sep 17 00:00:00 2001
From: cproudlock <cproudlock@localhost>
Date: Fri, 10 Jul 2026 12:20:34 -0400
Subject: [PATCH] Windows/IIS install fixes found by validating on a real win11
 VM

Deployed to win11 + IIS + MySQL 5.6 end to end; fixed what broke.

- requirements.txt: add tzdata. Windows has no IANA tz database, so
  ZoneInfo('America/New_York') (notifications recognition/recert) fails and the
  plugin won't import. Also confirmed waitress (added earlier) is required.
- deploy/windows/web.config: comment out the X-Forwarded-For <rewrite> block by
  default - it needs URL Rewrite, and with it active but the module absent IIS
  returns HTTP 500.19. Uncomment after installing URL Rewrite.
- docs/DEPLOY-WINDOWS-IIS.md: add the required `appcmd unlock config` step for
  system.webServer/handlers + httpPlatform (locked server-wide by default ->
  500.19 without it) and the app-pool icacls grant.

Verified: IIS -> HttpPlatformHandler -> waitress -> app on :8090, all plugins
load, admin login works.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 deploy/windows/web.config  | 13 +++++++++----
 docs/DEPLOY-WINDOWS-IIS.md | 19 ++++++++++++++-----
 requirements.txt           |  1 +
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/deploy/windows/web.config b/deploy/windows/web.config
index 3d06ba3..2c76842 100644
--- a/deploy/windows/web.config
+++ b/deploy/windows/web.config
@@ -44,10 +44,14 @@
     <!--
       OPTIONAL: forward the real client IP so audit logs and the kiosk
       visitor-location feature (IP -> business unit) see the caller, not the
-      loopback that HttpPlatformHandler connects from. Needs URL Rewrite.
-      Delete this whole <rewrite> block if URL Rewrite is not installed;
-      audit logs will then record 127.0.0.1 for a test instance.
-    -->
+      loopback that HttpPlatformHandler connects from.
+
+      This block is COMMENTED OUT by default because it needs the URL Rewrite
+      module; with it uncommented but URL Rewrite not installed, IIS returns
+      HTTP 500.19 ("configuration section not well-formed / cannot be read").
+      Install URL Rewrite (https://www.iis.net/downloads/microsoft/url-rewrite)
+      and then uncomment the <rewrite> block below to enable it.
+
     <rewrite>
       <allowedServerVariables>
         <add name="HTTP_X_FORWARDED_FOR" />
@@ -62,6 +66,7 @@
         </rule>
       </rules>
     </rewrite>
+    -->
 
   </system.webServer>
 </configuration>
diff --git a/docs/DEPLOY-WINDOWS-IIS.md b/docs/DEPLOY-WINDOWS-IIS.md
index 7a027a7..46e86c6 100644
--- a/docs/DEPLOY-WINDOWS-IIS.md
+++ b/docs/DEPLOY-WINDOWS-IIS.md
@@ -138,12 +138,21 @@ to reproduce the exact enabled set, then just run `flask plugin upgrade-all`.)
    `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. Recycle the app pool / restart the site.
+4. **Unlock the handler sections** (locked server-wide by default; without this
+   IIS returns **HTTP 500.19** "section cannot be used at this path"):
+   ```powershell
+   %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 optional URL Rewrite rule in the
-web.config sets `X-Forwarded-For` to the real client IP (HttpPlatformHandler
-otherwise forwards from loopback, so audit logs and the kiosk visitor-location
-feature would see 127.0.0.1). Drop that block if URL Rewrite is not installed.
+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
 
diff --git a/requirements.txt b/requirements.txt
index 3046104..d48e166 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -118,3 +118,4 @@ werkzeug==3.1.8
     #   flask-jwt-extended
     #   pytest-flask
 waitress>=3.0
+tzdata