Add Registry Server quickstart and document Helm deployment by rdimitrov · Pull Request #742 · stacklok/docs-website

rdimitrov · 2026-04-21T06:36:46Z

Summary

Adds docs/toolhive/guides-registry/quickstart.mdx, a net-new tutorial that walks a reader from an empty local machine to a running Registry Server and a successful API query. Uses kind, a minimal single-pod PostgreSQL, a ConfigMap-based file source, and anonymous auth so there is no external infrastructure to set up.
Replaces the "coming soon" placeholder in deployment.mdx with a real Helm section covering the chart's config block, a complete values.yaml excerpt for mounting the pgpass Secret via initContainers/extraVolumes/extraVolumeMounts, and a pointer to the chart repo.
Adds the new quickstart to sidebars.ts and surfaces it as the first "Where to start" bullet in guides-registry/index.mdx.

Addresses the top two outstanding gaps in #364 (no quickstart and the Helm placeholder). The publishing guide and polish items are coming in follow-up PRs.

Relates to #364

Test plan

`npm run build` - site builds cleanly (one pre-existing broken anchor on an unrelated page under /guides-ui/mcp-optimizer)
Spot-check on `npm run start`: quickstart renders, sidebar order is correct, enterprise admonition renders correctly, code blocks have expected titles
Walk the quickstart against a real kind cluster end-to-end (nice to have before merge)

🤖 Generated with Claude Code

vercel · 2026-04-21T06:36:51Z

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

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 21, 2026 3:39pm

Copilot

Pull request overview

Adds missing Registry Server onboarding and deployment documentation to close key gaps in the Registry Server docs user journey (quickstart + Helm deployment guidance).

Changes:

Adds a new end-to-end “Quickstart: Registry Server” tutorial using kind + ConfigMap file source + anonymous auth.
Replaces the Helm “coming soon” placeholder with concrete Helm install/config examples.
Updates navigation (sidebar + landing page) to surface the quickstart as the primary starting point.

Reviewed changes

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

File	Description
sidebars.ts	Adds the new quickstart page to the Registry Server docs sidebar near the intro.
docs/toolhive/guides-registry/quickstart.mdx	New tutorial that deploys operator + Postgres + MCPRegistry and demonstrates API queries.
docs/toolhive/guides-registry/index.mdx	Updates “Where to start” to link to the new quickstart and clarifies deployment options.
docs/toolhive/guides-registry/deployment.mdx	Replaces Helm placeholder with real chart usage and a values.yaml example.

- quickstart.mdx: add jq to the prerequisites list since the API query examples in Step 6 pipe curl output to jq. - deployment.mdx: the Helm init-container example now chowns the copied pgpass file to 65532:65532 before applying 0600, matching the UID the Registry Server container runs as. Without the chown, the copied file was owned by root and the main container could not read it at runtime. The command is kept on a single line with a prettier-ignore comment to avoid prettier folding the shell script across lines (which, while technically valid YAML plain-scalar folding, is visually ambiguous). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds missing onboarding and deployment documentation for the ToolHive Registry Server, addressing the “quickstart” and Helm deployment gaps called out in #364.

Changes:

Adds a new end-to-end Registry Server quickstart tutorial (kind + Postgres + ConfigMap source + API query).
Replaces the Helm “coming soon” placeholder with real Helm installation/configuration guidance.
Updates navigation to surface the quickstart prominently (sidebar + “Where to start” section).

Reviewed changes

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

File	Description
`sidebars.ts`	Adds the new Registry Server quickstart page to the Registry Server sidebar ordering.
`docs/toolhive/guides-registry/quickstart.mdx`	New tutorial walking through local Kubernetes deployment and API validation.
`docs/toolhive/guides-registry/index.mdx`	Updates the “Where to start” bullets to link the quickstart first.
`docs/toolhive/guides-registry/deployment.mdx`	Documents Helm-based deployment and chart configuration patterns.

