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.
217 lines
9.2 KiB
Markdown
217 lines
9.2 KiB
Markdown
# 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](INSTALL-WINDOWS.md)**.
|
|
>
|
|
> This is the **manual** procedure for the West Jefferson 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```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;
|
|
```
|
|
|
|
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:
|
|
|
|
```powershell
|
|
$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 13 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:
|
|
|
|
```powershell
|
|
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 # lean DB: drop tables of plugins this site did NOT install (ADR-014)
|
|
```
|
|
|
|
(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`.)
|
|
|
|
## 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"):
|
|
```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 `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
|
|
|
|
```powershell
|
|
# 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). |
|