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.
148 lines
4.7 KiB
Markdown
148 lines
4.7 KiB
Markdown
# 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](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](BACKUP-RESTORE.md).
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker compose build api
|
|
docker compose up -d api
|
|
```
|
|
|
|
Bare-metal / venv install: rebuild the frontend by hand and refresh Python
|
|
dependencies:
|
|
|
|
```bash
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cd frontend && npm ci && npm run build && cd ..
|
|
```
|
|
|
|
## Step 3: Apply migrations
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](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:
|
|
|
|
```powershell
|
|
.\shopdb-admin.ps1 status
|
|
.\shopdb-admin.ps1 verify
|
|
```
|
|
|
|
See [OPERATE-WINDOWS.md](OPERATE-WINDOWS.md).
|
|
|
|
## See also
|
|
|
|
- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
|
|
- [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) - Windows Server install
|
|
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys
|
|
- [DEPLOY.md](DEPLOY.md) - first-time deploy runbook
|
|
- `CHANGELOG.md` - what changed in each release
|