22e623c1f6
Framework: - Per-plugin Alembic migration chains (ADR-008): every bundled plugin carries its own chain with a stamp-only anchor at the ownership cutover; new plugin schema lands in plugins/<name>/migrations/, never the core chain. Deploys add flask plugin upgrade-all. Fixed a latent bug in the shared alembic template (engine URL resolution) and taught the metadata filter to include FK-referenced core tables. - Frontend plugin route gating (ADR-009): plugin routes carry meta.plugin; a disabled plugin's pages redirect to the dashboard via a cached, fail-open check against the new public GET /api/plugins/enabled. - get_reports() plugin hook (contract 0.5.0 -> 0.6.0): plugins contribute report cards; warranty and toner cards moved off the hardcoded list. Reports: - Hub grouped by category with search; inline reports render at the top, are URL-backed (?report=id, back-button and deep links work), expose their server-side filter params as controls, and export CSV. Warranty and Toner pages gained CSV export. - Deleted the dead legacy Warranty Status report (always-zero buckets from a retired column). Theming and fonts: - Inter (variable) bundled locally via @fontsource, replacing the Google Fonts Roboto import - air-gapped installs now render correctly; tables use tabular numerals. - Optional brand_primary_dark_color, brand_accent_color, brand_sidebar_color settings applied to CSS vars at bootstrap. USB frontend repair (views were reading a dead legacy shape): - List/detail/form and the employee profile USB panels remapped to the real API shape (device_id/device_desc/checkinoutlog); employee panels now use /usb/checkouts endpoints; external-mode /usb/checkouts/active honors the badge filter; dead client methods pruned. Also: warranties list page no longer requires login (matches app convention); collector doc rewritten with a GE-Enforce integration guide and paste-ready PowerShell reporter; ADR index and CHANGELOG updated. Verified: 323 tests pass, naming/style green, frontend builds, plugin migration dry-run green on scratch MySQL. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
117 lines
3.7 KiB
Markdown
117 lines
3.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 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:
|
|
|
|
```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 > 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 api flask shell -c "from shopdb.core.models.setting import Setting; print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())"
|
|
```
|
|
|
|
## See also
|
|
|
|
- [BACKUP-RESTORE.md](BACKUP-RESTORE.md) - what to back up and how to restore
|
|
- [CONFIG.md](CONFIG.md) - environment variables and Setting keys
|
|
- [DEPLOY.md](DEPLOY.md) - first-time deploy runbook
|
|
- `CHANGELOG.md` - what changed in each release
|