The runner host typically has another Postgres listening on 5432
(local dev stack, stage instance, etc.), which made the services:
postgres container fail at start with "port already allocated."
Remap the host-side port from 5432:5432 to 15432:5432. The service
container still listens on 5432 internally; only the runner host
binding changes. Dry-run's DB_PORT updated to 15432 to match.
--network host semantics preserved: DB_HOST=localhost reaches the
service on the runner's loopback at the new port.
Why we still need a Postgres container at all: the dry-run gate
applies db-init/*.sql migrations and the directus schema snapshot
against a real DB to catch breakage before pushing the image. No
Postgres = no validation = the gate is bypassed.
Inline comment in the workflow now explains the choice; task spec's
Done section captures the correction so future readers don't
re-discover this.
.gitea/workflows/build.yml builds the directus image on path-filtered
pushes to main and validates the boot pipeline against a throwaway
Postgres before pushing the image to the registry. The dry-run is the
gate that catches snapshot drift, broken db-init scripts, or
incompatible schema changes before they reach stage.
Workflow shape (mirrors processor's CI but tailored to Directus):
- Path filter: snapshots/, db-init/, extensions/, scripts/,
entrypoint.sh, Dockerfile, the workflow file itself.
Docs-only commits (.planning/, README.md, compose.dev.yaml,
package.json) do NOT trigger CI.
- Throwaway Postgres via services: block, pinned to the same
timescale/timescaledb-ha:pg16.6-ts2.17.2-all tag as compose.dev.yaml.
- Plain `docker build` (NOT build-push-action) so the image stays in
the local daemon for the subsequent docker run dry-run.
- Dry-run: --network host + --entrypoint bash to override the upstream
entrypoint and run only apply-db-init.sh && schema-apply.sh.
Skips bootstrap and pm2-runtime — the schema apply is the gate.
- Two image tags: :main (mutable) and :<sha> (immutable).
- Optional Portainer webhook gated on secret presence; curl -fsS so a
misconfigured URL fails the step explicitly.
Spec corrections folded in (the spec's draft had two contradictions
that would have failed at runtime):
1. DB_HOST=localhost (not 'postgres'). With --network host, service
containers are reachable on the runner's loopback by their port
mapping, NOT by service name. Service-name resolution requires the
default bridge network; --network host overrides it.
2. health-retries 20 (not 10). timescaledb-ha:*-all does more init
work at boot than vanilla postgres; 50s isn't always enough.
Operator action required in the Gitea repo Settings before first run:
configure REGISTRY_USERNAME and REGISTRY_PASSWORD secrets (required for
push); optionally PORTAINER_WEBHOOK_URL (for auto-deploy).
Live verification deferred to first relevant commit. Documented in the
task spec's Done section: positive (clean snapshot → push succeeds)
and negative (malformed snapshot → halt before push) cases to validate
once CI runs.
ROADMAP marks 1.8 done. Phase 1 progress: 8/9 tasks complete (1.1–1.8);
only 1.9 (Rally Albania 2026 dogfood seed) remains before Phase 1 ships.
Phase 1 task 1.1 lands. Directus 11.17.4 boots locally end-to-end
against a TimescaleDB+PostGIS container; admin UI serves at :8055,
admin bootstrap from env vars works, named volumes preserve data
across down/up cycles.
Scaffold:
- Dockerfile — FROM directus/directus:11.17.4. Pre-installs
postgresql16-client (ahead of task 1.2's db-init runner needing psql).
Bakes in /directus/snapshots, /directus/db-init, /directus/scripts,
/directus/extensions, /directus/entrypoint.sh.
- compose.dev.yaml — db (timescale/timescaledb-ha:pg16.6-ts2.17.2-all)
+ directus (local build), healthchecks, named volumes
directus-pg-data + directus-uploads.
- entrypoint.sh — placeholder using upstream's actual flow
(node cli.js bootstrap && pm2-runtime start ecosystem.config.cjs);
the real db-init -> schema apply -> start wrapper lands in task 1.7.
- package.json — scripts-only (dev, dev:down, dev:reset,
schema:snapshot, schema:apply, db:init), no runtime deps.
- .env.example — sectioned, fully documented, KEY/SECRET marked
required with generation hints.
- .gitignore, .dockerignore — match the processor service conventions.
- snapshots/, db-init/, scripts/, extensions/ — empty with .gitkeep,
filled by later Phase 1 tasks (1.3, 1.6) and Phase 5.
Lessons locked in (against the empirical pnpm dev boot):
- timescale/timescaledb-ha:pg16-latest does NOT exist on Docker Hub.
Pin a concrete version (we used pg16.6-ts2.17.2-all).
- This image's data directory is /home/postgres/pgdata/data, not
/pgdata or /var/lib/postgresql/data. PGDATA env var and the volume
mount must both target it.
- The -all variant bundles PostGIS binaries but the extension is not
auto-created on the directus database; CREATE EXTENSION lands in
Phase 2 alongside the geofences/SLZs/waypoints collections.
- The upstream image's CMD is bootstrap + pm2-runtime, not a simple
cli.js start. Bypassing pm2 would lose crash recovery.
These corrections folded into 01-project-scaffold.md (deliverable line
+ Done section), 08-gitea-ci-dryrun.md (CI service tag), and the
inline comments in compose.dev.yaml so future implementers don't
re-discover them.
Status: ROADMAP marks 1.1 done, Phase 1 in progress, 1.2 next.
julian