- quickstart.mdx: the CRDs install now includes -n toolhive-system --create-namespace with a namespace-consistency warning matching the operator-install guide. Without this, future CRD upgrades fail with a Helm ownership-annotation mismatch. - quickstart.mdx: fix the Registry API curl paths. The server mounts v0.1 routes under /registry, so the correct path is /registry/{registryName}/v0.1/servers, not /{registryName}/v0.1/... Verified against internal/api/server.go and docs/thv-registry-api/ swagger.yaml on toolhive-registry-server@main. - quickstart.mdx: add a one-liner in Step 3 pointing readers at the production user-privilege model in database.mdx so the quickstart's single-user pgpass doesn't look like a recommended pattern. - deployment.mdx: align the Helm pgpass example with the chart's own commented example at deploy/charts/toolhive-registry-server/ values.yaml. Use extraEnv to set PGPASSFILE, mount the Secret with defaultMode 0600 into /pgpass-secret, prepare /pgpass-prepared via an emptyDir, and run the init container as UID 65535 (the chart default, not 65532 as earlier) so no chown is needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Addresses the two largest gaps flagged in #364: no quickstart existed and the deployment page's Helm section was a "coming soon" placeholder. The new quickstart uses a file-based source, anonymous auth, and a minimal single-pod PostgreSQL so a reader can reach a running Registry Server and query its API end-to-end without external infrastructure. The deployment page now documents the toolhive-registry-server chart, including a pgpass mount excerpt, and the section index links to the new quickstart. Relates to #364 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- quickstart.mdx: add jq to the prerequisites list since the API query examples in Step 6 pipe curl output to jq. - deployment.mdx: the Helm init-container example now chowns the copied pgpass file to 65532:65532 before applying 0600, matching the UID the Registry Server container runs as. Without the chown, the copied file was owned by root and the main container could not read it at runtime. The command is kept on a single line with a prettier-ignore comment to avoid prettier folding the shell script across lines (which, while technically valid YAML plain-scalar folding, is visually ambiguous). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- quickstart.mdx: the CRDs install now includes -n toolhive-system --create-namespace with a namespace-consistency warning matching the operator-install guide. Without this, future CRD upgrades fail with a Helm ownership-annotation mismatch. - quickstart.mdx: fix the Registry API curl paths. The server mounts v0.1 routes under /registry, so the correct path is /registry/{registryName}/v0.1/servers, not /{registryName}/v0.1/... Verified against internal/api/server.go and docs/thv-registry-api/ swagger.yaml on toolhive-registry-server@main. - quickstart.mdx: add a one-liner in Step 3 pointing readers at the production user-privilege model in database.mdx so the quickstart's single-user pgpass doesn't look like a recommended pattern. - deployment.mdx: align the Helm pgpass example with the chart's own commented example at deploy/charts/toolhive-registry-server/ values.yaml. Use extraEnv to set PGPASSFILE, mount the Secret with defaultMode 0600 into /pgpass-secret, prepare /pgpass-prepared via an emptyDir, and run the init container as UID 65535 (the chart default, not 65532 as earlier) so no chown is needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

danbarr

Looks good overall, my primary concern is embedding the Helm deployment instructions in the Deployment overview page rather than having its own guide parallel to the other two methods.

