Files

cproudlock 4995456136 docs: take one site's name, hosts and paths off the public wiki

The publishability gate caught internal tooling names and developer paths but
nothing site-specific, so roughly sixty leaks reached the wiki: the site name in
ten documents, real fleet hostnames in the collector and GE-Enforce examples, an
internal database name through the whole import guide, imaging-share paths, and
a maintainer's username as the Deciders line of every ADR and inside a generated
curl example.

None of it is a security matter on an air-gapped fleet. It matters because these
pages are read by engineers at other plants, and a document that names one site
throughout reads as that site's notes rather than a product's documentation -
which is exactly what it then gets treated as.

Examples now use neutral hostnames, the site is "the reference site" where the
distinction carries meaning, and ADRs are decided by "ShopDB maintainers". The
gate carries all of these patterns, so the next one fails a build.

Two documents leave docs/ because they were never written for an outside reader.
PROJECT-REVIEW.md is an internal health memo pinned to a commit from July, whose
headline finding (an untracked playbook) has since been fixed - it is history,
and git holds it. PILOT-DEPLOY.md is one site's own cutover runbook, complete
with a "re-measure before publishing" placeholder; it moves next to the loader
it belongs to, in scripts/site_imports/wjf/.

ADR-015 is AMENDED rather than rewritten. Its enforcement section still said
report-only and its backlog still listed hardcodes that are now cleared, which
left the record contradicting itself. The amendment says what changed and why
the report-only period ended; the original text stays, because what the decision
looked like when it was taken is the part worth keeping.

Also corrects llms.txt's response envelope, which had errors at the top level
and pagination at meta.total. Both are nested one deeper, so anything written
against that description read undefined on every error it tried to handle.

2026-08-14 15:38:27 -04:00

4.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 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 the reference site floor plan removed

Versions before 0.5 shipped the the reference site 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.

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:

.\shopdb-admin.ps1 status
.\shopdb-admin.ps1 verify

See OPERATE-WINDOWS.md.

4.7 KiB Raw Blame History