1d73bd477e
Two audiences, two documents. Both were only in people's heads. UPDATES-WINDOWS.md is for whoever runs a server: updates arrive as one self-contained exe, an update takes two to four minutes, the site is down for that time, .env and data and any hand-edited web.config are kept, unticking a feature never removes it, the database is backed up and verified first, and a downgrade is refused because migrations only go forwards. It covers both kinds of security release, application and third-party, and explains that the CycloneDX inventory staged on every server is what answers a published vulnerability question. It also says plainly that the exe is not signed and the checksum is the integrity check to rely on today. It answers one question the existing docs did not address at all: the effect on other sites sharing the same IIS server. The application pool is isolated and the configuration is scoped to its own path, so other sites keep their own handlers. What IS shared gets named rather than glossed: installing the IIS modules and writing server-level configuration recycles application pools across the server, which can drop requests in flight and clears in-memory session state, though IIS is never stopped and no iisreset is issued. The two IIS modules and the single permitted rewrite server variable are machine-wide and stay behind on uninstall, deliberately, since another site may have come to depend on them. The bundled database option collides on port 3306 with an existing MySQL. RELEASING-WINDOWS.md is for whoever builds releases: the three kinds of change and the commands for each, why bundle-lock.json must be committed, the two dependency traps that have each already cost a release, which generated files must never be hand-edited, and the pre-release checks. It records the two known gaps honestly - no code signing, and compiling still requires Windows and a person. UPGRADE.md and OPERATE-WINDOWS.md link to the operator document.
4.7 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 git server; 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.
UPDATES-WINDOWS.md is the operator-facing version of this: downtime, what is and is not touched, security updates, and the effect on other sites sharing the same IIS server.
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