# 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. This page covers the handful of paths people actually arrive on, and the warnings worth reading before you pick one. Anything not here is in [INDEX](INDEX.md), which lists every task, the smallest page set that answers it, and how many lines that costs. Do not read both: find your row in one of them and go. Each path below is the shortest correct one, not everything that exists. ## I am standing up ShopDB at a new site **Docker is the path, and the only one this line ships.** 1. [DEPLOY](DEPLOY.md) - clone to first admin on Docker at a connected site. No internet at all: [DEPLOY-AIRGAP](DEPLOY-AIRGAP.md). 2. Then load the site's data: [CSV-IMPORT](CSV-IMPORT.md) from spreadsheets, or [IMPORT-API](IMPORT-API.md) if there is a source database to script against. 3. Later versions: [UPGRADE](UPGRADE.md), after [BACKUP-RESTORE](BACKUP-RESTORE.md). Just want to look at a build without standing one up? [DEV-BUILD-TEST](DEV-BUILD-TEST.md) pulls a prebuilt stack onto a Windows box with Docker Desktop. ## 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. It ends with a symptom table that says which piece to open when a bay misbehaves. [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md) has worked examples for Intune and for manual installation, and says where each artifact comes from. ShopDB serves the data these tools read; getting them onto a bay is your site's configuration tooling, not ShopDB's. ## I am writing a plugin 1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run. 2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative, and the one page every other plugin page defers to. 3. [PLUGIN-GUIDE](PLUGIN-GUIDE.md) - the conventions every bundled plugin follows and the traps that have actually bitten someone. Walk its checklist before you call a plugin done. Read `plugins/warranty/` beside it: it is the smallest bundled plugin that exercises most of the contract. If it lives in its own repository, [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md), and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose a version pin. ## I am integrating with the API 1. [llms.txt](llms.txt) (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. [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md) if you are feeding data in from a PC, and [COLLECTOR-AUTH](COLLECTOR-AUTH.md) for how that PC proves who it is. ## Something is broken - Server: `docker compose logs api`, then the health checks at the end of [DEPLOY](DEPLOY.md). - A PC or a bay: the symptom table at the end of [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md). - An upgrade that went in and then misbehaved: [UPGRADE](UPGRADE.md), with [BACKUP-RESTORE](BACKUP-RESTORE.md) if data has to come back too. ## I am trying to understand why something is built this way [The ADRs](adr/README.md). They are the decision record, they say what was rejected and why, they say whether each decision still holds, and they are the fastest way to avoid relitigating a settled question. One ADR answers one question; nothing there is a prerequisite for anything else. ## Three things people do not know exist - [GUIDES](GUIDES.md) - procedures live in ShopDB itself, as typed blocks with checkboxes a technician ticks as they work, instead of a Word document on a share. - [SECURE-SEND](SECURE-SEND.md) - a one-view expiring link for handing somebody a password. Read its "Before anybody relies on it" section first: there is one thing to test at your site before the first real credential goes through it. - [DEPENDENCY-SECURITY](DEPENDENCY-SECURITY.md) - every release installs a full inventory of third-party components, so a security team can answer "are we exposed to this advisory" without access to anything here. ## Before you read anything else here Every page opens with a `docmeta` comment saying what it is for and whether it is still current. A page marked `legacy` is true but superseded, and a page marked `historical` is a record of a finished migration or a proposal. Neither is guidance. [INDEX](INDEX.md) lists all of them in one place, at the bottom, so you never have to read one to find out it does not apply to you.