- Split Helm deployment into its own deploy-helm.mdx page, paralleling deploy-operator.mdx and deploy-manual.mdx. deployment.mdx is now consistently a short overview for all three methods. - Add deploy-helm to the sidebar between deploy-operator and deploy-manual. - Drop the namespace-consistency warning admonition from the quickstart to keep the tutorial on the happy path. Add a Related information section linking to the operator deployment guide and the full deployment overview. - Use Stacklok's gofetch image instead of docker.io/mcp/fetch in the quickstart's sample registry data. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Wrap deploy-operator, deploy-helm, and deploy-manual inside a non-collapsible "Deploy the Registry Server" sidebar category that links to the deployment overview page, per danbarr's suggestion on #742. Add the Helm entry to the deployment page's Next steps now that all three deployment methods coexist here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Move the enterprise admonition on quickstart.mdx above Next steps so the closing-section order (Next steps -> Related information -> Troubleshooting) matches the project style guide. - Call out "PostgreSQL 14 or later" in deploy-helm.mdx prerequisites instead of the vague "A PostgreSQL database", matching the version floor documented in deployment.mdx and database.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Wrap deploy-operator, deploy-helm, and deploy-manual inside a non-collapsible "Deploy the Registry Server" sidebar category that links to the deployment overview page, per danbarr's suggestion on #742. Add the Helm entry to the deployment page's Next steps now that all three deployment methods coexist here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add Registry Server quickstart and document Helm deployment Addresses the two largest gaps flagged in #364: no quickstart existed and the deployment page's Helm section was a "coming soon" placeholder. The new quickstart uses a file-based source, anonymous auth, and a minimal single-pod PostgreSQL so a reader can reach a running Registry Server and query its API end-to-end without external infrastructure. The deployment page now documents the toolhive-registry-server chart, including a pgpass mount excerpt, and the section index links to the new quickstart. Relates to #364 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address Copilot review feedback on PR #742 - quickstart.mdx: add jq to the prerequisites list since the API query examples in Step 6 pipe curl output to jq. - deployment.mdx: the Helm init-container example now chowns the copied pgpass file to 65532:65532 before applying 0600, matching the UID the Registry Server container runs as. Without the chown, the copied file was owned by root and the main container could not read it at runtime. The command is kept on a single line with a prettier-ignore comment to avoid prettier folding the shell script across lines (which, while technically valid YAML plain-scalar folding, is visually ambiguous). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address second round of Copilot feedback on PR #742 - quickstart.mdx: the CRDs install now includes -n toolhive-system --create-namespace with a namespace-consistency warning matching the operator-install guide. Without this, future CRD upgrades fail with a Helm ownership-annotation mismatch. - quickstart.mdx: fix the Registry API curl paths. The server mounts v0.1 routes under /registry, so the correct path is /registry/{registryName}/v0.1/servers, not /{registryName}/v0.1/... Verified against internal/api/server.go and docs/thv-registry-api/ swagger.yaml on toolhive-registry-server@main. - quickstart.mdx: add a one-liner in Step 3 pointing readers at the production user-privilege model in database.mdx so the quickstart's single-user pgpass doesn't look like a recommended pattern. - deployment.mdx: align the Helm pgpass example with the chart's own commented example at deploy/charts/toolhive-registry-server/ values.yaml. Use extraEnv to set PGPASSFILE, mount the Secret with defaultMode 0600 into /pgpass-secret, prepare /pgpass-prepared via an emptyDir, and run the init container as UID 65535 (the chart default, not 65532 as earlier) so no chown is needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address danbarr review on PR #742 - Split Helm deployment into its own deploy-helm.mdx page, paralleling deploy-operator.mdx and deploy-manual.mdx. deployment.mdx is now consistently a short overview for all three methods. - Add deploy-helm to the sidebar between deploy-operator and deploy-manual. - Drop the namespace-consistency warning admonition from the quickstart to keep the tutorial on the happy path. Add a Related information section linking to the operator deployment guide and the full deployment overview. - Use Stacklok's gofetch image instead of docker.io/mcp/fetch in the quickstart's sample registry data. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply docs-review findings to PR #742 - Move the enterprise admonition on quickstart.mdx above Next steps so the closing-section order (Next steps -> Related information -> Troubleshooting) matches the project style guide. - Call out "PostgreSQL 14 or later" in deploy-helm.mdx prerequisites instead of the vague "A PostgreSQL database", matching the version floor documented in deployment.mdx and database.mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Add guide for publishing MCP servers to the registry Closes the publishing-guidance gap flagged in #364. The new guide covers all three publishing paths (Git source, file source, managed-source admin API) with worked examples, required fields, and request/response details for the /v1/entries endpoints. Cross-links from intro, configuration, and skills land readers on this page from the most common entry points, and the skills page now points to the canonical versioning-behavior section instead of duplicating it. Relates to #364 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address review feedback on PR #743 - publishing.mdx: point the private-repo auth cross-link at the #private-repository-authentication anchor instead of the broader #git-repository-source anchor, so readers land directly on the subsection that covers auth.username / auth.passwordFile. - configuration.mdx: fix the example client URL in the "Sources vs. registries" bullet. The server mounts v0.1 routes under /registry, so the correct example is /registry/{registryName}/v0.1/ servers, not /{registryName}/v0.1/servers. - configuration.mdx: add a "Publish MCP servers" link to Next steps so readers finishing the configuration page have a natural path into the new publishing guide. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Extend publishing guide to cover skills as well as servers The publishing guide was only half the story: it described how to get servers into a registry but stayed silent on skills, even though the upstream schema and every sync path supports both. Readers trying to ship a skills catalog had to stitch together publishing.mdx (for the file format) and skills.mdx (for the API) with no cross-signal. - publishing.mdx: expand the file-format section to show both data.servers and data.skills in the same registry.json example, note that a single file can carry either or both, and document the minimum skill entry required fields alongside the server ones. - skills.mdx: rewrite the intro to present the two publishing paths side by side and delegate the Git/file mechanics to publishing.mdx rather than re-documenting them. The admin-API sections below stay as the page's main content. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address danbarr review on PR #743 - Restore the inline Versioning behavior content in skills.mdx instead of linking out to publishing.mdx - it's three sentences and readers get a self-contained answer. The top-of-page cross-link to the publishing guide remains as the broader-flow pointer. - Add a Related information section to publishing.mdx (between Next steps and Troubleshooting) linking to the upstream schema, API reference, and configuration guides. - Replace the `{ "...": "..." }` placeholder in the publish-claims example with a more obvious `[ ... ]` ellipsis and a prose note pointing at the full packages shape earlier on the page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply docs-review findings to PR #743 - Use `"packages": []` (valid JSON) with a prose pointer to the full example above, instead of `"packages": [ ... ]` which is invalid JSON inside a `json` fence and would fail parsing if a reader copies it. - Drop the duplicate "View the API reference" link from Next steps; the Related information section already points at the same reference material, and Next steps should stay focused on the forward journey. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Rename publishing.mdx to publish-servers.mdx Future-proof the URL per danbarr's review comment on PR #743. The guide only covers MCP server publishing; renaming now (while the page has never shipped) avoids a later rename-plus-redirect when other publish flows get their own dedicated pages. Updates intro.mdx, skills.mdx, configuration.mdx, and sidebars.ts to point at the new slug. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Wrap deploy-operator, deploy-helm, and deploy-manual inside a non-collapsible "Deploy the Registry Server" sidebar category that links to the deployment overview page, per danbarr's suggestion on #742. Add the Helm entry to the deployment page's Next steps now that all three deployment methods coexist here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Polish Registry Server docs: requirements, upgrade, auth Addresses the remaining secondary items from #364: - authentication.mdx: wrap the four provider-specific examples (Keycloak, Auth0, Azure AD, Okta) in collapsible <details> blocks. Shorter visual footprint and matches the progressive-disclosure pattern used in guides-k8s/auth-k8s.mdx. - intro.mdx: rephrase the "knowledge workers" bullet in the Kubernetes source description to use clearer, less jargon-y wording. Add a new "Registry Server and the rest of ToolHive" section clarifying how the Registry Server relates to the CLI's built-in catalog and the ToolHive operator. - deployment.mdx: add an explicit System requirements section covering Kubernetes versions, PostgreSQL version and migration privileges, persistent storage, and network access. Group the method-choice table under a Deployment methods heading. - deploy-operator.mdx and deploy-manual.mdx: add Upgrade and migration sections covering the operator-chart-then-image flow and the manifest-image-tag flow respectively, with pointers to the release notes and the migration-user privilege model. Relates to #364 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address review feedback on PR #744 - intro.mdx: fix the example client URL in the Key concepts list. Registry Server v0.1 routes are mounted under /registry, so the correct example is /registry/{registryName}/v0.1/servers. - skills.mdx: fix the six curl examples and the "Browse endpoints" path prefix. Pre-existing drift in the skills docs missed the /registry path prefix, so readers copying these commands would receive 404s. Verified against toolhive-registry-server@main internal/api/server.go and docs/thv-registry-api/swagger.yaml. - deployment.mdx: restructure Next steps to first point readers at the deployment how-to that matches their method (Operator vs. manual), then at the configuration tasks that apply to both. Previously the chooser page never surfaced the two how-tos in Next steps even though it's the natural progression. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Group deployment pages under a sidebar category Wrap deploy-operator, deploy-helm, and deploy-manual inside a non-collapsible "Deploy the Registry Server" sidebar category that links to the deployment overview page, per danbarr's suggestion on #742. Add the Helm entry to the deployment page's Next steps now that all three deployment methods coexist here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address danbarr review on PR #744 - Mention PostgreSQL 14+ requirement in database.mdx too, so a reader who jumps straight into the database guide learns the version floor and is directed at the migration-user-privileges section. - Point intro.mdx readers at the concrete CLI hook (thv config set-registry) instead of the vague "can also point at" phrasing. - Replace the <details> provider blocks on authentication.mdx with <Tabs queryString='provider'> so every provider is visible at a glance and individual providers get durable deep-links (for example ?provider=okta) without relying on lost section anchors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply docs-review findings to PR #744 - Link deployment.mdx's PostgreSQL bullet directly to the migration-user-privileges anchor in database.mdx instead of the top of the page. - Replace "A PostgreSQL database" with "PostgreSQL 14 or later" in deploy-operator.mdx and deploy-manual.mdx prose so readers landing on a specific deploy method see the version floor consistent with deployment.mdx and database.mdx. - Point deploy-manual.mdx's top info admonition at both the operator and Helm alternatives, keeping the three deploy-* pages parallel. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 21, 2026 06:36

