Files

cproudlock ee083ea80e docs: stop publishing internal references to a public wiki

docs/ is excluded from the code bundle and its scrub gate, because it goes to
the GitHub wiki instead - via a generator that has no gate at all. So the one
part of the repository written in prose, by people, about internal
infrastructure, was the one part nothing checked.

What was reaching a public wiki: the internal git server's URL and hostname,
.gitea workflow paths, developer home directories in the GE-Enforce cutover
reference, and a dev database root password inside a copy-pasteable command in
the import guide.

All replaced with neutral equivalents. tests/test_docs_publishable.py is now the
gate, at the source, in CI - a wiki page cannot be un-published, so catching this
after the fact is not good enough.

PROJECT-REVIEW.md also referred to internal tooling by name throughout; those
references are generalised. It remains an internal candid assessment of this
project that is nonetheless published, which is worth a separate decision.

2026-08-03 15:12:25 -04:00

4.5 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 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.

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.

4.5 KiB Raw Blame History