julian
e22d9d489a
Two parallel tasks landing together. The boot pipeline is now wired end-to-end: db-init → schema apply → directus bootstrap → pm2-runtime. Live-verified by booting a fresh compose stack to a serving Directus admin UI on :8055. Task 1.6 — snapshot tooling: - scripts/schema-snapshot.sh — host-side, dev-time. Verifies docker is on PATH and the directus compose service is running, runs `node /directus/cli.js schema snapshot --yes` inside the container, copies the YAML out to ./snapshots/schema.yaml. Used after admin-UI schema changes to capture the new state for git commit. - scripts/schema-apply.sh — image-side, boot-time. Reads /directus/snapshots/schema.yaml, runs a dry-run preview, then applies. Gracefully skips when the snapshot is absent or whitespace- only (Phase 1 first-boot path before tasks 1.4/1.5 produce collections). SNAPSHOT_PATH env var override for CI flexibility. - snapshots/README.md — lifecycle doc; warns against hand-editing. Task 1.7 — real entrypoint flow: - entrypoint.sh rewritten from Phase 1.1's placeholder to the 4-step boot per ROADMAP design rule #3: 1/4 db-init → /directus/scripts/apply-db-init.sh 2/4 schema apply → /directus/scripts/schema-apply.sh 3/4 directus bootstrap → node /directus/cli.js bootstrap 4/4 directus start → exec pm2-runtime start ecosystem.config.cjs set -euo pipefail halts boot on any step's non-zero exit. Each step emits a [entrypoint] log marker so an operator reading container logs sees which step failed. Bug found and fixed during live verification: - Both 1.6 scripts initially called bare `directus schema ...` as if the CLI were on PATH. Upstream directus/directus:11.17.4 does NOT expose `directus` on PATH — invocation is via `node /directus/cli.js`, same pattern as the entrypoint's bootstrap step. Both scripts corrected. Also added -T to docker compose exec in schema-snapshot.sh so the script works in non-TTY contexts (CI). Phase 5 follow-up (non-blocking) flagged in 07's Done section: Directus warns "Collection 'positions' doesn't have a primary key column and will be ignored". The positions table uses UNIQUE INDEX (device_id, ts) matching processor's pattern, not a PK constraint. Means positions is not auto-registered as a Directus collection — fine for Phase 1, but the operator faulty-flag workflow will need a custom endpoint or manual collection registration in Phase 5. ROADMAP marks 1.6 + 1.7 done. Phase 1 progress: 5/9 tasks complete (1.1, 1.2, 1.3, 1.6, 1.7); 1.4, 1.5, 1.8, 1.9 remain.
58 lines
1.9 KiB
Markdown
58 lines
1.9 KiB
Markdown
# snapshots/
|
|
|
|
This directory holds the Directus schema snapshot for the TRM directus service.
|
|
|
|
## What lives here
|
|
|
|
- `schema.yaml` — the authoritative Directus schema: all collections, fields,
|
|
and relations. Committed to git and applied at every container boot.
|
|
- `.gitkeep` — present until the first real snapshot lands (task 1.4/1.5/1.6).
|
|
Once `schema.yaml` is committed, `.gitkeep` is no longer needed and can be
|
|
removed.
|
|
|
|
## Do NOT hand-edit schema.yaml
|
|
|
|
`schema.yaml` is generated programmatically. Its format is tightly coupled to
|
|
the version of Directus that produced it. Hand-editing produces subtle breakage
|
|
(key-order drift, missing internal fields, format violations) that `schema apply`
|
|
will reject or silently misinterpret.
|
|
|
|
**The only supported workflow for schema changes is:**
|
|
|
|
1. Edit the schema in the Directus admin UI (local dev stack).
|
|
2. Run `pnpm run schema:snapshot` from the `directus/` repo root.
|
|
3. Review the diff in `snapshots/schema.yaml`.
|
|
4. Commit and open a PR.
|
|
|
|
## How schema.yaml is applied
|
|
|
|
`entrypoint.sh` calls `scripts/schema-apply.sh` at every container boot.
|
|
The apply script:
|
|
|
|
1. Skips silently if `schema.yaml` does not exist or is empty (safe for
|
|
first-boot before any collections are defined).
|
|
2. Runs a dry-run preview (`directus schema apply --dry-run`) and prints the
|
|
diff to container logs.
|
|
3. Applies the snapshot (`directus schema apply --yes`). This is idempotent —
|
|
Directus computes the diff against the live DB and applies only what has
|
|
changed. A clean re-deploy where the DB already matches the snapshot is a
|
|
no-op.
|
|
|
|
## Snapshot/apply lifecycle
|
|
|
|
```
|
|
edit in admin UI
|
|
│
|
|
▼
|
|
pnpm run schema:snapshot ←── writes snapshots/schema.yaml
|
|
│
|
|
▼
|
|
git commit + PR
|
|
│
|
|
▼
|
|
CI: directus schema apply --dry-run (fails PR if snapshot is broken)
|
|
│
|
|
▼
|
|
container boot: entrypoint.sh → schema-apply.sh → directus start
|
|
```
|