Skip to main content

Deploy the Registry Server

System requirements​

  • Kubernetes: current and two previous minor versions are supported. Production workloads should run on a cluster with at least one node providing 1 vCPU and 1 GB of memory available for the Registry Server pod.
  • PostgreSQL: version 14 or later. The server runs database migrations automatically on startup, so the migration user needs schema-modification privileges. See Database configuration for the full user-privilege model.
  • Persistent storage (recommended for Git sources): a volume mounted at /data avoids re-cloning repositories on every container restart.
  • Network access: outbound connectivity to your configured sources (Git hosts, upstream registries, file URLs) and to the PostgreSQL server.

Deployment methods​

The Registry Server can be deployed in Kubernetes using three methods. Choose the one that fits your environment:

MethodDescription
ToolHive OperatorManage the Registry Server lifecycle through MCPRegistry CRDs
HelmDeploy a standalone Registry Server using its dedicated Helm chart
Manual manifestsDeploy directly using raw Kubernetes manifests

ToolHive Operator​

Deploy and manage the Registry Server using MCPRegistry custom resources. The ToolHive Operator watches for these resources and creates the necessary infrastructure automatically.

See Deploy with the ToolHive Operator for a complete guide.

Helm​

Deploy the Registry Server directly with the official Helm chart from the toolhive-registry-server repository. Use this method when you want to manage the Registry Server like any other Helm release without installing the ToolHive Operator.

Install from the OCI registry:

helm upgrade --install registry-server \
  oci://ghcr.io/stacklok/toolhive-registry-server \
  -n toolhive-system --create-namespace \
  -f values.yaml

The chart's config block maps directly to the Registry Server's configuration file. Any valid configuration field can be set under config in your values file:

values.yaml
config:
  sources:
    - name: toolhive
      git:
        repository: https://github.com/stacklok/toolhive-catalog.git
        branch: main
        path: pkg/catalog/toolhive/data/registry-upstream.json
      syncPolicy:
        interval: '30m'
  registries:
    - name: default
      sources: ['toolhive']
  auth:
    mode: anonymous
  database:
    host: postgres
    port: 5432
    user: registry
    database: registry
    sslMode: require

Database credentials use the pgpass file pattern. Create a Kubernetes Secret with a pgpass-formatted entry, then mount it into the Registry Server pod using the chart's extraVolumes, extraVolumeMounts, and initContainers values:

values.yaml (excerpt)
initContainers:
  - name: pgpass-init
    image: alpine:3
    command:
      - sh
      - -c
      - cp /pgpass/.pgpass /home/appuser/.pgpass && chmod 600
        /home/appuser/.pgpass
    volumeMounts:
      - name: pgpass-secret
        mountPath: /pgpass
      - name: pgpass
        mountPath: /home/appuser
extraVolumes:
  - name: pgpass-secret
    secret:
      secretName: registry-pgpass
  - name: pgpass
    emptyDir: {}
extraVolumeMounts:
  - name: pgpass
    mountPath: /home/appuser

See Database configuration for the pgpass format and user privileges, and the toolhive-registry-server repository for the full set of chart values and their defaults.

Trying this out for the first time?

For a hands-on walkthrough that gets a Registry Server running end-to-end in a local cluster, see Quickstart: Registry Server.

Manual Kubernetes manifests​

Deploy the Registry Server directly using raw Kubernetes manifests. This approach gives you full control over the deployment configuration.

See Deploy manually for instructions.

Next steps​