fix(deploy): close container final review

README.md

@@ -9,19 +9,19 @@ external in this profile.
 Requirements: Docker Engine with Compose v2 and reachable DWH, vector, and embeddings
 services.
 
-1. Copy `deploy/env.example` to `deploy/.env` and fill in runtime credentials. The `.env`
-   file is gitignored and is read only when the container starts; secrets are never copied
-   into either image.
+1. For local development only, copy `deploy/env.example` to `deploy/.env` and fill in runtime
+   credentials. The file is gitignored and is never copied into either image.
 2. Add or edit YAML workspace descriptors under `deploy/workspaces/`. These files are mounted
    read-only. Use relative `roots`; they resolve beneath `/data/workspaces/<workspace-name>`.
 3. Start the external-service profile:
 
    ```sh
-   docker compose --profile external up --build --wait
+   docker compose -f compose.yaml -f deploy/compose.local.yaml \
+     --profile external up --build --wait
    ```
 
-4. Open <http://localhost:8080>. Set `THOTH_HTTP_PORT` before starting to use another host
-   port.
+4. Open <http://127.0.0.1:8080>. The published port is loopback-only. Set `THOTH_HTTP_PORT`
+   before starting to use another loopback port.
 
 Application state, including settings, sessions, artifacts, and indexes, lives in the named
 `thoth_data` volume mounted at `/data`. `docker compose down` keeps that volume. Only an
@@ -44,3 +44,52 @@ volume afterward. It never targets the fixed `thothii` operator project or its v
 `SMOKE_PROJECT` to a different explicit project name for reproducible debugging, and set
 `KEEP_SMOKE_RESOURCES=1` to retain that smoke project's resources for inspection; remove them
 later with `docker compose --project-name "$SMOKE_PROJECT" --profile external down --volumes`.
+
+## Production trust boundary and secrets
+
+ThothII does not implement OIDC. Do not expose its application port directly to a network.
+The production pattern is an authenticated host reverse proxy that:
+
+- terminates TLS and authenticates every request;
+- removes any client-supplied identity header;
+- injects one trusted `X-Authenticated-User` value;
+- proxies to the loopback-only ThothII frontend.
+
+[`deploy/nginx-authenticated-proxy.conf.example`](deploy/nginx-authenticated-proxy.conf.example)
+shows the contract using nginx `auth_request`; replace the placeholder authentication gateway
+with the organization's reviewed identity proxy. `AUTH_MODE=upstream` trusts this boundary and
+rejects requests without the identity header. Setting `THOTH_PUBLIC_EXPOSURE=true` with any other
+auth mode fails during core startup.
+
+Production credentials use Compose secrets, not `deploy/.env`. Create four files outside the
+repository, restrict their host permissions, and point these variables to them:
+
+```sh
+export THT_DWH_API_KEY_SECRET_FILE=/secure/thoth/dwh-api-key
+export THT_VEC_API_KEY_SECRET_FILE=/secure/thoth/vector-reader-api-key
+export THT_VEC_WRITE_API_KEY_SECRET_FILE=/secure/thoth/vector-writer-api-key
+export THT_CA_SECRET_FILE=/secure/thoth/ca-chain.pem
+export THT_DB_NAME=warehouse
+export THT_DWH_REST_URL=https://dwh.example.test
+export THT_VEC_REST_URL=https://vectors.example.test
+export THT_OLLAMA_URL=https://embeddings.example.test
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external up --build --wait
+```
+
+The secrets and public CA chain are mounted read-only under `/run/secrets` and must be readable by
+the core's UID 10001. See [`deploy/secrets/README.md`](deploy/secrets/README.md) for the verification
+command. The frontend remains on loopback; the authenticated host proxy is the only public listener.
+
+## Reproducible image verification
+
+Base images use exact tags and immutable multi-platform manifest digests. Dependency update and
+residual OS-repository limitations are documented in [`docker/LOCKS.md`](docker/LOCKS.md).
+Run the shared architecture gate with `PLATFORM=linux/amd64` or `PLATFORM=linux/arm64`:
+
+```sh
+PLATFORM=linux/arm64 ./scripts/verify-container-images.sh
+```
+
+It builds both images, runs common version/runtime/security smokes, and emits an image/package
+inventory beneath `.artifacts/container-images/`. CI runs the same script for both architectures.