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.
258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
# Install ShopDB-Flask on Windows Server
|
|
|
|
**This is the route for a new site.** You run one `.exe`, answer a few questions,
|
|
and get a working application. Nothing here needs an internet connection, and you
|
|
do not need to know IIS, Python or MySQL.
|
|
|
|
If you are looking after an existing hand-built server, see
|
|
[DEPLOY-WINDOWS-IIS.md](DEPLOY-WINDOWS-IIS.md) instead - that is the manual
|
|
procedure, and the installer will not adopt a server it did not build.
|
|
|
|
---
|
|
|
|
## Before you start
|
|
|
|
You need **four things**. The installer supplies everything else.
|
|
|
|
| | What | How to check |
|
|
|---|---|---|
|
|
| 1 | Windows Server 2019 or newer | `winver` |
|
|
| 2 | The **IIS Web Server role** installed | Server Manager -> Manage -> Add Roles -> Web Server (IIS). Or run the PowerShell below. |
|
|
| 3 | Administrator rights on the box | Right-click PowerShell -> "Run as administrator" works |
|
|
| 4 | A decision about the database - see [Which database?](#which-database) | - |
|
|
|
|
Installing IIS, if it is missing (this needs no internet):
|
|
|
|
```powershell
|
|
Install-WindowsFeature -Name Web-Server -IncludeManagementTools
|
|
```
|
|
|
|
### Sizing the server
|
|
|
|
Small, and the reasons are worth stating so a site does not over-provision.
|
|
ShopDB serves one plant's own staff, not the internet: a busy instance handles a
|
|
few dozen concurrent users and a fleet reporting a few hundred PCs a day, and
|
|
both are trivial loads. What actually consumes resources is MySQL and the
|
|
uploads.
|
|
|
|
| | Minimum | Comfortable | Why |
|
|
|---|---|---|---|
|
|
| Disk | 5 GB free (the installer refuses below this) | 40 GB | The application and Python are about 1 GB. The rest is MySQL, config-backup revisions, and uploads - branding, floor-plan blueprints, application installers and warranty proofs, which are the only ones that grow without bound. |
|
|
| RAM | 4 GB | 8 GB | MySQL wants most of it. The application itself is a Python worker per request. |
|
|
| CPU | 2 cores | 4 cores | Reports and the map are the heaviest reads and are cached. |
|
|
|
|
A VM is entirely normal. The one thing worth insisting on is that the database
|
|
directory and the backup directory are not on the same disk as anything you
|
|
would be sad to fill up.
|
|
|
|
### Getting the installer
|
|
|
|
The `.exe` is a release asset on the GitHub repository, not a file in it - it is
|
|
around 240 MB, which is well past what a repository accepts and well inside what
|
|
a release asset does. Take it from the release page for the version you want,
|
|
and keep it: you need the previous one to roll a release back, and you cannot
|
|
download it from your own server.
|
|
|
|
Every build is stamped with its version and ships a CycloneDX SBOM onto the
|
|
server, so `shopdb-admin.ps1 verify -Path <name>` answers "does this server
|
|
carry component X" without a network call - which is the question that arrives
|
|
on a Friday afternoon after a CVE announcement.
|
|
|
|
### If you get stuck
|
|
|
|
Raise an issue on the repository. Include the output of
|
|
`shopdb-admin.ps1 check -Json`, which reports version, IIS and pool state,
|
|
database reachability, Python version and installed plugins, and contains no
|
|
secrets - it is the single most useful thing you can attach, and it is designed
|
|
to be pasted.
|
|
|
|
---
|
|
|
|
The installer **checks all of this before it changes anything**, and it will not
|
|
let you continue until the check passes. You do not have to get it right first
|
|
time.
|
|
|
|
### Which database?
|
|
|
|
Two options. Pick before you start, because they ask different questions.
|
|
|
|
- **Use the bundled MySQL** - the installer puts MySQL 8.4 LTS on this server and
|
|
creates the database for you. Choose this when the server has no database
|
|
today. Simplest option, nothing to arrange in advance.
|
|
- **Use an existing MySQL** - the database already exists somewhere, and you have
|
|
a hostname, a database name, a username and a password for it. Choose this if
|
|
your site already runs MySQL, or a DBA looks after it.
|
|
|
|
If you are unsure: if nobody has given you database credentials, you want the
|
|
bundled option.
|
|
|
|
### SQL for your DBA (existing-MySQL option only)
|
|
|
|
The installer does not create the database or the user - it never needs
|
|
administrative rights on your database server. Ask your DBA to run:
|
|
|
|
```sql
|
|
CREATE DATABASE shopdb_flask CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
|
CREATE USER 'shopdb'@'%' IDENTIFIED BY '<a password you choose>';
|
|
GRANT ALL PRIVILEGES ON shopdb_flask.* TO 'shopdb'@'%';
|
|
FLUSH PRIVILEGES;
|
|
```
|
|
|
|
The `utf8mb4` charset matters - the default on older servers is `latin1`, and a
|
|
latin1 database mangles any non-ASCII text you store.
|
|
|
|
---
|
|
|
|
## Installing
|
|
|
|
1. Copy the installer `.exe` onto the server. It is one file and needs no
|
|
network.
|
|
2. **Right-click it -> Run as administrator.** Without this it cannot configure
|
|
IIS, and it will tell you so.
|
|
3. Work through the wizard. The pages are:
|
|
|
|
| Page | What it wants | If unsure |
|
|
|---|---|---|
|
|
| **Server check** | Nothing - it reports what it found | Fix anything red, then "Check again". You cannot continue while something is red, and nothing has been changed yet. |
|
|
| **Features** | Which parts of the product this site uses | The defaults are fine. You can add more later; removing needs a new installer. |
|
|
| **Database** | Bundled or existing - see above | Bundled |
|
|
| **Database details** | Host, port, name, user, password | Only asked for the existing-database option |
|
|
| **Address** | How people reach the site | See [Own address or subpath?](#own-address-or-subpath) |
|
|
| **Client addresses** | Whether a proxy sits in front | See [Client addresses](#client-addresses) |
|
|
| **Location** | Where to install | `C:\shopdb-flask` is fine |
|
|
|
|
4. The install takes a few minutes. Most of it is Python and the database schema.
|
|
5. At the end you get the address to open. **Write it down** - it is also on the
|
|
Start Menu as "Open ShopDB-Flask".
|
|
|
|
### Own address or subpath?
|
|
|
|
- **Its own address** - `http://yourserver:8090/`. Choose this on a server that
|
|
is not already running a website. Simplest.
|
|
- **Under this server's existing address** - `http://yourserver/shopdb/`. Choose
|
|
this when the server already serves something else and you do not want a second
|
|
port or a new DNS name. This is what the reference site uses.
|
|
|
|
You cannot change your mind later without re-running the installer, because the
|
|
web interface has the address compiled into it.
|
|
|
|
### Client addresses
|
|
|
|
The application records who connects, and some features decide what to show based
|
|
on it. The wizard asks one question:
|
|
|
|
- **Clients connect to this server directly** - the normal answer. Pick this
|
|
unless you know otherwise.
|
|
- **A proxy or load balancer sits in front** - pick this only if your network
|
|
team has told you traffic reaches this server through something else first.
|
|
|
|
Getting this wrong is not dangerous, but the site will record every visitor as
|
|
coming from the server itself, and features that depend on location will not
|
|
work. It can be changed later by re-running the installer.
|
|
|
|
---
|
|
|
|
## First login
|
|
|
|
Open the address the installer gave you. With no users in the database yet, the
|
|
page offers to **create the first administrator**, then runs a short setup wizard
|
|
for site details, features and the floor map.
|
|
|
|
That first account is a normal administrator account. Use a real password -
|
|
this is the account that creates everyone else.
|
|
|
|
---
|
|
|
|
## Did it work?
|
|
|
|
From the Start Menu, open **ShopDB-Flask Console** and pick option 1, or:
|
|
|
|
```powershell
|
|
cd C:\shopdb-flask
|
|
.\shopdb-admin.ps1 status
|
|
```
|
|
|
|
You want to see the site started, the pool started, and `responding : yes`.
|
|
|
|
Day-to-day tasks - restarting, backups, logs, upgrades - are in
|
|
[OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
|
|
|
|
---
|
|
|
|
## If the install fails
|
|
|
|
**The server is left part-configured.** Whatever had been done before the failure
|
|
is still there. That is deliberate: it means re-running is able to pick up where
|
|
it stopped.
|
|
|
|
1. Read the error. It names the cause and what to do about it.
|
|
2. Fix that, then **run the same installer again**. Re-running is safe - it skips
|
|
what is already done and does not touch your database or `.env`.
|
|
3. If you would rather start clean, remove it from **Settings -> Apps** first.
|
|
|
|
The full log is at:
|
|
|
|
```
|
|
C:\ProgramData\ShopDB-Flask\logs\shopdb-install-<date>.log
|
|
```
|
|
|
|
It records every step, including everything that was created. Send this if you
|
|
need help.
|
|
|
|
### Getting help from an AI assistant
|
|
|
|
These installs are often done with an assistant open in another window. Give it
|
|
real state rather than a description:
|
|
|
|
```powershell
|
|
.\shopdb-admin.ps1 check -Json
|
|
```
|
|
|
|
That prints one structured block covering the version, how the site is published,
|
|
IIS state, database reachability, Python version, installed features and any
|
|
errors. Paste it in. **It contains no passwords.** The install log is also safe
|
|
to share - the installer keeps secrets out of it deliberately.
|
|
|
|
Offline API reference for this server is served at `/api/docs` on the site
|
|
itself, and `docs\` in the install directory holds these runbooks.
|
|
|
|
---
|
|
|
|
## Upgrading
|
|
|
|
Run a newer installer over the top. It:
|
|
|
|
- backs the database up first, **verifies the dump is complete**, and refuses to
|
|
continue if it cannot;
|
|
- restores from that backup if the schema migration fails;
|
|
- refuses to install an **older** build over a newer one;
|
|
- keeps your `.env`, your data and your `web.config`.
|
|
|
|
Nothing else is required. See [UPGRADE.md](UPGRADE.md).
|
|
|
|
> **Before your first upgrade:** confirm `mysqldump` is available - the console's
|
|
> health check reports it. Without it the pre-upgrade backup is skipped, and that
|
|
> is the one you would want if a migration went wrong. It ships with the bundled
|
|
> database option; for an existing remote database, ask for `mysqlclient\` to be
|
|
> included in your installer bundle.
|
|
|
|
---
|
|
|
|
## Removing it
|
|
|
|
**Settings -> Apps -> ShopDB-Flask**, or Add/Remove Programs.
|
|
|
|
That removes the website, the application pool, the firewall rule and the
|
|
application directory. It deliberately **does not** drop the database and does
|
|
not uninstall MySQL, so your data survives.
|
|
|
|
Take a backup first: `.\shopdb-admin.ps1 backup`
|
|
|
|
---
|
|
|
|
## Notes for the person who builds the installer
|
|
|
|
Building a bundle for a site is a separate job, documented in
|
|
[../deploy/windows/installer/README.md](../deploy/windows/installer/README.md).
|
|
Sites receive a finished `.exe`; they do not build one.
|