534f179ee6
main was 16 days and 259 commits behind the line the product is actually built on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It was neither current nor curated - just stale. This brings it forward and, at the same time, makes it mean something: main is what a receiving site installs, and nothing else. WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides, knowledgebase, machines, network, notifications, printers, slides, tools, warranty - plus applications, which is manifest-less core and always ships. The only manifest dependency inside that set is endpoints on computers, and both are in it, so the closure is self-contained. WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb stay on the site line. So do the Windows installer tree, the VM rehearsal helpers, the agent tooling config, one site's data loader, the internal audit and findings records, and the planner spreadsheet. 1,135 tracked files against 1,438. A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped: deploy/site-profile-universal.json still named all seventeen plugins. It is the file docs/DEPLOY.md tells a site to provision from, so a fresh install would have failed at `flask plugin apply-profile` with PluginError - the first thing a receiving site does, broken by the branch meant to serve them. It now names the twelve that exist, and its comment says the two must agree. agent/ was never refreshed. Whoever populated this branch copied shopdb/, plugins/, frontend/ and tests/ from the site line and left the agent tree at its September state: 22 C# and PowerShell sources missing, including AgentCredentials, EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the site line had deleted still present. The old tree is internally consistent, so it compiles, and nothing in CI builds it - every gate was green over a server that speaks enrollment and per-PC credentials to a bundled agent source that cannot. Resynced whole. DECISIONS THIS ENCODES, rather than defers: - The plugin-authoring lab builds printedparts, whose manifest depends on employees, so it could not stay. The lab remains on the site line and main ships no build-along tutorial. That is a real loss for an adopting developer and is recorded here rather than discovered later. - Recognition, Training and Recertification notifications are no longer seeded. Each splits one notification into a card per employee and renders a photo, which needs a plugin this branch does not bundle. Seeding them would offer an author a type that cannot resolve anybody. A site that installs employees gets them from that plugin's own seed. - Windows/IIS is documented as the legacy path throughout, and the README leads with Docker, because that is what a receiving site gets. The API description is regenerated for THIS branch - 347 paths and 483 operations, down from 415 and 573 - so the published contract describes what is here rather than what the site line serves. docs/CONFIG.md lost the two measuring-tool label keys the code no longer declares, which two lanes had decided opposite ways. Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run rather than skip, and every index line count is derived from the file it names.
5.8 KiB
Upgrading an existing site
Topology: Docker, or a bare-metal venv install. An air-gapped Docker site upgrades by loading a newer image tarball - DEPLOY-AIRGAP, not this page. Where this sits: install -> operate -> upgrade. Back: DEPLOY, which is also the page for a first-time install.
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: a full database dump and a
copy of instance/. BACKUP-RESTORE is the procedure.
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
git pull <your-remote> <your-branch>
The application is distributed as source, and a production site builds its own
image from that checkout. Sites do not pull a published image: CI publishes
channel images to a container registry for dev and pilot workstations only
(docker-compose.pull.yml, .github/workflows/publish-images.yml).
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 ..
up -d api REPLACES the container, so everything the site has written must be
in the instance_data volume. If your stack predates that volume, do the
one-time rescue in DEPLOY
before this step, not after.
Step 3: Migrate and re-seed
Under compose this is automatic. docker compose up -d api will not start
api until the migrate service has run db upgrade, the plugin bootstrap,
plugin upgrade-all and the three seeders and exited 0. Watch it:
docker compose logs migrate # the last line is the error, if there was one
A venv install has no migrate service and runs them itself:
flask db upgrade
flask plugin upgrade-all
flask seed permissions
flask seed settings
flask seed reference-data
All of them are idempotent, so running them at head or on an already-seeded
database is a no-op; the seeders add anything a new version introduced and leave
your site's customized values alone. plugin upgrade-all is the one people
skip - each plugin owns its own Alembic chain (ADR-008), and missing it surfaces
days later as a 1054 "Unknown column" on the page that uses the new field.
DEPLOY
explains what each command covers.
Step 4: Restart and confirm
docker compose restart api
# venv: restart your process manager, e.g. pm2 restart shopdb-flask-api shopdb-flask-ui
docker compose exec api flask db current # must match `flask db heads`
Then log in: the page renders, and /api/auth/login returns a
VALIDATION_ERROR for an empty body rather than a 500.
Version-specific notes
Upgrading to v0.11.0: the floor map became buildings and levels
Nothing to do, and nothing moves on screen - the ordinary Step 3 migration
handles it. 7d33_buildings_and_levels creates one building ("Main") and one
default level ("Ground floor") carrying the blueprint paths and dimensions from
your map_* settings, then assigns every already-placed asset and location to
that level. Unplaced things stay unplaced. The old settings rows are
deliberately left in place, so a downgrade still finds the blueprint.
Two things to know afterwards:
- A second floor or building is a Settings task, not a migration: add it under
Settings > Buildings and levels, upload its blueprint, then move the markers
that belong on it.
POST /api/mappositions/transformmoves a whole level's markers onto a redrawn plan from landmark pairs, dry run by default. - Replacing a blueprint with one of DIFFERENT dimensions moves every marker on that level, because the coordinates are pixels of the old size. Upload it, then recalibrate with landmarks rather than editing the level's width and height by hand. The API refuses to adopt a new size on a level that already has markers, for this reason.
If you wrote a plugin that stores map positions, see CONTRACT-STABILITY.md: the
contract is 0.20.0 and a position must now carry its levelid.
Upgrading from before v0.5.0: the bundled floor plan was removed
Only affects an instance whose map_blueprint_light / map_blueprint_dark
Settings still point at /static/images/sitemap2025-*. Those bundled PNGs are
gone from v0.5 on, so the map 404s them after the upgrade. Re-upload your own
plan in Settings > Floor Map. Uploaded plans live under instance/ and
survive upgrades, so a site that already uploaded one is unaffected.
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
See also
- BACKUP-RESTORE - what to back up and how to restore
- CONFIG - environment variables and Setting keys
- DEPLOY - first-time deploy runbook
CHANGELOG.md- what changed in each release