Files

T

julian e22d9d489a Tasks 1.6 + 1.7 — schema tooling + real entrypoint flow

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.

2026-05-02 09:40:53 +02:00

1.9 KiB

Raw Permalink Blame History

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:

Edit the schema in the Directus admin UI (local dev stack).
Run pnpm run schema:snapshot from the directus/ repo root.
Review the diff in snapshots/schema.yaml.
Commit and open a PR.

How schema.yaml is applied

entrypoint.sh calls scripts/schema-apply.sh at every container boot. The apply script:

Skips silently if schema.yaml does not exist or is empty (safe for first-boot before any collections are defined).
Runs a dry-run preview (directus schema apply --dry-run) and prints the diff to container logs.
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

1.9 KiB Raw Permalink Blame History