f72813ed9c
The bundled-database option could not actually be built. Stage 0 looks for mysql\mysql-8.0.x-winx64.msi, and Oracle no longer publishes a standalone server MSI for 8.0 - every 8.0.x returns 404. What remains for 8.0 is the MySQL Installer bundle, which is an installer-manager: 'msiexec /i INSTALLDIR=' would install THAT rather than a database, and stage 0 would then fail on a missing mysqld.exe. MySQL 8.0 also reached end of life in April 2026, so bundling it would have put an unsupported database on every new site. 8.4 LTS still ships the standalone MSI (129MB, which is what the '125MB' note in stage 0 was written against) and is supported into 2032. Defaults follow it: install root MySQL Server 8.4, service MySQL84. The operator console still looks for an 8.0 install path as a fallback, for sites already running one. Also bundles mysqlclient\ - mysql.exe and mysqldump.exe with the two OpenSSL DLLs they actually import, 20MB rather than the 51MB of debug and auth-plugin libraries the archive ships. Stage 2 stages it onto the server, so a site whose database is on ANOTHER host can still take the pre-upgrade backup that every upgrade depends on. That was the gap the preflight had started warning about. Bundle is now 221MB.
202 lines
7.5 KiB
Markdown
202 lines
7.5 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
|
|
```
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## 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 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:
|
|
|
|
```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.
|