From 507aa8b23b38e3c77cff01b956aafa972fbe6a99 Mon Sep 17 00:00:00 2001 From: Julian Cuni Date: Fri, 1 May 2026 21:29:39 +0200 Subject: [PATCH] Add Docker image facts and Phase 1 scaffold decisions documentation --- .../directus-devops-architect/MEMORY.md | 5 +++++ .../project_phase1_scaffold.md | 19 +++++++++++++++++++ .../reference_directus_image.md | 18 ++++++++++++++++++ .../reference_timescaledb_ha.md | 16 ++++++++++++++++ 4 files changed, 58 insertions(+) create mode 100644 .claude/agent-memory/directus-devops-architect/MEMORY.md create mode 100644 .claude/agent-memory/directus-devops-architect/project_phase1_scaffold.md create mode 100644 .claude/agent-memory/directus-devops-architect/reference_directus_image.md create mode 100644 .claude/agent-memory/directus-devops-architect/reference_timescaledb_ha.md diff --git a/.claude/agent-memory/directus-devops-architect/MEMORY.md b/.claude/agent-memory/directus-devops-architect/MEMORY.md new file mode 100644 index 0000000..cfe3803 --- /dev/null +++ b/.claude/agent-memory/directus-devops-architect/MEMORY.md @@ -0,0 +1,5 @@ +# Agent Memory Index + +- [Directus image facts](reference_directus_image.md) — directus/directus:11.17.4 confirmed on Docker Hub; Alpine-based (node:22-alpine); runs as user `node`; CMD is `node cli.js bootstrap && pm2-runtime start ecosystem.config.cjs` +- [TimescaleDB-HA image facts](reference_timescaledb_ha.md) — timescale/timescaledb-ha:pg16-latest includes PostGIS by default; PGDATA=/pgdata (not /var/lib/postgresql/data); env vars: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB +- [Phase 1 scaffold decisions](project_phase1_scaffold.md) — key implementation decisions made during task 1.1 (image pins, volume paths, entrypoint command, apk package name) diff --git a/.claude/agent-memory/directus-devops-architect/project_phase1_scaffold.md b/.claude/agent-memory/directus-devops-architect/project_phase1_scaffold.md new file mode 100644 index 0000000..ac80f5e --- /dev/null +++ b/.claude/agent-memory/directus-devops-architect/project_phase1_scaffold.md @@ -0,0 +1,19 @@ +--- +name: Phase 1 task 1.1 scaffold decisions +description: Implementation decisions made during Phase 1 task 1.1 (project scaffold) for trm/directus +type: project +--- + +# Phase 1 task 1.1 — project scaffold decisions + +**Why:** These are non-obvious deviations from the task spec that future task implementers need to know. + +- **entrypoint.sh calls `node cli.js bootstrap` then `exec pm2-runtime start /directus/ecosystem.config.cjs`**, not `exec /directus/cli.js start`. The `bootstrap` step is idempotent and required for admin user creation. pm2-runtime provides crash recovery. +- **`postgresql16-client` is pre-installed in the Dockerfile via `apk add --no-cache postgresql16-client`**. This allows task 1.2's `apply-db-init.sh` to use `psql` without adding it later. Alpine 3.20 uses version-specific package names (no generic `postgresql-client`). +- **Volume mount for db service is `/pgdata`**, not `/var/lib/postgresql/data`. The `timescaledb-ha` image sets `PGDATA=/pgdata`. +- **`directus-uploads` named volume** maps to `/directus/uploads` in the directus service. No uploads use-case in Phase 1, but declared now to avoid volume-mount pain later. +- **`KEY` and `SECRET` in compose have no default** — blank env var means Directus will fail loudly at boot, which is the right behavior. +- **`packageManager` field omitted from package.json** because the local pnpm version (10.x) doesn't match what the task spec implied (9.x). pnpm 10 is backward-compatible. +- **Dockerfile is single-stage in Phase 1.** Multi-stage build with a Node builder for extensions lands in Phase 5. + +**How to apply:** Read this before implementing tasks 1.2–1.7 to avoid re-discovering these facts. diff --git a/.claude/agent-memory/directus-devops-architect/reference_directus_image.md b/.claude/agent-memory/directus-devops-architect/reference_directus_image.md new file mode 100644 index 0000000..5853957 --- /dev/null +++ b/.claude/agent-memory/directus-devops-architect/reference_directus_image.md @@ -0,0 +1,18 @@ +--- +name: Directus Docker image facts +description: Key facts about directus/directus:11.17.4 needed when extending or wrapping the image +type: reference +--- + +# Directus Docker image facts + +- **Pinned tag**: `directus/directus:11.17.4` — confirmed to exist on Docker Hub (pushed 2026-04-30). +- **Base image**: `node:22-alpine` (Alpine Linux). Use `apk add` for additional packages. +- **Non-root user**: The upstream image runs as user `node`. Our Dockerfile switches to `USER root` for apk/chmod, then drops back with `USER node`. +- **Working directory**: `/directus` +- **Upstream CMD** (not ENTRYPOINT): `node cli.js bootstrap && pm2-runtime start ecosystem.config.cjs` + - `node cli.js bootstrap` — idempotent DB init + admin user creation from ADMIN_EMAIL/ADMIN_PASSWORD. Safe to run every container start. + - `pm2-runtime start ecosystem.config.cjs` — starts Directus under PM2; handles crash recovery and signal forwarding. +- **Port**: 8055 +- **psql client package** on Alpine: `postgresql16-client` (version-specific; no generic `postgresql-client` on Alpine 3.20). +- **Entrypoint override**: Our `entrypoint.sh` must call `node /directus/cli.js bootstrap` then `exec pm2-runtime start /directus/ecosystem.config.cjs` to replicate upstream behavior. Do NOT just call `node /directus/cli.js start` — that skips pm2. diff --git a/.claude/agent-memory/directus-devops-architect/reference_timescaledb_ha.md b/.claude/agent-memory/directus-devops-architect/reference_timescaledb_ha.md new file mode 100644 index 0000000..97c31a0 --- /dev/null +++ b/.claude/agent-memory/directus-devops-architect/reference_timescaledb_ha.md @@ -0,0 +1,16 @@ +--- +name: TimescaleDB-HA Docker image facts +description: Key facts about timescale/timescaledb-ha needed for compose and CI configuration +type: reference +--- + +# TimescaleDB-HA Docker image facts + +- **Image used**: `timescale/timescaledb-ha:pg16-latest` +- **PostGIS**: Included by default in all (non-oss) tags. The `-oss` suffix variants ship only OSS-licensed extensions (PostGIS is Apache-licensed, included even in `-oss`). The GitHub README confirms: "By default, the Docker image contains many extensions, including TimescaleDB and PostGIS." +- **`-all` suffix meaning**: Contains multiple Postgres major versions in one image (e.g. pg13+pg14+pg15). NOT about extra extensions. Not needed for TRM. +- **PGDATA directory**: `/pgdata` — set via `PGDATA=/pgdata` env var. NOT the standard `/var/lib/postgresql/data`. Volume mounts must target `/pgdata`. +- **Environment variables**: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` (same as official postgres image). +- **Healthcheck**: `pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB` (double-$ in compose YAML to escape interpolation; the container sees single $ at runtime). +- **Compatible with `CREATE EXTENSION postgis`**: Yes, binaries present. +- **Compatible with `CREATE EXTENSION timescaledb`**: Yes, it's the whole point of the image.