fix(selfhost): add start_period to postgres and pgbouncer healthchecks

[JSONbored]

Summary

• Neither postgres nor pgbouncer's healthcheck had a start_period, unlike every other service in docker-compose.yml with a genuine cold-start delay (qdrant, ollama, browserless, rees, reporting-exporter, tempo, and the core gittensory app itself — whose comment explicitly says its 60s start_period "tolerates the Postgres cold start").
• Docker counts every failed healthcheck probe toward retries from the very first check unless start_period is set. A genuinely cold pgvector/pgvector:pg16 initdb (first pull, slow disk, low-memory VPS, creating the pgvector extension) can plausibly exceed postgres's 5 retries at a 10s interval (~50s) with no grace period — once Docker marks it unhealthy, every downstream depends_on: condition: service_healthy gate (gittensory, pgbouncer, postgres-exporter) fails startup outright instead of tolerating a slow-but-successful cold start.
• Added start_period: 20s to postgres and start_period: 15s to pgbouncer (which starts fast once postgres is already confirmed healthy), matching the pattern used elsewhere in this file.

Found via a fresh performance/scalability/accuracy hardening audit of the self-host ORB stack. Tracked under #1667.

Scope

• docker-compose.yml — start_period for postgres and pgbouncer healthchecks
• test/unit/selfhost-compose-db-health.test.ts — cover both

Validation

• npm run typecheck
• npx vitest run test/unit/selfhost-compose-db-health.test.ts — 4/4 passing
• git diff --check clean

Safety

• Config-only change, no src/** lines, no secrets. Purely additive grace period — doesn't change steady-state healthcheck behavior once a service is actually healthy.

Closes #3898

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-07 06:44:05 UTC}

2 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a narrow, well-justified config change: it adds `start_period` grace periods (20s for postgres, 15s for pgbouncer) to docker-compose healthchecks, matching the existing pattern used by every other service in the file (qdrant, ollama, browserless, etc.), and closes a real gap where a cold pgvector initdb could exceed the 5×10s=50s retry budget and cascade into failed `service_healthy` gates for gittensory/pgbouncer/postgres-exporter. The diff also slips in a `timeout: 5s` to the postgres healthcheck that wasn't previously present, and a matching unit test asserts both services now have a truthy `start_period`. Values are plausible and consistent with the file's existing conventions (core app already uses 60s explicitly citing Postgres cold start), and CI passed cleanly on a config-only change with no src/** impact.

Nits — 6 non-blocking

• The added postgres `timeout: 5s` (docker-compose.yml near line 232) isn't mentioned in the PR description, which only discusses `start_period` — worth calling out explicitly since it's a behavior change (previously unbounded/default timeout) bundled into a 'start_period only' fix.
• The test in test/unit/selfhost-compose-db-health.test.ts only asserts `start_period` is truthy, not that it equals the documented 20s/15s values — a future edit could silently shrink it back toward unsafe territory and the test would still pass.
• 20s for postgres and 15s for pgbouncer are asserted as sufficient by reasoning in the comment, but no empirical basis (e.g. observed cold-start timings) is cited, unlike the app's 60s value which has prior grounding in fix(selfhost): add start_period to postgres and pgbouncer healthchecks #3898/fix(selfhost): gate gittensory's depends_on on postgres/pgbouncer health #2500 history.
• Pin the exact start_period values in the test (toBe('20s') / toBe('15s')) rather than just truthy, so a regression to a too-small value fails CI.
• Mention the added postgres `timeout: 5s` in the PR description since it's a distinct behavioral change from the start_period addition.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#3898
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 51 registered-repo PR(s), 43 merged, 343 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 51 PR(s), 343 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 51 PR(s), 343 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.58%. Comparing base (61109fe) to head (8bd2a54).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3920   +/-   ##
=======================================
  Coverage   93.58%   93.58%           
=======================================
  Files         358      358           
  Lines       34342    34342           
  Branches    12570    12570           
=======================================
  Hits        32138    32138           
  Misses       1580     1580           
  Partials      624      624           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.