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.
4.5 KiB
Upgrading an existing site
This is the procedure for moving a running shopdb-flask instance to a newer version. For a first-time install use DEPLOY.md instead.
Each site is single-tenant (ADR-004), so an upgrade touches only that site's
own stack. Read the ADRs added since your last update (docs/adr/) and the
CHANGELOG.md before starting; a breaking ADR may require coordinated work.
Step 0: Back up first
Never upgrade without a fresh backup you have tested. Take a full database dump
and copy the instance/ directory. See BACKUP-RESTORE.md.
# Docker:
docker compose exec -T db mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_flask | gzip > pre-upgrade-$(date +%F).sql.gz
cp -a instance/ instance-backup-$(date +%F)/
Step 1: Get the new code / image
git pull origin main
The application is distributed through the internal GE Aerospace Gitea; pull from there. There is no external image registry.
Step 2: Rebuild
The Docker image builds the Vue frontend in-image, so a container rebuild picks up frontend changes automatically:
docker compose build api
docker compose up -d api
Bare-metal / venv install: rebuild the frontend by hand and refresh Python dependencies:
source venv/bin/activate
pip install -r requirements.txt
cd frontend && npm ci && npm run build && cd ..
Step 3: Apply migrations
# Docker:
docker compose exec api flask db upgrade
docker compose exec api flask plugin upgrade-all
# venv:
flask db upgrade
flask plugin upgrade-all
flask db upgrade applies any new migrations in the core Alembic chain.
flask plugin upgrade-all then applies any new per-plugin migrations (each
bundled plugin owns its schema going forward - see ADR-008). Both are
idempotent; running them when already at head is a no-op.
Step 4: Re-seed permissions and settings
New versions may add RBAC permissions or default Settings keys. Both seeders are idempotent - they add anything missing and leave existing rows untouched, so your site's customized values are preserved.
# Docker:
docker compose exec api flask seed permissions
docker compose exec api flask seed settings
# venv:
flask seed permissions
flask seed settings
Step 5: Restart
docker compose restart api
# venv: restart your process manager, e.g. pm2 restart shopdb-flask-api shopdb-flask-ui
Confirm the app is healthy (login page renders, /api/auth/login returns a
VALIDATION_ERROR for an empty body rather than a 500).
Version-specific notes
Upgrading to v0.5.0 or later: bundled West Jefferson floor plan removed
Versions before 0.5 shipped the West Jefferson facility floor-plan PNGs as the
map default (/static/images/sitemap2025-light.png and -dark.png). v0.5+
removes those bundled PNGs and ships a generic placeholder SVG instead.
If your instance's map_blueprint_light / map_blueprint_dark Settings still
point at /static/images/sitemap2025-*, the map will 404 those images after the
upgrade. Re-upload your own floor plan in Settings > Floor Map. Uploaded floor
plans are stored under instance/ and survive upgrades, so a site that already
uploaded its own plan is unaffected. Only instances still using the old bundled
default need to act.
To check what your instance points at:
docker compose exec -T api flask shell <<'PY'
from shopdb.core.models.setting import Setting
print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())
PY
Windows sites (installer-built)
Run a newer installer .exe over the existing install. That is the whole
procedure - none of the manual steps above apply.
It backs the database up first and verifies the dump, applies the core and plugin
migrations, restores from that backup if a migration fails, and refuses to
install an older build over a newer one. Your .env, your data and your
web.config are kept.
Before the first upgrade, confirm mysqldump is available
(.\shopdb-admin.ps1 check). Without it the pre-upgrade backup is skipped, which
is the one you would want if a migration went wrong.
Afterwards:
.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 verify
See OPERATE-WINDOWS.md.
See also
- BACKUP-RESTORE.md - what to back up and how to restore
- INSTALL-WINDOWS.md - Windows Server install
- CONFIG.md - environment variables and Setting keys
- DEPLOY.md - first-time deploy runbook
CHANGELOG.md- what changed in each release