directus/.planning/phase-1-slice-1-schema/07-image-and-dockerfile.md

Task 1.7 — Image build & entrypoint

Phase: 1 — Slice 1 schema + deploy pipeline Status: ⬜ Not started Depends on: 1.2, 1.3, 1.6 (need the runner, migrations, and snapshot tooling all in place) Wiki refs: docs/wiki/entities/directus.md (Schema management section)

Goal

Build a production-ready Directus image that bakes in the snapshot, db-init migrations, extensions directory, and entrypoint script. Replace the placeholder entrypoint from 1.1 with the real boot sequence: db-init → schema apply → directus start.

Deliverables

• Dockerfile (replacing the placeholder from 1.1):

  FROM directus/directus:11.5.1   # pin specific patch version
  
  USER root
  RUN apk add --no-cache postgresql16-client bash coreutils
  USER node
  
  COPY --chown=node:node snapshots/  /directus/snapshots/
  COPY --chown=node:node db-init/    /directus/db-init/
  COPY --chown=node:node extensions/ /directus/extensions/
  COPY --chown=node:node scripts/    /directus/scripts/
  COPY --chown=node:node entrypoint.sh /directus/entrypoint.sh
  RUN chmod +x /directus/entrypoint.sh /directus/scripts/*.sh
  
  ENTRYPOINT ["/directus/entrypoint.sh"]
  

  Adjust apk / apt-get based on the upstream image's distro. postgresql-client is required for psql in the db-init runner.
• entrypoint.sh:

  #!/usr/bin/env bash
  set -euo pipefail
  
  echo "[entrypoint] running db-init"
  /directus/scripts/apply-db-init.sh
  
  echo "[entrypoint] applying Directus schema snapshot"
  /directus/scripts/schema-apply.sh
  
  echo "[entrypoint] starting Directus"
  exec /directus/cli.js start
  

  (Verify /directus/cli.js start is the correct upstream command for the pinned version. Some versions use node /directus/server.js.)
• Update compose.dev.yaml so the dev image uses the same Dockerfile (no special path in dev). The local image has identical boot semantics to prod — only env vars differ.

Specification

• Pin the Directus version exactly (e.g. 11.5.1, not 11). Version bumps land via PR.
• Layer ordering for cache friendliness.
  1. FROM + apk install (rarely changes).
  2. COPY scripts/ (changes occasionally).
  3. COPY entrypoint.sh (rarely changes).
  4. COPY db-init/ (changes per migration PR).
  5. COPY snapshots/ (changes per schema PR — most volatile).
  6. COPY extensions/ (Phase 5+). Putting the most-changed layer last maximizes cache reuse for the rest.
• USER node for runtime (matches upstream image's non-root convention).
• Health check. Add a HEALTHCHECK instruction calling wget -qO- http://localhost:8055/server/ping (or the upstream's health endpoint), with sensible interval/timeout. Useful in compose and Portainer.
• Entrypoint failure modes. If db-init fails → exit, container restarts (Docker will retry). If schema apply fails → same. Both failures should produce clear log lines so an operator looking at Portainer logs can diagnose.
• No EXPOSE change — the upstream image already exposes 8055.
• No ENV overrides for Directus runtime config in the Dockerfile — that's the deployer's concern via env vars at runtime.

Acceptance criteria

• docker build -t trm-directus:dev . succeeds.
• Image size is reasonable (< 600 MB; upstream image + tooling).
• Booting against a fresh Postgres: db-init applies all three migrations, schema apply creates 12 collections, Directus starts and serves on :8055.
• Re-booting against the same Postgres (warm DB): db-init reports "0 applied, 3 skipped", schema apply reports "no changes", Directus starts.
• Killing Postgres mid-db-init → container exits non-zero with clear error in logs.
• Killing Postgres mid-schema-apply → container exits non-zero with clear error in logs.
• HEALTHCHECK reports "healthy" once Directus is serving.
• compose.dev.yaml directus service uses the local Dockerfile build and works end-to-end (pnpm dev:reset → fresh boot → admin UI loads).

Risks / open questions

• Upstream image distro. Directus's official image has used both Alpine and Debian-based bases over the years. Verify the current 11.x base and adjust apk vs apt-get accordingly.
• /directus/cli.js start path. Confirm against the upstream Dockerfile / docs for the pinned version. Bake the right command into entrypoint.sh.
• Permissions on /directus/snapshots/ etc. If the upstream user is node (uid 1000), the --chown=node:node flag is right. Verify with docker run --rm trm-directus:dev id.

Done

Pending commit by user. entrypoint.sh replaced with production boot flow 2026-05-01.

Deliverables produced:

• entrypoint.sh — full boot flow: db-init → schema apply → bootstrap → pm2-runtime start. Mode 100755 preserved.

Scope boundary honored:

• Only entrypoint.sh was modified. Dockerfile, compose.dev.yaml, package.json, apply-db-init.sh, and everything under scripts/, db-init/, and snapshots/ were untouched (parallel agent boundary for task 1.6).

Deviations from task 1.7 spec:

The task spec (07-image-and-dockerfile.md) shows a naive entrypoint with exec /directus/cli.js start as the final command. This was superseded by the implementation brief's explicit requirement (and task 1.1 Done section) to use node /directus/cli.js bootstrap && pm2-runtime start /directus/ecosystem.config.cjs — the upstream image's actual CMD. The final entrypoint:

1. Calls bootstrap as a discrete step 3 (after schema apply), then
2. Uses exec pm2-runtime start /directus/ecosystem.config.cjs as step 4.

This matches the ROADMAP design rule #3 apply order and preserves pm2's crash recovery and signal handling. exec replaces the bash process so SIGTERM from docker stop reaches pm2 directly without traversal through bash.

Static acceptance criteria (passed):

• File path: C:\Users\Administrator\projects\trm\directus\entrypoint.sh
• Shebang: #!/usr/bin/env bash
• set -euo pipefail present (line 22)
• log() helper uses printf — no trailing newline issues
• Apply order: db-init (1/4) → schema apply (2/4) → bootstrap (3/4) → pm2-runtime (4/4)
• exec pm2-runtime — bash process replaced; signals reach pm2 directly
• File mode: 100755 confirmed via git ls-files -s entrypoint.sh before and after staging

Parallel agent status (task 1.6):

scripts/schema-apply.sh was NOT present when this task ran — only scripts/apply-db-init.sh and scripts/schema-snapshot.sh existed in scripts/. Step 2/4 of the entrypoint calls /directus/scripts/schema-apply.sh. With set -euo pipefail, a missing script causes bash to exit non-zero at that line before attempting execution (the shell resolves the command, finds it executable, then the kernel exec fails with ENOENT → bash reports the error and exits 127). This means the full boot sequence cannot be live-tested until task 1.6's schema-apply.sh lands. The implementation is correct; the missing dependency is a parallel-agent timing issue, not a bug.

Acceptance criteria — live testing deferred:

Live acceptance criteria (Docker boot, curl health check, restart verification) cannot be completed until scripts/schema-apply.sh is produced by task 1.6. Re-run the full acceptance suite after both task 1.6 and 1.7 PRs land:

• docker compose -f compose.dev.yaml down -v
• docker compose -f compose.dev.yaml build
• docker compose -f compose.dev.yaml up -d
• Watch for: [entrypoint] step 1/4 → [db-init] output → [entrypoint] step 2/4 → schema-apply log → [entrypoint] step 3/4 → bootstrap log → [entrypoint] step 4/4 → PM2 startup → server at :8055
• curl http://localhost:8055/server/health → 200
• docker compose -f compose.dev.yaml restart directus → clean re-boot with "already initialized" paths

Live-verification result (2026-05-01) — all four steps fired in order, server up at :8055:

[entrypoint] step 1/4: db-init                    → 3 applied, 0 skipped
[entrypoint] step 2/4: directus schema apply      → snapshot not found, skipping (correct for Phase 1)
[entrypoint] step 3/4: directus bootstrap         → system tables created, first admin role + user added
[entrypoint] step 4/4: directus start (pm2-runtime)
PM2 log: App [directus:0] online
Server started at http://0.0.0.0:8055

Bug fix during live verification: the parallel schema-apply.sh invoked directus as if it were on PATH. The upstream image does NOT expose directus on PATH — invocation is via node /directus/cli.js. See task 1.6's Done section for the fix detail. Entrypoint itself was unaffected; only schema-apply.sh needed the change.

Phase 5 follow-up note (not blocking Phase 1):

Boot logs include WARN: Collection "positions" doesn't have a primary key column and will be ignored — three times (during bootstrap migrations + once at startup). Directus auto-discovers tables in the public schema and tries to register them as collections, but skips ones without a PRIMARY KEY constraint. The positions table uses UNIQUE INDEX (device_id, ts) instead of a PK (matching processor's pattern, see task 1.3 Done). Result: positions is not auto-registered as a Directus collection, so the cross-plane operator workflow (operator flips faulty flag via admin UI) cannot use the auto-collection path.

This is acceptable for Phase 1 (no operator UI yet). Phase 5 (custom extensions) needs a different mechanism for the faulty-flag workflow:

• Option A: a custom Directus endpoint (POST /positions/:id/flag-faulty) that performs the UPDATE directly via the database service. Bypasses Directus's collection abstraction; thin wrapper around SQL.
• Option B: register positions in directus_collections manually with a composite primary key configured (device_id, ts). Some Directus versions support this; verify against 11.17.4.
• Option C: add an id BIGSERIAL PRIMARY KEY surrogate column to positions. Cleanest for Directus, but introduces a column processor doesn't write and slightly increases per-row storage.

Phase 5's task file should pin one of these options before extension work begins.