Files

cproudlock 928a50c16e 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.

2026-08-14 16:16:01 -04:00

10 KiB

Raw Blame History

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 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?	-

Installing IIS, if it is missing (this needs no internet):

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:

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

Copy the installer .exe onto the server. It is one file and needs no network.
Right-click it -> Run as administrator. Without this it cannot configure IIS, and it will tell you so.
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?
Client addresses	Whether a proxy sits in front	See Client addresses
Location	Where to install	`C:\shopdb-flask` is fine

The install takes a few minutes. Most of it is Python and the database schema.
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.

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:

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.

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.

Read the error. It names the cause and what to do about it.
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.
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:

.\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.

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. Sites receive a finished .exe; they do not build one.

10 KiB Raw Blame History