Skip to main content

Configure the Registry Server

The Registry Server serves the approved MCP server and skills catalog that the console and Stacklok CLI use. Install it with the platform chart, either with the other platform components or as a separate release for a distributed deployment.

The Enterprise build uses the open source Registry Server configuration schema. This page covers its platform chart values and links to the Registry Server guides for service configuration.

Prerequisites​

Before deploying, ensure you have:

  • A Kubernetes cluster (1.30 or later)
  • An external PostgreSQL database (14 or later). The role that runs migrations needs the CREATEROLE attribute. See Database roles.
  • Stacklok Enterprise distribution access, which includes the Helm chart and container image registry credentials, provided by Stacklok during onboarding

Configure values​

Enable the Registry Server with its registryServer.enabled flag, then set its configuration under the toolhive-registry-server key. The chart wraps the open source Registry Server chart under an upstream alias, so those values sit under toolhive-registry-server.upstream.

The upstream.config block contains the open source Registry Server configuration. The chart provides a toolhive source for the public catalog and a default registry. Supply the database configuration below.

Override sources and registries when you want your own catalog, more registries, or claim-scoped access to them; see the open source reference.

Database roles​

The first startup migration creates a toolhive_registry_server role. Assign the CREATEROLE attribute to the role that runs migrations.

By default the application user runs the migrations, so it is the one that needs the attribute:

CREATE ROLE thv_user LOGIN PASSWORD '<APP_DB_PASSWORD>' CREATEROLE;
CREATE DATABASE toolhive_registry OWNER thv_user;

If you configure a separate migration user, put CREATEROLE on that one instead and leave the application user unprivileged.

Create the database credential Secrets​

Supply database passwords from Secrets, never inline in the config block. Create a Secret for the application user's password. The Registry Server runs schema migrations on startup; if you use a separate, more-privileged migration user, create a second Secret for it. Otherwise the server reuses the application password for migrations and you can skip it.

kubectl create secret generic registry-db-credentials \
  --from-literal=password='<APP_DB_PASSWORD>' \
  -n stacklok-system

# Only if you use a separate migration user
kubectl create secret generic registry-db-migrator-credentials \
  --from-literal=password='<MIGRATION_DB_PASSWORD>' \
  -n stacklok-system

Set the values file​

Enable the component, point it at your database, and reference the Secrets you just created:

values.yaml
# Enable only the Registry Server.
registryServer:
  enabled: true

# Registry Server configuration.
toolhive-registry-server:
  upstream:
    config:
      # sources and registries are required for a working server. See the
      # configuration reference below.
      database:
        host: 'postgres.example.com'
        port: 5432
        user: 'registry' # application user
        migrationUser: 'registry_migrator' # elevated user for migrations
        database: 'registry'
        sslMode: 'require'
    # Passwords from Secrets, keyed by the env vars the server reads.
    extraEnv:
      - name: THV_REGISTRY_DATABASE_PASSWORD
        valueFrom:
          secretKeyRef:
            name: registry-db-credentials
            key: password
      # Only if you use a separate migration user
      - name: THV_REGISTRY_DATABASE_MIGRATIONPASSWORD
        valueFrom:
          secretKeyRef:
            name: registry-db-migrator-credentials
            key: password

Configuration reference​

The upstream.config block accepts every field the open source Registry Server supports. See the open source reference for the detail:

Connect the console​

Install the platform chart with these values as described in Deploy the platform. Once running, verify the pod:

kubectl get pods -n stacklok-system -l app.kubernetes.io/component=registry-api

The chart exposes the Registry Server through an in-cluster Service named registry-api on port 8080. Point the console at it with toolhive-cloud-ui.apiBaseUrl, for example http://registry-api.stacklok-system.svc.cluster.local:8080.

Next steps​

Troubleshooting​

Migration reports Dirty database version 1

The first migration failed because its database role lacked CREATEROLE and left the migration table marked dirty. For a new installation, assign the attribute, drop and recreate the database, and restart the Registry Server.