shopdb-flask/deploy/windows/installer

Windows installer

Builds a single self-contained .exe that installs ShopDB-Flask on an air-gapped Windows Server. Nothing here ever touches the network at install time: Python, the wheels, the SPA and (optionally) MySQL all ship inside it.

Lives with the application on purpose. The installer depends on app internals - flask plugin verbs, site-profile.json, MOUNT_PATH, the plugin registry - so a separate repo would drift out of step with the thing it installs.

Files

File	What it is
shopdb-preflight.ps1	Stage 1. Read-only. Changes nothing, reports what this server is missing.
shopdb-install.ps1	Stages 0 and 2-5 plus uninstall. All the actual work.
shopdb-admin.ps1	Operator console installed alongside the app: status, restart, logs, backup, plugins.
ShopDBFlask.iss	Inno Setup wizard. A thin wrapper - it collects input and runs the stages.
build-installer.sh	Stages the bundle from a site profile.
make-branding.py	Generates wizard artwork and the icon from frontend/public/*.svg.
*.bmp, shopdb.ico	Generated artwork, committed so a Windows build box needs no Python.

Building

# 1. Stage the bundle for a site's plugin set.
./build-installer.sh ../../site-profile.example.json

# 2. Add the pieces that cannot be built on Linux:
#      bundle/wheels/               ~47 cp314 win_amd64 wheels, built ON Windows:
#                                   pip download -r requirements.txt -d wheels --only-binary=:all:
#      bundle/python/               python-3.14.x-amd64.exe
#      bundle/httpplatformhandler/  httpPlatformHandler_amd64.msi
#      bundle/mysql/                mysql-8.0.x-winx64.msi   (bundled-database option only)

# 3. Compile on Windows.
iscc ShopDBFlask.iss

The wheelhouse is cp314-locked. A different Python minor version means a different wheelhouse; the installer will not use a Python it did not install.

Deployment methods

Chosen in the wizard, and the bundle carries a SPA build for each because Vite compiles the base path in - it cannot be switched at install time.

• Its own site on a port (default 8090).
• Subpath under an existing site, e.g. http://<server-fqdn>/shopdb/. Needs no new DNS record. Three things must agree - the IIS application alias, MOUNT_PATH in .env, and the SPA's build-time base - so the alias is fixed per bundle (SUBPATH_ALIAS, default shopdb) and the installer refuses if the bundle's build does not match what was asked for.

Switching between methods removes the other one's IIS artifact and reconciles MOUNT_PATH and CORS_ORIGINS, so a server never ends up with both.

Upgrades

Run a newer installer over an existing install. It:

• backs the database up first, verifies the dump is complete, and refuses to migrate if it cannot;
• restores from that backup if migrations fail, and reports honestly that DDL the failed migration committed cannot be undone;
• refuses to run a bundle older than what is installed;
• keeps .env unless new credentials are supplied, and copies it aside first;
• stops the app pool before replacing files, then starts it again.

Whether a run is an upgrade is decided by probing the target database, not by whether the app directory exists - a rebuilt server pointed at an existing database is an upgrade, and treating it as fresh would drop tables.

Testing notes

Verified end to end on Windows Server 2025 against both a bundled MySQL 8.0 and an existing MySQL 5.6: fresh install, upgrade, re-run idempotency, failure and rollback, uninstall, and both deployment methods including switching between them.

Not yet verified: a fully air-gapped run with the network disabled at the hypervisor, and any load in a real browser (all HTTP checks so far used curl, which sends no Origin header - so CORS_ORIGINS is untested in anger).