1d73bd477e
Two audiences, two documents. Both were only in people's heads. UPDATES-WINDOWS.md is for whoever runs a server: updates arrive as one self-contained exe, an update takes two to four minutes, the site is down for that time, .env and data and any hand-edited web.config are kept, unticking a feature never removes it, the database is backed up and verified first, and a downgrade is refused because migrations only go forwards. It covers both kinds of security release, application and third-party, and explains that the CycloneDX inventory staged on every server is what answers a published vulnerability question. It also says plainly that the exe is not signed and the checksum is the integrity check to rely on today. It answers one question the existing docs did not address at all: the effect on other sites sharing the same IIS server. The application pool is isolated and the configuration is scoped to its own path, so other sites keep their own handlers. What IS shared gets named rather than glossed: installing the IIS modules and writing server-level configuration recycles application pools across the server, which can drop requests in flight and clears in-memory session state, though IIS is never stopped and no iisreset is issued. The two IIS modules and the single permitted rewrite server variable are machine-wide and stay behind on uninstall, deliberately, since another site may have come to depend on them. The bundled database option collides on port 3306 with an existing MySQL. RELEASING-WINDOWS.md is for whoever builds releases: the three kinds of change and the commands for each, why bundle-lock.json must be committed, the two dependency traps that have each already cost a release, which generated files must never be hand-edited, and the pre-release checks. It records the two known gaps honestly - no code signing, and compiling still requires Windows and a person. UPGRADE.md and OPERATE-WINDOWS.md link to the operator document.
7.8 KiB
What to expect from updates (Windows sites)
For the people who run a ShopDB-Flask server. It covers how updates arrive, what they do to your data and your server, how long they take, and what happens to anything else running on the same machine.
If you are the person building releases, see RELEASING-WINDOWS.md.
Updates arrive as one file
Every release is a single .exe, the same kind of file you used to install.
There is no patch, no separate updater, and no download step during the install:
everything the server needs is inside that one file, including the Python
runtime, all library code and the application itself.
To update, run the newer .exe on the server as Administrator. That is the
whole procedure.
The installer works out for itself that this is an update rather than a first install, and skips what is already correct. An update typically takes two to four minutes, most of which is the database migration.
What an update changes, and what it leaves alone
Changed:
- The application code and the web interface.
- The database schema, brought forward by migrations.
- The Python runtime and libraries, but only when that release moves them.
Left exactly as they are:
.env, which holds your database connection and secret keys.- Your data. Updates migrate the schema; they do not reset or reload content.
web.config, if you have edited it. The installer only ever repairs a specific fault in it that older builds created, and copies the file aside first when it does.- Which features are switched on. The feature list opens showing what this site already has.
- Uploaded files and anything under
instance\.
Unticking a feature during an update does not remove it. Adding is a tick; removing is a deliberate, separate step. This is so an upgrade can never quietly delete a feature and its data.
Downtime
The site is down for the length of the update, so two to four minutes. The installer stops the application pool before replacing files, because Windows will not let it overwrite files a running process holds open, and starts it again afterwards.
There is no reboot. If a release ever needs one, the installer says so rather than restarting the machine itself.
Your data is backed up first
Before applying migrations, the installer takes a database backup and checks the dump is readable. If a migration fails, it restores from that backup and tells you.
This depends on mysqldump being present. Confirm it once, before your first
update:
.\shopdb-admin.ps1 check
Without it the update still runs, but the pre-update backup is skipped, and that is precisely the backup you would want if a migration went wrong.
Afterwards:
.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 verify
Going backwards is refused
Installing an older build over a newer one is blocked outright. Once migrations have moved the schema forward, older code cannot read it, and the failures are difficult to unpick.
To go back you restore a backup taken before the update. Keep the previous
.exe until you are satisfied with a release.
Will an update affect other sites on the same IIS server?
Mostly no, and the exceptions are listed here rather than glossed over.
Isolated from other sites:
- The application runs in its own application pool under its own identity, so a crash or a memory leak cannot reach another site's pool.
- Its configuration lives in its own folder and applies only to its own URL path. A parent site's own pages, including classic ASP, keep their existing handlers.
- File permissions are granted on the application folder only.
Shared, and therefore worth knowing about:
- A brief application pool recycle across the server. Installing the IIS
modules and writing server-level configuration causes IIS to reload its
configuration, which recycles application pools. Requests in flight at that
moment can be dropped, and any session state other sites hold in memory is
lost. It is a few seconds and there is no service outage: IIS itself is never
stopped and no
iisresetis issued. - Two IIS modules are installed machine-wide the first time: HttpPlatformHandler and URL Rewrite. Both are standard Microsoft modules. They do nothing to a site that does not reference them, and if a site already uses URL Rewrite its rules are untouched.
- One rewrite server variable is permitted machine-wide,
HTTP_X_FORWARDED_FOR, so the application can see real client addresses instead of the loopback address. This grants exactly that one variable rather than opening the section up. - A Microsoft C++ runtime may be installed, which is shared and backwards compatible.
- The bundled database option installs MySQL on port 3306. If this server already runs MySQL, choose the existing-database option instead. Two servers will collide on that port. The wizard asks before doing anything.
Removing ShopDB-Flask takes away its own site, application, pool, folder and firewall rule. It deliberately leaves the shared IIS modules in place, because another site may have started depending on them.
If your server hosts something critical, schedule updates in a maintenance window for the pool recycle, not for the application itself.
Security updates
Two kinds reach you, both as an ordinary .exe.
Application fixes are built from the source and shipped like any other release.
Third-party fixes cover the Python runtime, the libraries, MySQL and the IIS modules. These are pinned to exact versions and checked by cryptographic hash at install time, so a release contains precisely the versions it claims and nothing substituted. When one of them publishes a fix that affects this application, it is picked up and a new release is issued.
Each release ships a machine-readable inventory of every third-party component
and its version, installed on the server as sbom.cdx.json. If your security
team asks whether you are exposed to a published vulnerability, that file
answers it without anyone guessing.
An update that is only a dependency bump is still worth taking: the version number moves and the application behaviour does not.
Check the file before running it
Each release publishes a SHA-256 checksum beside the .exe. Verify it:
certutil -hashfile ShopDBFlask_Installer_<version>.exe SHA256
Compare with the published .sha256 file.
Windows will warn about an unknown publisher, because the installer is not yet code-signed. The checksum is the integrity check to rely on today. Get the file from the agreed location rather than from mail or a message.
Version numbers
Three parts, for example 0.7.0:
- The last part changes for bug fixes and security fixes. Nothing you use behaves differently.
- The middle part changes for new features. Existing features keep working.
- The first part changes for something that needs you to read the notes first.
Before 1.0 the middle number can still bring changes that need attention. Read the release notes for those.
If an update fails
The installer stops at the first problem rather than continuing, and says what failed and what to do. Nothing is left half-applied: either the change is complete or it is rolled back, and the log records everything either way.
The log is at:
C:\ProgramData\ShopDB-Flask\logs\shopdb-install-<timestamp>.log
Re-running the same .exe is safe and picks up from where it stopped. If it
fails again, send that log with your report; it names the failing step, the
exit code and the relevant output.
See also
- OPERATE-WINDOWS.md - day-to-day running
- UPGRADE.md - upgrade notes across all deployment types
- BACKUP-RESTORE.md - what to back up and how to restore
- INSTALL-WINDOWS.md - first-time install