Files

cproudlock 928a50c16e docs: what a site needs that no page answered

Four gaps a second site hits and cannot resolve by reading.

**Restoring on Windows** was one sentence - "the standard mysql < dump.sql" -
with no ordering. Restoring a database under running code that expects a
different schema turns a restore into a second incident, so the steps are now
ordered and each says why. It also says what `.env` costs if it is lost, which
is the part nobody discovers until they are already rebuilding: the dump does
not contain it, and without the JWT secrets every issued token dies, so every
collector and every GE-Enforce client on the fleet needs a new key.

**Rolling back** had a paragraph saying downgrades are refused and a backup is
the way back, but not the procedure. Rollback is restoring a matched pair, code
and the schema it expects, in that order - and the doc now separates it from the
case it gets confused with: a migration that failed mid-update has already been
rolled back by the installer, and fixing forward is the only move.

**Sizing, acquisition and support** were absent from the install guide entirely.
A reader could not learn how big a server to ask for, where the .exe comes from,
or where to raise a problem. The sizing is small and the reasons are stated, so
a site does not over-provision a VM for a load that is a few dozen users.

**Credentials** were described in three documents from three ends, so three
answers existed for where a key lives. One table, both ends - server and PC -
plus the two rules behind it: what a shop-floor PC holds is scoped to exactly
what it does, and a credential is delivered rather than typed, because a value
entered per machine is a value that is wrong on some machine.

2026-08-14 16:16:01 -04:00

9.3 KiB

Raw Blame History

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.

Keep the previous .exe until you are satisfied with a release. You cannot download it again from the server, and it is what a rollback needs.

Rolling back a release

Rolling back is restoring a matched pair: the code AND the database it expects. Doing one without the other is the state the installer refuses to create, and it is worth understanding why - newer code against an older schema fails at the first query that touches a new column, while older code against a newer schema often appears to work until something silently misreads a column that changed meaning.

The update takes its own backup before touching the schema, so the pair you need already exists.

cd C:\shopdb-flask
.\shopdb-admin.ps1 stop

# 1. Database first, from the pre-upgrade dump the update took.
mysql -u root -p shopdb_flask < C:\ProgramData\ShopDB-Flask\backups\shopdb_flask-pre-upgrade-<stamp>.sql

# 2. Then the code: run the PREVIOUS installer .exe. It is an install over a
#    restored older schema, which is the ordinary case, not a downgrade.
.\ShopDBFlask_Installer_<previous-version>.exe

# 3. Prove the pair matches.
.\shopdb-admin.ps1 check -Json

If a migration failed mid-update, the installer has already restored its own backup and there is nothing to roll back - read the log it names and fix forward. Rollback is for a release that installed cleanly and then behaved badly, which is a different situation and the only one this procedure is for.

Uploaded files are not in the dump. If the release you are leaving behind accepted uploads, restore instance\ from your own backup as well, or those files stay while the rows referring to them do not. See BACKUP-RESTORE.md.

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 iisreset is 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.

9.3 KiB Raw Blame History