docs(container): documentation & CI audit guards (ADR-T-009 Phase 9)

Closes out ADR-T-009 by landing the documentation and CI-audit
work that the earlier phases deferred. No runtime behaviour
changes; the diff is operator-facing docs plus three new
container-infra lint jobs.

Highlights:

- CHANGELOG: consolidate the Phase 1–9 story under a single
  ADR-T-009 entry covering the lean release / debug split,
  the three extracted helper crates (health-check,
  auth-keypair, config-probe), the Compose split, and the
  vendored su-exec audit. Also document the three breaking
  changes operators need to know about (mandatory
  database.connect_url and tracker.token, mutually-exclusive
  AUTH__*_PEM / AUTH__*_PATH pairs, and the demotion of
  TORRUST_INDEX_DATABASE_DRIVER to a first-boot TOML selector).
- README: replace the bare `docker run` / `podman run`
  one-liners with the now-required override pair, and add
  a Compose-sandbox section pointing at `make up-dev` /
  `make up-prod`. Cross-link ADR-T-009 from the docs index.
- docs/containers.md: document the test-stage build gate
  (no --skip-tests escape hatch, by design), the new
  IMPORTER_API_PORT and TZ env vars, and the canonical
  entry-script env-var manifest contract.
- share/container/entry_script_sh: add the
  `ENTRY_ENV_VARS` / `END_ENTRY_ENV_VARS` manifest block
  as the single source of truth for every env var the
  script consults (including dynamically constructed
  AUTH__*_{PEM,PATH} names a naive grep would miss).
- contrib/dev-tools/su-exec/AUDIT.md: new file recording
  provenance, choice rationale (vs gosu / setpriv / su),
  re-audit triggers (file-change + CVE, deliberately not
  calendar-based), and an append-only audit log anchored
  by SHA-256.
