torrust
diff --git a/‎Containerfile‎
Lines changed: 26 additions & 3 deletions b/‎Containerfile‎
Lines changed: 26 additions & 3 deletions
diff --git a/‎Makefile‎
Lines changed: 61 additions & 0 deletions b/‎Makefile‎
Lines changed: 61 additions & 0 deletions
diff --git a/‎adr/009-implementation-plan.md‎
Lines changed: 125 additions & 2 deletions b/‎adr/009-implementation-plan.md‎
Lines changed: 125 additions & 2 deletions
diff --git a/‎compose.override.yaml‎
Lines changed: 53 additions & 0 deletions b/‎compose.override.yaml‎
Lines changed: 53 additions & 0 deletions
@@ -35,8 +35,31 @@ RUN mkdir -p /app/share/torrust/default/database/; \
 FROM rust:slim-trixie AS jq_donor
 RUN apt-get update && \
     apt-get install -y --no-install-recommends jq && \
-    rm -rf /var/lib/apt/lists/* && \
-    mkdir -p /jq && \
+    rm -rf /var/lib/apt/lists/*
+# Pin jq's runtime shared-library set so a future donor-base
+# upgrade that drags in a new transitive dep fails the build
+# instead of producing a silently-broken runtime image. The
+# allow-list mirrors what the runtime stages COPY across
+# (libjq, libonig) plus libraries already present in the
+# `cc-debian13` runtime base (libc, libm, ld-linux, vdso).
+RUN set -eu; \
+    expected='libc.so.6 libjq.so.1 libm.so.6 libonig.so.5 ld-linux-x86-64.so.2 linux-vdso.so.1'; \
+    # ldd column 1 is sometimes a bare soname ("libc.so.6")
+    # and sometimes an absolute path ("/lib64/ld-linux-…").
+    # Reduce to basenames so the allow-list check is uniform.
+    actual="$(ldd /usr/bin/jq | awk '{print $1}' | sed 's|.*/||' | sort -u | tr '\n' ' ')"; \
+    for lib in $expected; do \
+      case " $actual " in *" $lib "*) ;; *) echo "ERROR: jq lost expected library: $lib" >&2; exit 1 ;; esac; \
+    done; \
+    for lib in $actual; do \
+      case " $expected " in *" $lib "*) ;; *) echo "ERROR: jq pulls unexpected library: $lib (allow-list: $expected)" >&2; exit 1 ;; esac; \
+    done
+# Stage jq + its two non-glibc shared libraries at
+# deterministic paths under `/jq/`. The `*-linux-gnu` glob
+# resolves to whichever multi-arch tuple the donor was
+# built for; re-staging under stable names lets the runtime
+# COPY directives stay tuple-agnostic.
+RUN mkdir -p /jq && \
     cp /usr/bin/jq /jq/jq && \
     cp -L /usr/lib/*-linux-gnu/libjq.so.1   /jq/libjq.so.1 && \
     cp -L /usr/lib/*-linux-gnu/libonig.so.5 /jq/libonig.so.5
@@ -227,7 +250,7 @@ ENV PATH=/usr/local/bin:/bin:/usr/bin:/sbin
 # §4.4 of the implementation plan — update both in the same
 # change.
 RUN ["/bin/busybox", "sh", "-c", \
-     "for a in sh adduser install mkdir dirname chown chmod tr mktemp cat printf rm echo grep; do \
+     "for a in sh adduser addgroup install mkdir dirname chown chmod tr mktemp cat printf rm echo grep; do \
         /bin/busybox ln -s busybox /bin/$a; \
       done && rm -f /tmp/.preflight-sentinel"]
 
 
@@ -0,0 +1,61 @@
+# Top-level developer / operator entry points for the
+# Compose split introduced by ADR-T-009 §8.3.
+#
+# Targets:
+#
+#   make up-dev   Plain `docker compose up`. Auto-loads
+#                 `compose.override.yaml`, applying the dev
+#                 sandbox extras (mailcatcher, permissive
+#                 credential defaults, tty allocation). No
+#                 validation — operators get whatever
+#                 defaults the override provides.
+#
+#   make up-prod  Production-shaped invocation. Validates
+#                 required credentials are set in the
+#                 environment before any container starts,
+#                 then runs `docker compose --file
+#                 $(COMPOSE_FILE) up -d --wait` with the
+#                 override excluded. Make propagates the
+#                 recipe's exit code, so a failed
+#                 healthcheck (`--wait`) or a missing
+#                 credential (`:?required`) surfaces as a
+#                 non-zero `make` exit.
+#
+# Validation logic uses POSIX `sh` with `set -u` and
+# explicit `: "$${VAR:?message}"` per required variable so
+# the file is dependency-free and shellcheck-clean.
+#
+# COMPOSE_FILE is overridable so acceptance tests (and
+# operators with a non-default layout) can point at an
+# alternate baseline without filesystem manipulation:
+#
+#   make up-prod COMPOSE_FILE=path/to/other.yaml
+#
+# Compose's own `COMPOSE_FILE` env var is ignored when
+# `--file` is set on the command line, so the make-variable
+# is the only reliable way to redirect the recipe.
+
+.PHONY: up-dev up-prod _validate-prod-env
+
+COMPOSE_FILE ?= compose.yaml
+
+up-dev:
+	docker compose up
+
+# NOTE: The MySQL check is name-coupled to the compose
+# service (`mysql:`). This is acceptable because it is
+# defence-in-depth only — the config probe (exit 3 on
+# empty connect_url) and the MySQL entrypoint (rejects
+# empty root password) are the authoritative gates.
+_validate-prod-env:
+	@sh -uc '\
+	  : "$${USER_ID:?required (numeric host UID owning ./storage)}" && \
+	  : "$${TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN:?required}" && \
+	  : "$${TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL:?required}" && \
+	  : "$${TORRUST_TRACKER_CONFIG_OVERRIDE_HTTP_API__ACCESS_TOKENS__ADMIN:?required}" && \
+	  if grep -q "^[[:space:]]*mysql:" $(COMPOSE_FILE); then \
+	    : "$${MYSQL_ROOT_PASSWORD:?required}"; \
+	  fi'
+
+up-prod: _validate-prod-env
+	docker compose --file $(COMPOSE_FILE) up -d --wait
@@ -21,7 +21,7 @@ re-litigated here — when in doubt, defer to the ADR.
 | 5     | Schema (D2)                        | Done        |
 | 6     | Config probe                       | Done        |
 | 7     | Entry-script contract              | Done        |
-| 8     | Compose split                      | Not started |
+| 8     | Compose split                      | Done        |
 | 9     | Documentation & audit (D8, D9)     | Not started |
 
 ## Phase Dependency Graph
@@ -698,7 +698,7 @@ ENV PATH=/usr/local/bin:/bin:/usr/bin:/sbin
 # preflight_gate carries for the BuildKit dependency edge;
 # it has no runtime purpose and should not ship.
 RUN ["/bin/busybox", "sh", "-c", \
-     "for a in sh adduser install mkdir dirname chown chmod tr mktemp cat printf rm echo; do \
+     "for a in sh adduser addgroup install mkdir dirname chown chmod tr mktemp cat printf rm echo; do \
         /bin/busybox ln -s busybox /bin/$a; \
       done && rm -f /tmp/.preflight-sentinel"]
 
@@ -951,6 +951,7 @@ applet symlinks — busybox `sh` provides them internally.
 |-----------|-----------------------------------------------------|
 | `sh`      | Entry script interpreter (`#!/bin/sh`)               |
 | `adduser` | §4.1 — create `torrust` user at first boot           |
+| `addgroup`| §4.1 — create `torrust` group before `adduser` so a downstream `install -g torrust` resolves the group |
 | `install` | `inst()` helper — seed config/database templates     |
 | `mkdir`   | Create volume subdirectories, auth-key dirs          |
 | `dirname` | §7.1 — resolve parent of auth-key and database paths |
@@ -2307,6 +2308,7 @@ dependency-free and shellcheck-clean.
 
   _validate-prod-env:
   	@sh -uc '\
+  	  : "$${USER_ID:?required (numeric host UID owning ./storage)}" && \
   	  : "$${TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN:?required}" && \
   	  : "$${TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL:?required}" && \
   	  : "$${TORRUST_TRACKER_CONFIG_OVERRIDE_HTTP_API__ACCESS_TOKENS__ADMIN:?required}" && \
@@ -2318,6 +2320,15 @@ dependency-free and shellcheck-clean.
   # defence-in-depth only — the config probe (exit 3 on
   # empty connect_url) and the MySQL entrypoint (rejects
   # empty root password) are the authoritative gates.
+  #
+  # NOTE: `USER_ID` is required because `compose.yaml`
+  # references `${USER_ID}` with no default (it is an
+  # operator-supplied numeric selector, not a credential
+  # and not an environment-coupled hostname). An empty
+  # value would propagate to the entry script's
+  # `adduser -u ""` call and fail loudly inside the
+  # container; failing earlier in the wrapper matches the
+  # spirit of the §8.1 defence-in-depth contract.
 
   up-prod: _validate-prod-env
   	docker compose --file $(COMPOSE_FILE) up -d --wait
@@ -2355,6 +2366,105 @@ compositions pass `--file compose.yaml` explicitly.
 Describe the two files with a clear "for development" / "for
 deployment template" distinction.
 
+### 8.6 Bring-up addendum (issues surfaced & fixed inline)
+
+Phase 8 was validated end-to-end against `podman-compose
+1.5.0` / `podman 5.8.2` (as the closest available stand-in
+for `docker compose v2`'s additive override merge). The
+bring-up exposed five latent bugs in earlier phases that
+only surface when the full stack actually starts. All five
+were fixed in the same PR rather than deferred, since each
+would block any operator following the documented workflow.
+
+1. **Test binaries baking compile-time paths** (Phases 6, 7).
+   `packages/index-config-probe/tests/binary.rs` and
+   `packages/index-entry-script/tests/seed_sqlite.rs`
+   resolved the binary / shell-library under test via
+   `env!("CARGO_BIN_EXE_…")` and `CARGO_MANIFEST_DIR`.
+   Both bake the build-time path into the test executable
+   and break under cargo-nextest's archive →
+   `--extract-to` → `--target-dir-remap` flow used in the
+   container `test` stage. **Fix:** drive the contracts
+   through the library API (probe) and embed the shell
+   library at compile time via `include_str!` materialised
+   to a `tempfile` at run time (entry-script). Same model
+   as `packages/index-config/tests/shipped_samples.rs`.
+2. **Missing `addgroup` in the curated busybox applets**
+   (Phase 4 / 7). Distroless `cc-debian13` ships
+   `/etc/passwd` and `/etc/group`, but busybox
+   `adduser -D -u UID NAME` writes only `/etc/passwd` —
+   `getgrnam("torrust")` then fails, breaking the entry
+   script's `install -g torrust …` step with `unknown
+   group torrust`. **Fix:** add `addgroup` to the curated
+   symlink loop in the release runtime base, change the
+   entry script to `addgroup -g "$USER_ID" torrust`
+   followed by `adduser -D -s /bin/sh -u "$USER_ID" -G
+   torrust torrust`, and guard both with idempotent
+   `grep`-of-`/etc/{passwd,group}` checks so a container
+   restart is a no-op rather than a fatal exit under
+   `set -e`.
+3. **`jq` shipped without its shared libs** (Phase 2). The
+   `jq_donor` stage installed jq via `apt-get` but the
+   runtime stages copied only `/usr/bin/jq`; the binary
+   then aborted with `libjq.so.1: cannot open shared
+   object file` inside the lean `cc-debian13` runtime base.
+   **Fix:** copy `libjq.so.1` and `libonig.so.5` from the
+   donor alongside the binary, and add an `ldd`-based
+   allow-list assertion to the `jq_donor` stage so a future
+   donor-base upgrade that drags in a new transitive dep
+   fails the build instead of silently producing a broken
+   image. The allow-list is `libc.so.6 libjq.so.1
+   libm.so.6 libonig.so.5 ld-linux-x86-64.so.2
+   linux-vdso.so.1`; the parser strips path prefixes from
+   `ldd`'s column 1 so absolute paths
+   (`/lib64/ld-linux-…`) and bare sonames are treated
+   identically.
+4. **Empty-string env vars treated as configuration TOML**
+   (Phases 3, 8). `Info::from_env` called `env::var(…).
+   ok()` directly, which returns `Some("")` for an
+   exported-but-unset variable. The compose baseline's
+   `TORRUST_INDEX_CONFIG_TOML=${TORRUST_INDEX_CONFIG_TOML}`
+   then propagated an empty string into the container,
+   which the loader treated as a zero-byte TOML and
+   rejected with "Missing mandatory option:
+   logging.threshold". **Fix:** `Info::from_env` now
+   filters empty strings out of both `TORRUST_INDEX_CONFIG_TOML`
+   and `TORRUST_INDEX_CONFIG_TOML_PATH`, and `compose.yaml`
+   uses Compose's bare-name pass-through form
+   (`- TORRUST_INDEX_CONFIG_TOML`, no `=`) for those two
+   optional inline-TOML envs so an unset host var is
+   omitted entirely rather than forwarded as empty.
+5. **Unqualified Docker Hub image names** (Phase 8).
+   `mysql:8.0.45`, `dockage/mailcatcher:0.8.2`, and
+   `torrust/tracker:develop` all relied on a
+   short-name-resolution prompt that podman cannot honour
+   without a TTY (and that operators should not be relying
+   on regardless). **Fix:** fully qualify all three as
+   `docker.io/...` in `compose.yaml` /
+   `compose.override.yaml`. This is portable across both
+   docker and podman and immune to per-host
+   `unqualified-search-registries` configuration.
+6. **`USER_ID` missing from `_validate-prod-env`** (Phase 8).
+   `compose.yaml` references `${USER_ID}` with no default
+   (it is an operator-supplied numeric selector, not a
+   credential and not an environment-coupled hostname, so
+   the §8.1 bare-`${VAR}` rule does not strictly apply —
+   but neither does the `${VAR:-default}` selector
+   convention, since there is no safe cross-environment
+   default). Without validation, an unset `USER_ID`
+   propagated to the entry script's `adduser -u ""` call
+   and failed deep inside container start. **Fix:** add
+   `USER_ID` to the `_validate-prod-env` required list so
+   the wrapper fails fast with a clear message before any
+   container starts. The entry-script-side failure remains
+   the authoritative gate; this is defence-in-depth in the
+   same spirit as the credential checks.
+
+These inline fixes preserve the Phase 8 deliverable's scope
+(the compose split itself) while ensuring the documented
+`make up-dev` / `podman-compose up` flows actually reach a
+healthy `200 OK` on `:3001`.
+
 ---
 
 ## Phase 9 — Documentation & Audit (D8, D9 docs part)
@@ -2394,6 +2504,19 @@ consumers), the PEM+PATH mutual-exclusion enforcement
 `TORRUST_INDEX_DATABASE_DRIVER` (now a TOML-selection
 knob only, no longer a runtime database dispatcher).
 
+### 9.1.3 Add `mailcatcher` CI lint on `compose.yaml`
+
+Phase 8 §8.1 prescribed a CI lint that re-runs the
+`grep -nriE 'mailcatcher|MAILER|SMTP|smtp_'` audit against
+`compose.yaml` to catch accidental re-introduction of the
+dev sidecar into the production-shaped baseline. Land it
+as a workflow step (or a `make lint-compose` target wired
+into the existing CI pipeline) so the audit trail is
+enforced rather than reviewer-discretionary. The check
+must inspect `compose.yaml` only — the override file is
+*expected* to mention `mailcatcher` and matching it there
+would be a false positive.
+
 ### 9.2 Internal code audit for vendored `su-exec`
 
 Add `contrib/dev-tools/su-exec/AUDIT.md` with:
 
@@ -0,0 +1,53 @@
+# Dev sandbox extras for `compose.yaml`. Auto-loaded by
+# Compose v2 when present (i.e. by `docker compose up` and
+# `make up-dev`). Excluded by `make up-prod` via explicit
+# `--file compose.yaml`. See ADR-T-009 §8.2.
+#
+# What this file adds:
+#
+# - The `mailcatcher` sidecar (re-attached to `index` via
+#   long-form `depends_on`, which Compose v2 merges
+#   additively — short-form would silently replace the
+#   base's tracker/mysql dependencies).
+# - `tty: true` on `index` and `tracker` so interactive
+#   `docker attach` sessions get a sensible terminal.
+# - Permissive `${VAR:-default}` credential defaults so a
+#   plain `docker compose up` works without operator
+#   intervention. Production paths (`make up-prod`) bypass
+#   this file and rely on the validated bare-`${VAR}` form
+#   in the base.
+
+services:
+
+  index:
+    tty: true
+    environment:
+      # DEV-ONLY defaults — change for any public or production deployment.
+      - TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN=${TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN:-MyAccessToken}
+      - TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL=${TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL:-sqlite:///var/lib/torrust/index/database/index.sqlite3.db?mode=rwc}
+    # Long-form merge — extends the base's `tracker` / `mysql`
+    # dependencies rather than replacing them. See ADR-T-009 §8.2.
+    depends_on:
+      mailcatcher:
+        condition: service_started
+
+  tracker:
+    tty: true
+    environment:
+      # DEV-ONLY default — change for any public or production deployment.
+      - TORRUST_TRACKER_CONFIG_OVERRIDE_HTTP_API__ACCESS_TOKENS__ADMIN=${TORRUST_TRACKER_CONFIG_OVERRIDE_HTTP_API__ACCESS_TOKENS__ADMIN:-MyAccessToken}
+
+  mysql:
+    environment:
+      # DEV-ONLY credentials — change for any public or production deployment.
+      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD:-root_secret_password}
+      - MYSQL_USER=${MYSQL_USER:-db_user}
+      - MYSQL_PASSWORD=${MYSQL_PASSWORD:-db_user_secret_password}
+
+  mailcatcher:
+    image: docker.io/dockage/mailcatcher:0.8.2
+    networks:
+      - server_side
+    ports:
+      - 127.0.0.1:1080:1080
+      - 127.0.0.1:1025:1025