f9d6b57f0f
The docs lived on one lineage and the fleet code on another. That is why six pages described a shared fleet key as how an agent authenticates, why COLLECTOR-AUTH had to warn that the per-PC credential code was not in the repository it sat in, and why ADR-019 recorded a decision whose implementation was somewhere else. Documentation that cannot see the code it documents goes stale by construction, and no amount of editing fixes that. So the corpus moves here: 84 files, 56 pages, 20 ADRs, the proposals, INDEX.md, llms.txt and both gates. Filenames are unchanged, because a wiki page name is derived from the filename and a rename breaks every link anybody saved. THE POINT OF THE MOVE IS THE CORRECTION IT ENABLES. Every caveat that said "not in this tree" was false the moment the files landed beside the code, so each was rewritten from what is actually here: - COLLECTOR-AUTH gained the real enroll request body, the two bounds on the unauthenticated route (per-IP rate limit, pending cap with stale rows dropped before a real PC is refused), and the rejected pending reason that binds to the endpoint identity rather than the nonce. - ADR-019 now describes an implementation that is present, including its tests, and says plainly that what remains is the FLEET migration, not the code. - proposals/device-identity claimed phase 1 was unbuilt. plugins/computers declares deviceid on the collector schema and prefers it over the older fallbacks. Corrected in the page, its summary and the index. WINDOWS/IIS IS NOW DOCUMENTED AS THE LEGACY PATH, per the product decision, and carefully: it is what production runs today. Every Windows page opens by saying it is supported, not for a new site, and where a new site should go instead. No procedure was cut - an operator on an IIS box at 2am needs these pages to work exactly as well tomorrow. MIGRATE-TOPOLOGY stops being a footnote and becomes the off-ramp, which is why it nearly doubled: what was there did not match how the Docker stack really works here. The Docker material that already lived on this line was kept and given ownership rather than buried under the ported Windows-centric prose: DEPLOY now describes the four services, the migrate service that runs the upgrade chain before api starts, TLS terminated by nginx, and the plugin count corrected from thirteen to seventeen - a number both lineages had wrong. ROADMAP is rewritten from evidence rather than memory: what has shipped, read out of the changelog, the ADRs and the manifests, and ahead of it exactly two items - finalize a distributed release and polish the setup wizard. PROJECT-MAP is generated and was stale; the GENERATOR was what was wrong. --check passes now. API-REFERENCE is retired to a pointer. /api/docs serves 573 operations with derived auth, query parameters and harvested examples, and a hand-written page competing with that is a liability. The file stays so its wiki page and its inbound links survive. AND THE MOVE TURNED ON A SCRUB THAT HAD NEVER RUN HERE. test_docs_publishable keys on docs/*.md, which this line did not have, so it skipped - its own comment predicted what would surface. Porting the corpus activated it and it found 48 lines that must not reach a published wiki: branch names abbreviating the site, assistant-tooling paths, the site name in two deployment pages, and an employee ID in a Windows path that the scrub does not even look for.
157 lines
7.4 KiB
Markdown
157 lines
7.4 KiB
Markdown
<!-- docmeta
|
|
purpose: explanation
|
|
audience: developer, adopter
|
|
status: current
|
|
summary: Where a site own hostnames, paths and defaults are allowed to live, and where they are not.
|
|
loadwith: none
|
|
-->
|
|
|
|
# ADR-015: Where a site's own data is allowed to live
|
|
|
|
- Status: ACCEPTED
|
|
- Date: 2026-08-11
|
|
- Deciders: ShopDB maintainers
|
|
- Relates to: ADR-004 (per-site instances, not multi-tenant), ADR-013 (plugin catalog + lean per-site builds), ADR-014 (schema-lean per-site builds)
|
|
|
|
## Context
|
|
|
|
ShopDB is built as a product several GE Aerospace sites can adopt (ADR-004:
|
|
each site runs its own instance). It is also developed at one site, against
|
|
that site's live fleet. Every feature therefore arrives
|
|
carrying that site's hostnames, networks, share paths and vocabulary, and the
|
|
fastest way to ship any of them is to write the value where the code needs it.
|
|
|
|
That is not a hypothetical drift. A scan of `plugins/` and `shopdb/` for a site
|
|
host, a site FQDN or a site network returns 19 hits, of which roughly 8 are a
|
|
shipped default or a hardcode rather than a comment:
|
|
|
|
- `plugins/geenforce/seed_display_scope.py` baked one site's own ShopDB URL and
|
|
`device.geaerospace.net` into an inline PowerShell payload. A sister site
|
|
could not override either without editing the source. FIXED 2026-08-14: the
|
|
kiosk base URL now comes from the `site_base_url` setting at seed time and
|
|
from HKLM at run time, and the dispatcher refuses rather than guessing when
|
|
neither is set.
|
|
- `plugins/backups/services/registry.py` defaults the backup share root to one site's own
|
|
UNC path.
|
|
- `shopdb/core/api/settings.py` ships `device.geaerospace.net` and
|
|
`Printer-{ip}.printer.geaerospace.net` as SETTING DEFAULTS, so another site
|
|
inherits that site's domain silently until someone notices.
|
|
- `shopdb/core/models/dashboarddefault.py` holds the same domain a second time
|
|
as a module constant, and `plugins/computers/api/routes.py` a third time as a
|
|
literal fallback.
|
|
|
|
The problem is not that site-specific values exist - they must. It is that the
|
|
repository already has three good mechanisms for them and no rule about which to
|
|
use, so each new value lands wherever was convenient. The result reads as drift
|
|
because it is unmanaged, not because any single choice was wrong.
|
|
|
|
Nothing here is a security matter: these are internal hostnames on an air-gapped
|
|
network, and `tests/test_docs_publishable.py` already gates what reaches the
|
|
public wiki. This is about whether a sister site can adopt the product without
|
|
reading our source.
|
|
|
|
## Decision
|
|
|
|
A site's own data lives in one of three places, in this order of preference.
|
|
|
|
**1. A setting, with a NEUTRAL default.** Anything an operator could plausibly
|
|
change: hostnames, domains, share paths, networks, base URLs, label prefixes.
|
|
The default that ships must be blank or generic, never one site's value. Blank
|
|
must be a working state - code reads the setting and degrades sensibly, the way
|
|
`display_fqdn_domain` already treats blank as "use the hostname as-is". A
|
|
site-specific default is the failure mode this ADR exists to stop: it is
|
|
invisible, it looks deliberate, and it is wrong everywhere except here.
|
|
|
|
**2. A site-namespaced directory.** Anything that is genuinely one site's and
|
|
will never be another's, such as the reference site's import loader at
|
|
`scripts/site_imports/wjf/`. Never reached by another site's build.
|
|
|
|
**3. Seed data, not code.** Vocabularies and catalogs, loaded by `flask seed`
|
|
and editable per site afterwards.
|
|
|
|
Fleet-wide convention is NOT site-specific. The `gea-shopfloor-*` imaging types
|
|
are a GE fleet taxonomy, not one site's data, and they already carry a per-site
|
|
override through the `pctypemap_*` settings. They are out of scope here.
|
|
|
|
Comments and documentation may name a site where it explains WHY - "part markers
|
|
share a machine number at the reference site" is a fact a maintainer needs. Prefer
|
|
phrasing the rule generally and the example specifically.
|
|
|
|
## Enforcement
|
|
|
|
`scripts/check-naming-and-style.sh`, which already runs in CI, greps `plugins/`
|
|
and `shopdb/` for a site host, a site FQDN or a site network, excluding tests
|
|
and `site_imports/`.
|
|
|
|
It shipped in REPORT-ONLY mode, because turning a 19-item backlog into a hard
|
|
gate on the day it lands blocks every unrelated commit until someone works
|
|
through it. See the amendment below: it now fails the build.
|
|
|
|
## Consequences
|
|
|
|
Positive:
|
|
|
|
- A sister site can adopt without reading our source for values it must change.
|
|
- The backlog is visible and counted rather than felt.
|
|
- New site-specifics are caught at commit time, in the same place the naming
|
|
rules are already enforced, so there is nothing new to remember.
|
|
|
|
Negative:
|
|
|
|
- Report-only means the rule is advisory until someone flips it, and an
|
|
advisory rule can be ignored.
|
|
- A neutral default is more code than a working one: every read needs a blank
|
|
case, which is a real cost paid at every call site.
|
|
- The pattern list is a denylist and will miss a site value it has not been
|
|
taught. It catches drift, not everything.
|
|
|
|
## Backlog
|
|
|
|
CLEARED - see the amendment below. Kept as the record of what the decision was
|
|
answering:
|
|
|
|
- `plugins/geenforce/seed_display_scope.py` - kiosk base URL, FQDN domain, and
|
|
the legacy-shortcut sweep pattern
|
|
- `plugins/backups/services/registry.py` - `DEFAULTSHAREROOT`
|
|
- `shopdb/core/api/settings.py` - `display_fqdn_domain` and the printer
|
|
hostname pattern defaults
|
|
- `shopdb/core/models/dashboarddefault.py` - `DEFAULT_DISPLAY_FQDN_DOMAIN`
|
|
- `plugins/computers/api/routes.py` - literal fallback duplicating that default
|
|
|
|
The domain appears three times in three files, which is its own defect: one
|
|
setting, one default, one read.
|
|
|
|
Cosmetic mentions in comments and UI placeholder text are acceptable under this
|
|
ADR and are not part of the backlog, with one exception worth fixing when
|
|
convenient: the GE-Enforce settings page shows one site's real CIDRs as its
|
|
placeholder, which every site sees.
|
|
|
|
## Amendment, 2026-08-14
|
|
|
|
The backlog above is cleared and the scanner now ENFORCES: it fails the build,
|
|
and `SITE_LITERALS_ENFORCE=0` is the escape hatch rather than the default. The
|
|
report-only period ended for the reason the Consequences section predicted - the
|
|
hit count did not move for weeks, because a rule that only prints is read as no
|
|
rule.
|
|
|
|
Three things changed beyond clearing the list:
|
|
|
|
- The scan covers PowerShell, the installer, the seeds, generated JSON and the
|
|
frontend, case-insensitively, across `plugins/`, `shopdb/`, `scripts/`,
|
|
`deploy/`, `frontend/src/` and `tools/`. Its original scope - three file types
|
|
under two directories - missed every literal that actually reached a second
|
|
site, because those were all in the client scripts and the installer.
|
|
- A line may declare itself deliberate with a trailing `ADR-015-OK: <reason>`
|
|
marker. That is for an organisation-wide default which is right at every site
|
|
and configurable anyway, such as the corporate device domain. It is not a
|
|
way to defer work: the marker puts the claim in the diff where a reviewer
|
|
sees it.
|
|
- Both publication gates - the export scrub and the docs publishability test -
|
|
carry the site patterns, which neither did. The ADR said this was not a
|
|
security matter because the values were internal to an air-gapped network;
|
|
that was true of the fleet and false of the public mirror, which had been
|
|
carrying a production hostname and a share path.
|
|
|
|
This amendment is appended rather than edited into the text above, because what
|
|
the decision looked like when it was taken is the part worth keeping.
|