- .github/workflows/container.yaml: new `lints` job that
  the existing `test` job now depends on, with three
  guards — (1) compose.yaml stays free of mailcatcher /
  SMTP wiring (comments stripped before grepping so the
  explanatory header doesn't trip the audit),
  (2) su-exec.c SHA-256 matches the most recent AUDIT.md
  entry, and (3) every env var in the entry-script
  manifest is documented in docs/containers.md.
- ADR + implementation plan: flip status from Proposed /
  Phase 9 "Not started" to Implemented.
- AGENTS.md: extend the helper-crates list with
  index-cli-common and index-entry-script.

Author: peer-cat

.github/workflows/container.yaml

@@ -15,8 +15,90 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  lints:
+    name: Lints (Container infra)
+    runs-on: ubuntu-latest
+
+    steps:
+      - id: checkout
+        name: Checkout Repository
+        uses: actions/checkout@v6
+
+      # Phase 9 §9.1.3 — guard against re-introducing the
+      # `mailcatcher` dev sidecar (or any SMTP/mail config)
+      # into the production-shaped baseline. The override
+      # file is *expected* to mention `mailcatcher` and is
+      # deliberately excluded from the audit. Comments are
+      # stripped before grepping so the explanatory header
+      # in `compose.yaml` (which legitimately references
+      # `mailcatcher` in prose) does not trip the audit;
+      # we are looking for live YAML config, not docs.
+      - id: compose-baseline-no-mailcatcher
+        name: compose.yaml has no mailcatcher / SMTP wiring
+        run: |
+          set -eu
+          # awk strips `# ...` comments while preserving line
+          # numbering 1:1 with the source file, so any error
+          # output points the reader at the real line.
+          if awk '{ sub(/#.*/, ""); print }' compose.yaml \
+              | grep -nE 'mailcatcher|MAILER|SMTP|smtp_'; then
+            echo "::error file=compose.yaml::dev mail sidecar / SMTP config present in production-shaped baseline (ADR-T-009 §8.1, §9.1.3)"
+            exit 1
+          fi
+          echo "compose.yaml clean."
+
+      # Phase 9 §9.2 — vendored `su-exec.c` must not change
+      # without a fresh audit entry recording the new SHA-256
+      # in contrib/dev-tools/su-exec/AUDIT.md.
+      - id: su-exec-audit
+        name: su-exec audit log matches vendored source
+        run: |
+          set -eu
+          audit=contrib/dev-tools/su-exec/AUDIT.md
+          test -s "$audit"
+          recorded=$(sed -n '/^## Audit Log/,$ { s/^SHA-256: \([0-9a-f]\{64\}\)$/\1/p; }' "$audit" | tail -1)
+          actual=$(sha256sum contrib/dev-tools/su-exec/su-exec.c | cut -d' ' -f1)
+          if [ -z "$recorded" ]; then
+            echo "::error file=$audit::no SHA-256 entry found in '## Audit Log' section (ADR-T-009 §9.2)"
+            exit 1
+          fi
+          if [ "$recorded" != "$actual" ]; then
+            echo "::error file=$audit::recorded SHA-256 ($recorded) does not match contrib/dev-tools/su-exec/su-exec.c ($actual). Append a new dated audit entry per ADR-T-009 §9.2."
+            exit 1
+          fi
+          echo "su-exec audit current ($actual)."
+
+      # Phase 9 §9 / Acceptance Criterion #7 — every env var
+      # listed in the entry script's manifest block must be
+      # documented in docs/containers.md.
+      - id: entry-env-docs
+        name: entry-script env vars documented
+        run: |
+          set -eu
+          script=share/container/entry_script_sh
+          vars=$(sed -n '/^# ENTRY_ENV_VARS:/,/^# END_ENTRY_ENV_VARS/p' "$script" \
+                  | grep -oE '[A-Z][A-Z0-9_]+' \
+                  | sort -u)
+          if [ -z "$vars" ]; then
+            echo "::error file=$script::ENTRY_ENV_VARS manifest block not found or empty (ADR-T-009 §9 Crit. #7)"
+            exit 1
+          fi
+          missing=0
+          for v in $vars; do
+            grep -q "$v" docs/containers.md || {
+              echo "::error file=docs/containers.md::env var '$v' is in the entry-script manifest but not documented"
+              missing=1
+            }
+          done
+          grep -q 'compose\.override\.yaml' docs/containers.md || {
+            echo "::error file=docs/containers.md::two-file Compose split (compose.override.yaml) is not documented"
+            missing=1
+          }
+          [ "$missing" -eq 0 ]
+
   test:
     name: Test (Docker)
+    needs: lints
     runs-on: ubuntu-latest
 
     strategy:

AGENTS.md

@@ -68,10 +68,11 @@ use their own `ADR-<PREFIX>-<NNN>` form without the `§` prefix.
 | `R-`   | render-text-as-image | `packages/render-text-as-image/`     |
 
 Helper crates (`index-health-check`, `index-auth-keypair`,
-`index-config`, `index-config-probe`) are internal
-implementation details of the root crate and do not own
-separate ADRs or specification docs. They share the `T-`
-prefix for any cross-references that target them.
+`index-config`, `index-config-probe`, `index-cli-common`,
+`index-entry-script`) are internal implementation details of
+the root crate and do not own separate ADRs or specification
+docs. They share the `T-` prefix for any cross-references
+that target them.
 
 ### General Rules
 

CHANGELOG.md

@@ -9,7 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- ADR-T-009: Container infrastructure hardening (Phases 1, 2 & 3).
+- ADR-T-009: Container infrastructure refactor (Phases 1–9). Beyond
+  the tactical hardening already noted under Phase 3, the refactor:
+  - Splits the runtime image into a lean `release` (distroless
+    `cc-debian13`) and `debug` (`cc-debian13:debug`) target. The
+    `release` image keeps `/bin/busybox`, `/bin/su-exec`, and
+    `/usr/bin/jq` root-only (mode `0700`/`0500 root:root`); the
+    unprivileged `torrust` user gets `EACCES` on the entire toolset
+    after privilege drop. The `debug` target retains the upstream
+    `/busybox/` tree on `PATH` for interactive debugging.
+  - Extracts three helper binaries into their own workspace crates
+    with no transitive HTTP/TLS/async-runtime dependencies:
+    `torrust-index-health-check` (renamed from `health_check`),
+    `torrust-index-auth-keypair` (renamed from
+    `torrust-generate-auth-keypair`), and the new
+    `torrust-index-config-probe` (the same loader the application
+    uses, exposing the resolved schema/database/auth state as JSON).
+  - Splits Compose into a production-shaped
+    [`compose.yaml`](./compose.yaml) baseline (no `mailcatcher`, no
+    `tty`, dev ports bound to `127.0.0.1`, credentials referenced
+    as bare `${VAR}`) and an auto-loaded
+    [`compose.override.yaml`](./compose.override.yaml) supplying the
+    dev sandbox. Two `Makefile` targets (`make up-dev`, `make up-prod`)
+    wrap the documented invocation paths and validate required env
+    vars before any container starts.
+  - Adds `contrib/dev-tools/su-exec/AUDIT.md` recording provenance,
+    rationale, and a SHA-256-anchored append-only audit log for the
+    vendored `su-exec.c`. CI fails the build when the file changes
+    without a matching audit entry.
+
 - `torrust-index-config` workspace crate (`packages/index-config/`)
   containing the parsing surface of the configuration system: schema
   modules, validator, `load_settings`, `Info`, `Error`, the
