fix(compose): use HINDSIGHT_API_LLM_API_KEY env var

[ishfuseini]

Summary

The HINDSIGHT_API_LLM_API_KEY environment variable in every docker/docker-compose/*/docker-compose.yaml references the wrong source variable on the right-hand side of the ${...} substitution. Setting HINDSIGHT_API_LLM_API_KEY=... in .env is silently ignored — the variable resolves to OPENAI_API_KEY instead.

Two variants of the bug exist:

Variant A — 7 files, dict form (wrong var + your-api-key default that fails auth at first retain):

• alloydb/docker-compose.yaml:68
• pg_search/docker-compose.yaml:75
• custom-models/docker-compose.yaml:28
• pg_textsearch/docker-compose.yaml:71
• timescale/docker-compose.yaml:83
• pgroonga/docker-compose.yaml:71
• vchord/docker-compose.yaml:73

Variant B — 2 files, list form (wrong var + ${VAR?msg} fail-fast, but pointed at the wrong var):

• external-pg/docker-compose.yaml:42
• s3-file-storage/docker-compose.yaml:62

local-llm/docker-compose.yaml uses HINDSIGHT_API_LLM_API_KEY: not-needed (literal) and is intentionally untouched.

Memory is a funny thing. I found this docker container running and didn't know what is was. Tried to use it. Wasn't working. Envs where there but no dice. LLM_BASE_URL wasn't in my docker inspect. So i did a little dance and we're good now but just in case.

Noticed but out of scope

While debugging this, I noticed HINDSIGHT_API_LLM_BASE_URL isn't exposed as an env var in any compose file — it's only set as a literal in local-llm/docker-compose.yaml. Users pointing at a non-OpenAI provider (Ollama, LM Studio, etc.) currently have to edit the compose file by hand. Worth a separate PR.

The bug

HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-your-api-key}

Two issues on one line:

1. The right-hand side reads OPENAI_API_KEY, not HINDSIGHT_API_LLM_API_KEY. Anyone following the README and setting HINDSIGHT_API_LLM_API_KEY=... gets nothing — the value is ignored.
2. The default your-api-key is a string the API will reject, but the container starts cleanly. Failure happens later on first retain, far from the misconfiguration. There is no log line flagging your-api-key as a placeholder.

Variant B uses ${OPENAI_API_KEY?Please set the OPENAI_API_KEY env variable}, which is better — it errors at startup with a message — but still points at the wrong variable, so the message misleads users about what to set.

The fix

Variant A:

HINDSIGHT_API_LLM_API_KEY: ${HINDSIGHT_API_LLM_API_KEY:-}

Variant B (preserves the fail-fast behavior, just points it at the right var):

HINDSIGHT_API_LLM_API_KEY: ${HINDSIGHT_API_LLM_API_KEY:?Please set the HINDSIGHT_API_LLM_API_KEY env variable}

Why this works

${VAR:-} expands to the empty string when VAR is unset — same default behavior as before, but now reads from the correct variable. Users who set HINDSIGHT_API_LLM_API_KEY will see it take effect; users who don't will get an auth failure on first retain (unchanged) or a clear startup error in the Variant B files (unchanged, just with the right variable name).

Testing

• ran docker compose config on each affected file and confirmed the resolved value matches expectations
• set HINDSIGHT_API_LLM_API_KEY in .env and observed the container log on startup
• left it unset and confirmed Variant B files error at startup with the corrected message
• left it unset and confirmed Variant A files start cleanly (matching prior behavior) and fail on first retain

Checklist

• All 9 affected files updated
• local-llm/docker-compose.yaml left untouched (uses literal value)
• No other compose files reference HINDSIGHT_API_LLM_API_KEY or OPENAI_API_KEY (verified via grep)

`

[handnewb]

LGTM! Clean fix — 9 compose files all reference the wrong env var (OPENAI_API_KEY → HINDSIGHT_API_LLM_API_KEY). Each file changes exactly 1 line, well-documented rationale. Variant B preserves the fail-fast behavior with corrected variable name. Thanks for catching this!

[nicoloboschi]

did you verify each readme to not contain outdated run example?

[nicoloboschi]

Verified — the compose fix is correct, but it left the surrounding docs describing a variable nothing reads anymore. I've pushed a follow-up commit updating them:

• custom-models/README.md quick start + the compose file's own header comment
• timescale/README.md prerequisite, quick start and env-var table
• timescale/.env.example — the important one: compose's project directory defaults to the compose file's own directory, so this file is auto-loaded. Naming the wrong var there silently dropped the key on the documented happy path. Also collapsed the ANTHROPIC_API_KEY / GEMINI_API_KEY / GROQ_API_KEY alternatives, which were never read either — the provider switch is HINDSIGHT_API_LLM_PROVIDER plus the one HINDSIGHT_API_LLM_API_KEY.

The other 7 stacks have no README or .env.example, so there was nothing to update there.

I also ran the test plan from the description, which was still unchecked — all four now verified via docker compose config:

• key set in the environment → resolves to the real value (Variant A and B)
• .env.example copied to .env in timescale/ → picked up correctly
• key unset → Variant B fails fast with the corrected message
• key empty → Variant B also fails fast, because ? became :?

Two notes on the description rather than the code:

1. The checklist says "No other compose files reference HINDSIGHT_API_LLM_API_KEY or OPENAI_API_KEY" — nginx/docker-compose.yml:35 does (${OPENAI_API_KEY:-not-needed-for-mock}, plus commented variants at :40/:44). Leaving it alone is right since it's the mock-provider stack, same rationale as local-llm — it just shouldn't be described as absent.
2. "Behavior unchanged" is slightly generous in both variants: Variant A's default moves from your-api-key to empty, and ? → :? now also rejects an empty value. Both are improvements — worth stating as such rather than as no-ops.

Good catch on the underlying bug.