aea2905de0
Nine fixes from a review of the installer against its actual audience: DT leads at sister sites who are not Windows, IIS or Python specialists and who will lean on an AI assistant to get through it. TRUTHFULNESS. The preflight was advisory - an operator read 'IIS is not installed', pressed Next, answered five more pages and the install died partway through with Python already on the box. The results page now blocks while anything is failing, repaints on every run instead of latching after the first, and offers 'Check again' so a fixed problem does not mean starting over. On failure the wizard said 'Nothing was left running', which is false in every path because the stages run with -OnFailure never: it now says the server is part-configured, that re-running is safe, and how to remove it. The final page no longer reads 'ShopDB-Flask is ready' after a failed install. SECRETS. The generated MySQL root password went to Write-Host in a process the wizard runs hidden - so nobody saw it - and stdout is forwarded into the setup log operators are told to send to support, so it was permanently recorded for everyone who did not need it. It now goes to an ACL'd file. Database dumps, which contain every user password hash, landed in a ProgramData directory readable by every user on the box; the directory is now locked at creation. UPGRADES ON REMOTE-DATABASE SITES. mysqldump was looked for only under local MySQL install paths, so a site whose database is on another host silently skipped every pre-upgrade backup - after stage 2 had already stopped the pool and replaced the tree. Find-MysqlTool now prefers a client shipped in the bundle, stage 2 stages it onto the server, preflight reports when it is missing, and mysqlclient\ is an optional locked payload. UNINSTALL. A subpath install is an IIS Application, not a site; removing only the site left the application pointing at a deleted directory, so the parent site - at West Jefferson, the live classic ASP - served 503 on that path forever while Add/Remove Programs reported success. Uninstall now reads MOUNT_PATH and removes the application. The firewall rule was created as "$SiteName $SitePort" and removed as the literal 'ShopDB-Flask 8090', which matches nothing. DAY-2 TOOLING. Every shortcut now passes -AppRoot and -SitePort, and the console forwards them through its own elevation and 32-bit relaunches instead of discarding them - a non-default directory or port made it report a healthy site as broken, from a shortcut the installer wrote. 'Open ShopDB-Flask' resolved to a hardcoded localhost:8090 that was wrong for every subpath install; it now asks the console, which reads the address the installer recorded, and no longer demands administrator to open a browser. SMOKE TEST. The parent-site port lookup filtered for an http binding and defaulted to 80, so an https-only parent site failed a working install with a red dialog. DOCS AND /api/docs. The installer was invisible: nothing in docs/, README.md or CLAUDE.md mentioned it, so a DT lead or their assistant landed on the manual IIS runbook and hand-built the very server the installer then refuses to upgrade. docs/INSTALL-WINDOWS.md and docs/OPERATE-WINDOWS.md are now the canonical route, the two manual runbooks are bannered as reference-only, README and CLAUDE.md route by target, and llms.txt tells an assistant which document to follow and to ask for 'check -Json' before diagnosing. Both ship on the server, along with openapi.json and llms.txt - without those the self-hosted /api/docs was broken on every installed box, which matters most to the sites least able to debug it. Stage 5 now checks it actually serves. shopdb-admin.ps1 gains 'check -Json': one structured, secret-free block covering version, publishing method, IIS state, HTTP reachability, database, Python version, plugins and errors. That is the cheapest useful answer to 'the operator will ask an LLM' - it works with no infrastructure, which a install-time MCP server could not.
7.5 KiB
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
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.0 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.
Installing
- Copy the installer
.exeonto 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 West Jefferson 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:
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 yourweb.config.
Nothing else is required. See UPGRADE.md.
Before your first upgrade: confirm
mysqldumpis 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 formysqlclient\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.