shopdb-flask/docs/UPDATES-WINDOWS.md

# 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](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:

```powershell
.\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:

```powershell
.\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 `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:

```powershell
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](OPERATE-WINDOWS.md) - day-to-day running
- [UPGRADE.md](UPGRADE.md) - upgrade notes across all deployment types
- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
- [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) - first-time install