46 lines
4.3 KiB
Markdown
46 lines
4.3 KiB
Markdown
# DockDeck architecture
|
|
|
|
## Runtime
|
|
|
|
DockDeck is one deployable Node.js process. Fastify owns the REST API and serves the compiled React client in production. React/Vite provides the development UI. SQLite is mounted at `/data`; Drizzle ORM owns typed reads and writes while a small idempotent SQL migration creates the first schema before Fastify starts.
|
|
|
|
```text
|
|
Browser → Fastify API → domain rules → Drizzle → SQLite
|
|
↘ discovery service → AppOps inventory (GET only)
|
|
→ Unraid XML/runtime mounts (read only)
|
|
→ NPM API (read only, optional)
|
|
```
|
|
|
|
## Trust boundaries
|
|
|
|
- The `dockdeck` container never receives `/var/run/docker.sock`.
|
|
- The standard deployment is exactly one `DockDeck` container. A separate `dockerproxy` exists only in the optional fallback overlay; there it is private, has `POST=0` and disables all mutation families.
|
|
- Unraid templates are mounted read-only.
|
|
- NPM, Gitea and provider credentials exist only as server-side process environment. Values entered in Settings are persisted in the permission-restricted environment file and remain excluded from API responses, SQLite and JSON exports.
|
|
- Fastify validates every user-controlled mutation with Zod. External integration errors are reduced to non-sensitive connection states.
|
|
- New discoveries are inserted with `visible=false`. Subsequent syncs update runtime fields but preserve user choices and overrides.
|
|
- A DockDeck-only app removal records the technical name in `removed_apps`; later discovery ignores that name and never calls a Docker mutation endpoint.
|
|
|
|
## Modules
|
|
|
|
- `src/shared`: Zod contracts and pure URL/search/matching/sorting rules.
|
|
- URL resolution prefers an explicit `br0` LAN address, then the configured Unraid host, and uses a single unambiguous published TCP port when template metadata is stale.
|
|
- Dashboard search is a derived client index over the latest payload, so renames, removals, category changes and URL changes require no separate search persistence.
|
|
- `src/server/database.ts`: persistence, migration, import/export and user preference invariants.
|
|
- Widget layout is stored as validated size/content, metric order/visibility/style, statistic limit, warning and chart fields on app and preference records. Legacy rows receive safe standard/all-content defaults; version 1 backups remain compatible because added backup fields are optional on import.
|
|
- `src/server/integrations`: read-only external adapters, provider capability metadata and deterministic mocks. Provider URLs default to an already discovered local app origin; explicit environment overrides remain available. Provider recognition is token-based and excludes known support-container roles.
|
|
- `src/server/integrations/unraid-status.ts`: parseert een minimale read-only view van Unraid runtime- en hwmondata naar array-, parity-, opslag-, temperatuur- en optionele UPS-metrics.
|
|
- Provideradapters bewaren alleen de laatst succesvolle gereduceerde metricresponse en een korte tijdreeks in procesgeheugen; geen van beide overleeft een procesrestart.
|
|
- `src/server/app.ts`: narrow REST surface; no Docker control routes.
|
|
- `src/client`: accessible responsive UI and design tokens.
|
|
|
|
## Layout and offline model
|
|
|
|
Widgetvolgorde staat los van apptegelvolgorde. App- en hostrecords bewaren hun eigen volgorde; layoutpresets bevatten alleen presentatievelden, inclusief metricselectie, value/gauge/progress, waarschuwing en lijn-/vlak-/staafgrafiek. Provider- en hosthistoriek bevat maximaal zestig punten per numerieke reeks en blijft uitsluitend in procesgeheugen. Het toepassen van een preset kan geen appzichtbaarheid, navigatie-URL, credential of Dockerstaat wijzigen.
|
|
|
|
De serviceworker cachet alleen statische applicatieshellassets. Requests onder `/api/` worden volledig overgeslagen, zodat offline content nooit als actuele runtime- of providerdata wordt gepresenteerd.
|
|
|
|
## Failure behavior
|
|
|
|
Saved data is always returned independently of integration health. A failed AppOps inventory, missing Unraid mount or unavailable NPM instance produces a degraded integration card/banner without blocking navigation. Polling runs only while the browser tab is visible. AppOps inventory is read immediately; its slower all-container resource sample refreshes in the background so it cannot delay navigation.
|