928a50c16e
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.
237 lines
9.3 KiB
Markdown
237 lines
9.3 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|
|
```powershell
|
|
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](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:
|
|
|
|
```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
|