c4e2db4755
START-HERE routes by the question somebody arrived with, and 'are we exposed to this CVE' had no entry - the SBOM was only mentioned in the Windows update doc, which is not where anybody asking that would look.
97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
# Start here
|
|
|
|
ShopDB is a per-site asset platform: one instance per plant, plugins for what
|
|
each site tracks. These pages document the server, the plugin contract, and the
|
|
tools that run on shop-floor PCs.
|
|
|
|
Find yourself below. Each row is the shortest correct path, not everything that
|
|
exists.
|
|
|
|
## I am standing up ShopDB at a new site
|
|
|
|
1. [INSTALL-WINDOWS](INSTALL-WINDOWS.md) - one offline installer, start to finish.
|
|
2. [OPERATE-WINDOWS](OPERATE-WINDOWS.md) - restart, logs, backups, upgrades.
|
|
3. [CSV-IMPORT](CSV-IMPORT.md) if the site's data is in spreadsheets, or
|
|
[IMPORT-API](IMPORT-API.md) if there is a source database to script against.
|
|
4. [FLOOR-MAP](FLOOR-MAP.md) - load the site's floor plans and place markers.
|
|
Also the page to read BEFORE a plan changes: it covers moving every marker
|
|
onto a redrawn plan without doing it one at a time.
|
|
|
|
**Do not** follow [INSTALL-WINDOWS-IIS](INSTALL-WINDOWS-IIS.md) for a new site.
|
|
That is the manual procedure, kept for hand-built servers that predate the
|
|
installer, and following it produces a server the installer then refuses to
|
|
upgrade.
|
|
|
|
## I am deploying the shop-floor tools
|
|
|
|
Read [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) first - it is one page and it
|
|
is what makes the rest make sense.
|
|
|
|
Then [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md), which has worked
|
|
examples for Intune, GE-Enforce and manual installation, and says where each
|
|
artifact comes from.
|
|
|
|
## I am writing a procedure for other people to follow
|
|
|
|
Guides live in ShopDB itself: [GUIDES.md](GUIDES.md). Typed blocks rather than
|
|
markup, pasted screenshots, checkboxes a technician can tick as they work, and a
|
|
draft/publish split so a procedure cannot change under somebody halfway through
|
|
it. Use it instead of leaving a Word document on a share.
|
|
|
|
## I am writing a plugin
|
|
|
|
1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run.
|
|
2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative.
|
|
3. [PLUGIN-LAB-PRINTEDPARTS](PLUGIN-LAB-PRINTEDPARTS.md) - a real plugin built
|
|
end to end, to type along with.
|
|
4. [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) if it lives in its own
|
|
repository, and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose
|
|
a version pin.
|
|
|
|
## I am integrating with the API
|
|
|
|
1. [LLM-GUIDE](llms.txt) (`docs/llms.txt` in the repo, also served at
|
|
`/api/docs/llms.txt`) - auth, the response envelope, common recipes.
|
|
Short, and the envelope section is the part people get wrong.
|
|
2. `GET /api/docs` on any running instance - the full spec, browsable.
|
|
3. [API-REFERENCE](API-REFERENCE.md) for prose, [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md)
|
|
if you are feeding data in from a PC.
|
|
|
|
## I have to give somebody a password
|
|
|
|
[SECURE-SEND](SECURE-SEND.md) - a one-view expiring link, instead of a chat
|
|
message or a sticky note. Read the "Before anybody relies on it" section first:
|
|
there is one thing to test at your site before the first real credential goes
|
|
through it.
|
|
|
|
## Somebody is asking whether we are exposed to a published vulnerability
|
|
|
|
[DEPENDENCY-SECURITY](DEPENDENCY-SECURITY.md). Every release installs
|
|
`sbom.cdx.json`, a full inventory of third-party components and versions, so a
|
|
security team can answer this on their own without access to anything here.
|
|
|
|
In the repository, `scripts/scan_sbom.py` checks that inventory against
|
|
published advisories and separates what ships from what only builds - the two
|
|
are not the same finding, and only the first can fail a release.
|
|
|
|
## I am trying to understand why something is built this way
|
|
|
|
[The ADRs](adr/ADR-001-asset-as-platform-contract.md). They are the decision record,
|
|
they say what was rejected and why, and they are the fastest way to avoid
|
|
relitigating a settled question. [PROJECT-MAP](PROJECT-MAP.md) lists them all
|
|
with their status, along with the current versions and every migration head -
|
|
it is generated, so it is never stale.
|
|
|
|
## Something is broken
|
|
|
|
- Server: [OPERATE-WINDOWS](OPERATE-WINDOWS.md), then `shopdb-admin.ps1 check -Json`.
|
|
- A PC or a bay: the symptom table at the end of
|
|
[FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
|
|
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
|
|
[BACKUP-RESTORE](BACKUP-RESTORE.md).
|
|
|
|
## I am moving a site to a different server or stack
|
|
|
|
[MIGRATE-TOPOLOGY](MIGRATE-TOPOLOGY.md) - Windows/IIS to Docker, Docker to a new
|
|
host, and back. The data moves cleanly; the URL the fleet points at is the work.
|