96df19702e
DEPLOY-WINDOWS-IIS was a second copy of the manual IIS procedure that had diverged from the first: a different MySQL version (8.0, which reached end of life in April), a different port, a different plugin list, and a profile file that does not exist. Two runbooks for one procedure means a reader follows whichever they found, and one of them was wrong. INSTALL-WINDOWS-IIS covers everything it did plus a preflight step and the subpath method, so the one section it uniquely had - redeploying a hand-built server - is folded in there, with the plugin-chain step it was missing and a note to back up first, and the duplicate is gone. Everything that pointed at it now points at the survivor. Three ADR statuses said something untrue. ADR-013 said PROPOSED while half of it had shipped and ADR-014 had been accepted on top of it. A decision that has been implemented and depended upon is not proposed, and leaving one that way devalues every other status in the index. The catalog half is still unbuilt, which is the ordinary state of an accepted decision: accepted means settled, not delivered. ADR-016 said ACCEPTED for a design where nothing is built - the endpoint and permissions it describes do not exist, so a reader goes looking for them. The status stands, because the decision does; the header now says so plainly and points at where today's credentials actually live. ADR-003 and ADR-004 were ACCEPTED with their own Decision lines still opening "**PROPOSED:**", which reads as though the decision was never taken. And the dashboard proposal carried Status: ACCEPTED, which belongs to a decision record. A proposal is a proposal; the contract it produced is the ADR.
65 lines
2.8 KiB
Markdown
65 lines
2.8 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.
|
|
|
|
**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 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](LLM-GUIDE.md) (`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 am trying to understand why something is built this way
|
|
|
|
[The ADRs](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).
|