From 3d1b9b90d9d82e398e6db01b24ed5aaad9eae6b1 Mon Sep 17 00:00:00 2001
From: Juan Antonio Osorio <ozz@stacklok.com>
Date: Thu, 27 Nov 2025 09:14:34 -0600
Subject: [PATCH] Add custom package registries documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the build environment configuration feature for custom package
registries (toolhive#2742). This allows enterprise environments to configure
environment variables like NPM_CONFIG_REGISTRY, GOPROXY, and PIP_INDEX_URL
that are injected into Dockerfiles during protocol scheme builds.

Adds:
- New "Custom package registries" section in build-containers guide
- CLI commands: set-build-env, get-build-env, unset-build-env
- Table of common environment variables for npm, Go, and pip/uv
- Troubleshooting section for custom registry issues

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/toolhive/guides-cli/build-containers.mdx | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx
index 2826b1e7..fae9a1a4 100644
--- a/docs/toolhive/guides-cli/build-containers.mdx
+++ b/docs/toolhive/guides-cli/build-containers.mdx
@@ -261,6 +261,7 @@ you need to pre-build containers before deploying them.
    ```
 
 3. **Deploy to Kubernetes** using the pre-built image:
+
    ```yaml
    apiVersion: toolhive.stacklok.dev/v1alpha1
    kind: MCPServer
@@ -330,6 +331,46 @@ thv build uvx://internal-mcp-server
 thv build --ca-cert /path/to/special-ca.crt uvx://special-server
 ```
 
+### Custom package registries
+
+Enterprise environments often use private package registries or mirrors instead
+of public registries like npm or PyPI. ToolHive supports configuring build
+environment variables that are injected into the Dockerfile during builds,
+allowing you to use custom registries for all protocol scheme builds.
+
+#### Set build environment variables
+
+Use the `thv config set-build-env` command to configure environment variables
+that will be included in all builds:
+
+```bash
+thv config set-build-env <KEY> <VALUE>
+```
+
+Common environment variables for package registries:
+
+| Package manager | Environment variable  | Example value                          |
+| --------------- | --------------------- | -------------------------------------- |
+| npm             | `NPM_CONFIG_REGISTRY` | `https://npm.corp.example.com`         |
+| Go              | `GOPROXY`             | `https://goproxy.corp.example.com`     |
+| Go              | `GOPRIVATE`           | `github.com/mycompany/*`               |
+| pip/uv          | `PIP_INDEX_URL`       | `https://pypi.corp.example.com/simple` |
+| pip/uv          | `PIP_TRUSTED_HOST`    | `pypi.corp.example.com`                |
+
+Example configuration for an enterprise environment:
+
+```bash
+# Configure npm to use a corporate registry
+thv config set-build-env NPM_CONFIG_REGISTRY https://npm.corp.example.com
+
+# Configure Go proxy for private modules
+thv config set-build-env GOPROXY https://goproxy.corp.example.com
+thv config set-build-env GOPRIVATE "github.com/mycompany/*"
+
+# Configure Python/uv to use a corporate PyPI mirror
+thv config set-build-env PIP_INDEX_URL https://pypi.corp.example.com/simple
+```
+
 ### Build local Go projects
 
 Build MCP servers from local Go projects:
@@ -381,9 +422,11 @@ If builds fail with network connectivity issues:
 
 1. **Check internet connectivity** for downloading packages
 2. **Configure CA certificates** for corporate environments:
+
    ```bash
    thv config set-ca-cert /path/to/corporate-ca.crt
    ```
+
 3. **Use proxy settings** if required by your network
 4. **Verify package names** and versions exist in the respective registries
 
@@ -430,3 +473,29 @@ If the build fails because a package cannot be found:
 3. **For Go modules**, ensure the path includes the correct import path
 
 </details>
+
+<details>
+<summary>Custom registry not being used</summary>
+
+If your custom package registry configuration isn't being applied:
+
+1. **Verify your build environment configuration**:
+
+   ```bash
+   thv config get-build-env
+   ```
+
+2. **Check the environment variable names** match what your package manager
+   expects (for example, `NPM_CONFIG_REGISTRY` for npm, `GOPROXY` for Go)
+
+3. **Use `--dry-run` to inspect the generated Dockerfile** and verify your
+   environment variables are being injected:
+
+   ```bash
+   thv build --dry-run uvx://my-package
+   ```
+
+4. **Ensure network connectivity** to your custom registry from inside the
+   container build environment
+
+</details>