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.
This commit is contained in:
cproudlock
2026-08-14 16:16:01 -04:00
parent 62c5454f00
commit 928a50c16e
4 changed files with 146 additions and 6 deletions

View File

@@ -83,8 +83,45 @@ 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.
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?