Files

cproudlock 22e623c1f6 Plugin framework maturation, reports overhaul, theming, and USB frontend repair

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>

2026-07-11 10:01:47 -04:00

3.7 KiB

Raw Blame History

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 > 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 api flask shell -c "from shopdb.core.models.setting import Setting; print(Setting.query.filter(Setting.key.like('map_blueprint%')).all())"

3.7 KiB Raw Blame History