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:
@@ -166,10 +166,53 @@ Two Windows-specific notes:
|
||||
using a remote MySQL needs `mysqlclient\` in its installer bundle, or the
|
||||
pre-upgrade backup is skipped. `shopdb-admin.ps1 check` reports this.
|
||||
|
||||
Restoring is the standard `mysql < dump.sql`, then
|
||||
`.\shopdb-admin.ps1 restart`. Also restore `C:\shopdb-flask\instance\` if you are
|
||||
rebuilding a server - it holds uploaded branding and map blueprints, which the
|
||||
database does not.
|
||||
### Restoring on Windows, in order
|
||||
|
||||
Order matters. Restoring the database under running code that expects a
|
||||
different schema is how a restore turns into a second incident.
|
||||
|
||||
```powershell
|
||||
cd C:\shopdb-flask
|
||||
|
||||
# 1. Stop serving. The pool, not the whole site: other applications on this
|
||||
# IIS server are unaffected.
|
||||
.\shopdb-admin.ps1 stop
|
||||
|
||||
# 2. Restore the database. Use the dump taken closest BEFORE the problem,
|
||||
# not the newest one - the newest may already contain it.
|
||||
mysql -u root -p shopdb_flask < C:\ProgramData\ShopDB-Flask\backups\shopdb_flask-pre-upgrade-20260814-0730.sql
|
||||
|
||||
# 3. Restore instance\ if you are rebuilding a server rather than just
|
||||
# reverting data. It holds uploaded branding, map blueprints, application
|
||||
# images and warranty proofs - none of which are in the database.
|
||||
robocopy D:\backups\instance C:\shopdb-flask\instance /MIR
|
||||
|
||||
# 4. Start, then prove it.
|
||||
.\shopdb-admin.ps1 start
|
||||
.\shopdb-admin.ps1 check -Json
|
||||
```
|
||||
|
||||
`check -Json` reports version, publishing method, IIS and pool state, HTTP
|
||||
reachability, database reachability, Python version and installed plugins. If it
|
||||
passes, the restore worked; if the version it reports is not the version you
|
||||
expect, see "Rolling back a release" in [UPDATES-WINDOWS.md](UPDATES-WINDOWS.md),
|
||||
because a restored database and newer code is the one combination the installer
|
||||
cannot fix for you.
|
||||
|
||||
### What is lost if `.env` is lost
|
||||
|
||||
`.env` is not in the database dump, and rebuilding it is not simply retyping it:
|
||||
|
||||
| Value | If it is lost |
|
||||
|---|---|
|
||||
| `SECRET_KEY`, `JWT_SECRET_KEY` | Every issued token and session becomes invalid. Users log in again; managed API tokens must be reissued, which means every collector and GE-Enforce client needs its key replaced. Recoverable, but it is a fleet-wide job. |
|
||||
| `DATABASE_URL` password | Recoverable: reset the MySQL user's password and write the new one in. |
|
||||
| `MYSQL_ROOT_PASSWORD` | Recoverable through MySQL's own reset procedure, which requires stopping the server. |
|
||||
| `ZABBIX_TOKEN` and similar integration tokens | Reissue at the far end. Nothing else breaks. |
|
||||
|
||||
So back it up with the database, to somewhere as protected as the dump - it is
|
||||
ACL'd to Administrators and SYSTEM on the server for the same reason. A dump
|
||||
without its `.env` restores the data and locks everyone out of it.
|
||||
|
||||
See [OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user