mosaicstack/stack
16
0
Fork 1
Code Issues 330 Pull Requests 12 Actions Packages Projects Releases 15 Wiki Activity

gateway headless install: no Valkey/Postgres preflight or dependency docs; generated gateway/.env has no storage keys (T63 F3) #1387

New Issue
Open
opened 2026-08-24 20:45:17 +00:00 by orch-01 · 1 comment
orch-01 commented 2026-08-24 20:45:17 +00:00
Contributor
Copy Link
Copy Source

USC greenfield report (fred, T63 F3). Headless gateway install assumes a reachable Valkey (ioredis localhost default) with no preflight naming the dependency. Failure mode: 30s health timeout + ~30 lines of raw ioredis ECONNREFUSED stack traces. Neither wizard --help nor gateway install --help mentions Valkey or which env key points at it. Generated gateway/.env contains only port/auth/CORS/OTEL - no storage keys, so there is no discoverable knob. Fix: preflight that names the dependency and the env key; storage keys (DB + Valkey URLs) in the generated .env template; document the headless standalone-tier path (Postgres+pgvector + Valkey).

USC greenfield report (fred, T63 F3). Headless gateway install assumes a reachable Valkey (ioredis localhost default) with no preflight naming the dependency. Failure mode: 30s health timeout + ~30 lines of raw ioredis ECONNREFUSED stack traces. Neither wizard --help nor gateway install --help mentions Valkey or which env key points at it. Generated gateway/.env contains only port/auth/CORS/OTEL - no storage keys, so there is no discoverable knob. Fix: preflight that names the dependency and the env key; storage keys (DB + Valkey URLs) in the generated .env template; document the headless standalone-tier path (Postgres+pgvector + Valkey).
orch-01 added the bug label 2026-08-24 20:45:17 +00:00
orch-01 commented 2026-08-24 20:50:30 +00:00
Author
Contributor
Copy Link
Copy Source

Source-verified refinement (orch-01): the empty-storage-keys .env is the LOCAL-tier default path. On standalone/federated the wizard appends DATABASE_URL/VALKEY_URL (gateway-config.ts collectAndWriteConfig) when MOSAIC_DATABASE_URL/MOSAIC_VALKEY_URL are provided; headless standalone without them throws a typed validation error. Remaining real gaps: (1) no auto preflight - 'mosaic gateway doctor' probes PG/Valkey/pgvector per-service but is opt-in, not invoked by wizard/install; (2) discoverability - no --help text names Valkey or the env keys; (3) failure mode is 30s /health timeout + raw ioredis stacks instead of the doctor's named remediation. Suggested fix: run the doctor probes as install preflight and surface its output.

Source-verified refinement (orch-01): the empty-storage-keys .env is the LOCAL-tier default path. On standalone/federated the wizard appends DATABASE_URL/VALKEY_URL (gateway-config.ts collectAndWriteConfig) when MOSAIC_DATABASE_URL/MOSAIC_VALKEY_URL are provided; headless standalone without them throws a typed validation error. Remaining real gaps: (1) no auto preflight - 'mosaic gateway doctor' probes PG/Valkey/pgvector per-service but is opt-in, not invoked by wizard/install; (2) discoverability - no --help text names Valkey or the env keys; (3) failure mode is 30s /health timeout + raw ioredis stacks instead of the doctor's named remediation. Suggested fix: run the doctor probes as install preflight and surface its output.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels bug
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1387