shopdb-flask/docs/UPGRADE.md

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 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 - what to back up and how to restore
• CONFIG.md - environment variables and Setting keys
• DEPLOY.md - first-time deploy runbook
• CHANGELOG.md - what changed in each release