@@ -91,6 +119,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **BREAKING:** `database.connect_url` and `tracker.token` are now
+  mandatory schema fields (no defaults in shipped TOMLs). Operators
+  must supply both via env-var override
+  (`TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL`,
+  `TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN`) or by mounting a
+  populated `index.toml`. Missing values fail at config-parse time
+  with a precise serde `missing field` error rather than silently
+  falling back to a hidden default (ADR-T-009 §D2).
+- **BREAKING:** `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__*_PEM` and
+  `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__*_PATH` are mutually exclusive
+  within a single key, both keys must use the same delivery
+  mechanism, and the pair must either both be configured or both be
+  absent. Mixed/half-pair configurations are rejected by the entry
+  script before the application starts (ADR-T-009 §D3).
+- **BREAKING:** `TORRUST_INDEX_DATABASE_DRIVER` is now a *first-boot
+  TOML selector only* (read by the entry script to choose which
+  shipped default `index.toml` to seed). It no longer dispatches the
+  application's runtime database driver — that is derived from the
+  URL scheme of `database.connect_url`. Operators who scripted around
+  this env var to switch databases at runtime must instead supply
+  `TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL`
+  (ADR-T-009 §D2/§7.4).
 - **BREAKING:** TLS configuration renamed from `[net.tsl]` to `[net.tls]`
   in operator TOMLs and from `"tsl"` to `"tls"` in the settings JSON
   API response. The original spelling was a typo; corrected as a clean

README.md

