Reorder Registry Server Helm deploy guide

[danbarr]

Description

Follow-up on two items deferred from the #1050 review, plus two gaps that surfaced while fixing them.

1. The Helm guide was not executable in order. deploy-helm.mdx ran helm upgrade ... -f values.yaml before the guide ever showed what goes in values.yaml, and database credentials came later still. Reordered to: prerequisites → create a values file → provide database credentials → install the chart → expose the Service → optional umbrella-chart config.

Gaps that became visible while reordering:

• The pgpass Secret was described but never created. Added the kubectl create namespace and kubectl create secret commands.
• The values file and the pgpass entry have to agree on host, port, database, and user or libpq won't match the entry. That's now stated explicitly.
• The prerequisite said only "PostgreSQL 14 or later"; it now says the instance must be reachable from the cluster with a database and user already created.
• The install and pod check now match the quickstart (--wait --timeout=3m, -l app.kubernetes.io/instance=registry-server). Dropped --create-namespace, since the namespace is created explicitly a step earlier.

2. Database and deployment pointed readers in opposite directions. Resolved in favor of self-contained deployment guides, with database.mdx as the deeper operational reference owning production hardening, migrations, pooling, and alternative credential mechanisms. Most of this landed in #1050 already, so only three stale back-pointers needed retargeting:

• The Kubernetes Secrets tip sent readers to the deprecated operator guide for "complete examples." It now points at the quickstart for the secretKeyRef pattern it actually describes, with the pgpass section as the alternative.
• A bash block carried # See deployment.mdx for examples as a comment, a bare filename rather than a link, pointing at a page with no such example.
• The connection-error troubleshooting step named only pgpassSecretRef, an operator-only CRD field, on a page that serves all deployment methods. Now names both mechanisms.

3. The guide ended at a ready pod with no way to reach the API. The chart ships no Ingress or HTTPRoute template (verified against v1.5.0: the only templates are _helpers, clusterrole, configmap, deployment, leader-election-role, service, serviceaccount), so routing is bring-your-own and nothing said so. New "Expose the Registry Server" section documents the ClusterIP Service and its default <RELEASE_NAME>-toolhive-registry-server name, points readers at their existing ingress controller, Gateway API, or cloud load balancer, and mentions fullnameOverride for a shorter name to reference from routing resources. Port-forward is kept only as a pre-routing smoke test, not as an exposure mechanism.

4. configuration.mdx had the same bare-filename-in-a-YAML-comment pattern, pointing at authentication.mdx. Dropped; the page already links it properly in prose at line 659.

Service naming was verified with helm template against chart v1.5.0. Worth noting for reviewers that quickstart.mdx and migrate-to-helm.mdx appear to disagree on the Service name but don't: the quickstart sets fullnameOverride: registry-server, while migrate-to-helm.mdx documents the default. This PR follows the default.

Type of change

• Documentation update

Related issues/PRs

Follow-up to #1050.

Screenshots

N/A

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Navigation

No pages added, deleted, renamed, or reordered. Section ordering within deploy-helm.mdx changed, but the #provide-database-credentials anchor is preserved (inbound links from quickstart.mdx, migrate-to-helm.mdx, and database.mdx all resolve).

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Jul 28, 2026 7:41pm

[Copilot]

Pull request overview

Reorders and fills gaps in the Registry Server Helm deployment guide so the steps are executable end-to-end (values file + DB credentials before install), and updates related Registry Server docs to remove stale or misleading pointers while adding an explicit “Expose the service” step.

Changes:

• Reordered deploy-helm.mdx to: prerequisites → values file → DB credentials (pgpass Secret) → install → expose Service → optional umbrella-chart config.
• Added missing Kubernetes commands to create the namespace and pgpass Secret, plus an explicit Service exposure section (Ingress/Gateway API/LoadBalancer + port-forward smoke test).
• Retargeted database.mdx / configuration.mdx references to remove stale/bare-filename pointers and clarify credential mechanisms.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/toolhive/guides-registry/deploy-helm.mdx	Reorders the Helm deploy flow and adds missing namespace/Secret creation plus explicit Service exposure guidance.
docs/toolhive/guides-registry/database.mdx	Updates Kubernetes credential guidance to point at the right docs and clarifies troubleshooting language.
docs/toolhive/guides-registry/configuration.mdx	Removes a stale bare-filename comment in a YAML example.