Copilot started reviewing on behalf of rdimitrov April 21, 2026 06:37 View session

vercel Bot deployed to Preview April 21, 2026 06:37 View deployment

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Comment thread docs/toolhive/guides-registry/quickstart.mdx

Comment thread docs/toolhive/guides-registry/deployment.mdx Outdated

This was referenced Apr 21, 2026

Add Publish MCP servers guide #743

Merged

Polish Registry Server docs: requirements, upgrade, auth #744

Merged

vercel Bot deployed to Preview April 21, 2026 08:21 View deployment

rdimitrov requested a review from Copilot April 21, 2026 08:33

Copilot started reviewing on behalf of rdimitrov April 21, 2026 08:34 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Comment thread docs/toolhive/guides-registry/quickstart.mdx Outdated

Comment thread docs/toolhive/guides-registry/deployment.mdx Outdated

vercel Bot deployed to Preview April 21, 2026 09:06 View deployment

rdimitrov mentioned this pull request Apr 21, 2026

Fix remaining Registry API paths that miss /registry prefix #745

Merged

2 tasks

rdimitrov and others added 3 commits April 21, 2026 14:39

rdimitrov force-pushed the registry-quickstart-helm branch from 403f535 to ff276b3 Compare April 21, 2026 11:39

vercel Bot deployed to Preview April 21, 2026 11:40 View deployment

danbarr requested changes Apr 21, 2026

View reviewed changes

Comment thread docs/toolhive/guides-registry/quickstart.mdx Outdated

Comment thread docs/toolhive/guides-registry/quickstart.mdx Outdated

Comment thread docs/toolhive/guides-registry/deployment.mdx

vercel Bot deployed to Preview April 21, 2026 15:03 View deployment

vercel Bot deployed to Preview April 21, 2026 15:21 View deployment

danbarr approved these changes Apr 21, 2026

View reviewed changes

rdimitrov merged commit fdb2e97 into main Apr 21, 2026
4 checks passed

rdimitrov deleted the registry-quickstart-helm branch April 21, 2026 15:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Registry Server quickstart and document Helm deployment#742

Add Registry Server quickstart and document Helm deployment#742
rdimitrov merged 5 commits intomainfrom
registry-quickstart-helm

rdimitrov commented Apr 21, 2026

Uh oh!

vercel Bot commented Apr 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

danbarr left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

rdimitrov commented Apr 21, 2026

Summary

Test plan

Uh oh!

vercel Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

danbarr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Apr 21, 2026 •

edited

Loading