@@ -31,24 +31,56 @@ If you are using `Version 1` of `torrust-tracker-backend`, please view our [upgr
 
 ### Container Version
 
-The Torrust Index is [deployed to DockerHub][dockerhub], you can run a demo immediately with the following commands:
+The Torrust Index is [deployed to DockerHub][dockerhub], you can run a demo
+immediately with the following commands. Per
+[ADR-T-009 §D2](./adr/009-container-infrastructure-refactor.md), the image
+no longer ships a default tracker token or `database.connect_url`, so two
+overrides are mandatory at startup — a bare `docker run -it
+torrust/index:develop` now fails with a `missing field` error rather than
+booting against hidden defaults.
 
 #### Docker
 
 ```sh
-docker run -it torrust/index:develop
+docker run -it \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MyAccessToken" \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL="sqlite:///var/lib/torrust/index/database/sqlite3.db?mode=rwc" \
+    torrust/index:develop
 ```
 
 > Please read our [container guide][containers.md] for more information.
 
 #### Podman
 
 ```sh
-podman run -it torrust/index:develop
+podman run -it \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MyAccessToken" \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_DATABASE__CONNECT_URL="sqlite:///var/lib/torrust/index/database/sqlite3.db?mode=rwc" \
+    torrust/index:develop
 ```
 
 > Please read our [container guide][containers.md] for more information.
 
+#### Compose (development sandbox)
+
+For a complete local stack (index + tracker + MySQL + mailcatcher) the
+repository ships a Compose split: a production-shaped
+[`compose.yaml`](./compose.yaml) baseline plus an auto-loaded
+[`compose.override.yaml`](./compose.override.yaml) that supplies dev
+defaults. Two `Makefile` wrappers cover the documented invocation
+paths:
+
+```sh
+# Dev sandbox (auto-loads compose.override.yaml):
+make up-dev
+
+# Production-shaped (validates required credentials first):
+make up-prod
+```
+
+See [Compose Split](./docs/containers.md#compose-split) in the container
+guide for the required env vars and the validation contract.
+
 ### Development Version
 
 - Please assure you have the ___[latest stable (or nightly) version of Rust][Rust]___.
@@ -144,6 +176,7 @@ The following services are provided by the default configuration:
 - [ADR-T-006: Refactor the Error System](adr/006-error-system-refactor.md) — Replace the 41-variant `ServiceError` god enum with domain-scoped error enums (`AuthError`, `UserError`, `TorrentError`, `CategoryTagError`) and a thin `ApiError` wrapper.
 - [ADR-T-007: Refactor the JWT System](adr/007-jwt-system-refactor.md) — Centralise JWT handling into `src/jwt.rs`, redesign claims to RFC 7519, move to RS256 asymmetric signing, and consolidate session validation into a single code path.
 - [ADR-T-008: Refactor the Roles and Permissions System](adr/008-roles-and-permissions-refactor.md) — Replace Casbin with a native Rust permission system (`PermissionMatrix` + `RequirePermission<A>` Axum extractors), migrate from `administrator: bool` to a `role` column, and add a `/me/permissions` discovery endpoint.
+- [ADR-T-009: Container Infrastructure Refactor](adr/009-container-infrastructure-refactor.md) — Split the runtime image into `release` (distroless, root-only toolset) and `debug` bases; extract three helper binaries (`torrust-index-health-check`, `torrust-index-auth-keypair`, `torrust-index-config-probe`) into their own workspace crates with no HTTP/TLS/async-runtime deps; strip credentials from shipped TOMLs and make `database.connect_url` / `tracker.token` mandatory schema fields; split Compose into a production-shaped `compose.yaml` baseline plus an auto-loaded `compose.override.yaml` dev sandbox; and add an internal audit record for vendored `su-exec`.
 
 ## Contributing
 

adr/009-container-infrastructure-refactor.md

@@ -1,6 +1,6 @@
 # ADR-T-009: Container Infrastructure Refactor
 
-**Status:** Proposed
+**Status:** Implemented (Phases 1–9 complete)
 **Date:** 2026-04-19
 **Supersedes:** Earlier `ADR-T-009` draft ("Container
 Infrastructure Hardening") whose tactical S-N items were

adr/009-implementation-plan.md

@@ -1,7 +1,7 @@
 # ADR-T-009 — Implementation Plan
 
 **Companion to:** [adr/009-container-infrastructure-refactor.md](009-container-infrastructure-refactor.md)
-**Status:** Tracking
+**Status:** Implemented (Phases 1–9 complete)
 **Date:** 2026-04-19
 
 This document captures the *how* of ADR-T-009. The ADR records
@@ -22,7 +22,7 @@ re-litigated here — when in doubt, defer to the ADR.
 | 6     | Config probe                       | Done        |
 | 7     | Entry-script contract              | Done        |
 | 8     | Compose split                      | Done        |
-| 9     | Documentation & audit (D8, D9)     | Not started |
+| 9     | Documentation & audit (D8, D9)     | Done        |
 
 ## Phase Dependency Graph
 

contrib/dev-tools/container/e2e/mysql/e2e-env-down.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.mysql.toml) \
+TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.toml) \
 TORRUST_TRACKER_CONFIG_TOML=$(cat ./share/default/config/tracker.public.e2e.container.sqlite3.toml) \
     docker compose down

contrib/dev-tools/container/e2e/mysql/e2e-env-up.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
 
-TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.public.e2e.container.mysql.toml) \
+TORRUST_INDEX_CONFIG=$(cat ./share/default/config/index.public.e2e.container.toml) \
     docker compose build
 
 USER_ID=${USER_ID:-1000} \
-    TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.mysql.toml) \
+    TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.toml) \
     TORRUST_INDEX_DATABASE="torrust_index_e2e_testing" \
     TORRUST_INDEX_DATABASE_DRIVER="mysql" \
     TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MyAccessToken" \

contrib/dev-tools/container/e2e/mysql/run-e2e-tests.sh

@@ -38,7 +38,7 @@ docker ps
 
 # Run E2E tests with shared app instance
 TORRUST_INDEX_E2E_SHARED=true \
-    TORRUST_INDEX_CONFIG_TOML_PATH="./share/default/config/index.public.e2e.container.mysql.toml" \
+    TORRUST_INDEX_CONFIG_TOML_PATH="./share/default/config/index.public.e2e.container.toml" \
     TORRUST_INDEX_E2E_DB_CONNECT_URL="mysql://root:root_secret_password@127.0.0.1:3306/torrust_index_e2e_testing" \
     cargo test ||
     {

contrib/dev-tools/container/e2e/sqlite/mode/public/e2e-env-down.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.sqlite3.toml) \
+TORRUST_INDEX_CONFIG_TOML=$(cat ./share/default/config/index.public.e2e.container.toml) \
 TORRUST_TRACKER_CONFIG_TOML=$(cat ./share/default/config/tracker.public.e2e.container.sqlite3.toml) \
     docker compose down