> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation.md).

# Platform Installation

Install the CAT-BM operator, API, and UI with Helm.

The `catalyx-canton` Helm chart installs three components — the operator, the API, and the CatalyX UI component — plus the two custom resource definitions they depend on.

## Before you install

{% stepper %}
{% step %}
**Create the namespace**

Create a namespace for the platform — any name works. This guide uses `<namespace>` as a placeholder throughout; substitute your own choice everywhere you see it.

```bash
kubectl create namespace <namespace>
```

{% endstep %}

{% step %}
**Create the identity provider secrets**

One secret is required. It lives in the release namespace and holds the operator's admin client secret from an existing Keycloak realm — see [Keycloak Realm Setup](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/keycloak-realm-setup.md) if that realm and its clients don't exist yet.

```bash
# The operator's Keycloak admin client secret
kubectl create secret generic catalyx-operator-keycloak \
  --from-literal=admin-client-secret=<keycloak-admin-client-secret> \
  -n <namespace>
```

{% hint style="info" %}
**Version note.** 2.0.0 also required a `catalyx-api-credentials` secret for the API's own Keycloak client. From 2.0.1 the API authenticates to each validator with that validator's backend client, so the secret is no longer read.
{% endhint %}
{% endstep %}

{% step %}
**Create the TLS secret**

The chart does not create a TLS certificate unless you enable cert-manager. The default name is `catalyx-app-tls`.

```bash
kubectl create secret tls catalyx-app-tls \
  --cert=<path-to-cert.pem> --key=<path-to-key.pem> \
  -n <namespace>
```

{% hint style="warning" %}
This secret name is used by **every ingress route the operator creates for validators**, not just by the UI and API. If it does not exist, validator UIs will fail to serve over HTTPS even if you never set `ingress.tls.secretName` yourself.
{% endhint %}
{% endstep %}

{% step %}
**Create the image pull secret**

```bash
kubectl create secret docker-registry intellecteu-jfrog-access \
  --docker-server=intellecteu-catbp-docker.jfrog.io \
  --docker-username=<username> --docker-password=<token> \
  -n <namespace>
```

{% endstep %}
{% endstepper %}

***

## Install

```bash
helm install catalyx-canton catalyx/catalyx-canton \
  -n <namespace> \
  --set image.tag=v2.0.2 \
  --set 'image.pullSecrets[0].name=intellecteu-jfrog-access' \
  --set operator.keycloak.serverUrl=https://keycloak.example.com \
  --set operator.keycloak.realm=my-realm \
  --set operator.keycloak.adminClientId=catalyx-operator-admin \
  --set operator.keycloak.adminClientSecretRef.name=catalyx-operator-keycloak \
  --set api.auth.jwksUri=https://keycloak.example.com/realms/my-realm/protocol/openid-connect/certs \
  --set ui.oidc.authority=https://keycloak.example.com/realms/my-realm \
  --set ui.oidc.redirectUri=https://validators.example.com \
  --set operatorRuntime.baseHostname=validators.example.com \
  --set ingress.host=validators.example.com \
  --set ingress.tls.secretName=catalyx-app-tls
```

Contact IntellectEU support for the Helm repository URL and credentials.

Verify the rollout:

```bash
kubectl -n <namespace> get deploy
kubectl -n <namespace> wait --for=condition=Available deployment \
  -l app.kubernetes.io/instance=catalyx-canton --timeout=180s
```

The UI is then available at `https://<ingress.host>/`, and the API at `https://<ingress.host>/api`.

***

## Values you must set

These have defaults that are only suitable for local development. Every production install should override all of them.

<table><thead><tr><th width="330">Value</th><th>Purpose</th></tr></thead><tbody><tr><td><code>ingress.host</code></td><td>Hostname the UI and API are served on. When empty, ingress routes match on path only, with no host clause.</td></tr><tr><td><code>ingress.tls.secretName</code></td><td>TLS secret for the UI and API routes.</td></tr><tr><td><code>operatorRuntime.baseHostname</code></td><td>Base hostname for every per-validator hostname the operator generates, and for the identity provider redirect URIs it registers. Changing it later rewrites those redirect URIs on the next reconcile.</td></tr><tr><td><code>operatorRuntime.tlsSecretName</code></td><td>TLS secret used by every ingress route the operator creates. Default <code>catalyx-app-tls</code>.</td></tr><tr><td><code>api.auth.jwksUri</code></td><td>JWKS endpoint the API validates UI tokens against.</td></tr><tr><td><code>ui.oidc.authority</code></td><td>OIDC issuer the UI redirects browser logins to.</td></tr><tr><td><code>ui.oidc.clientId</code></td><td>Public OIDC client for the UI. Default <code>catalyx-canton-ui</code>.</td></tr><tr><td><code>ui.oidc.redirectUri</code></td><td>Where the identity provider returns the browser after login. Must match a redirect URI registered on the client.</td></tr><tr><td><code>image.tag</code></td><td>Pin to a release tag. When empty (the default from 2.0.2), each image uses the chart's <code>appVersion</code>. Charts up to 2.0.1 defaulted to <code>latest</code>.</td></tr><tr><td><code>image.pullSecrets</code></td><td>Pull secret for the IntellectEU registry.</td></tr></tbody></table>

## Managed authentication values

Required only if you intend to use `managedKeycloak: true` on any validator.

<table><thead><tr><th width="380">Value</th><th>Purpose</th></tr></thead><tbody><tr><td><code>operator.keycloak.serverUrl</code></td><td>Identity provider base URL.</td></tr><tr><td><code>operator.keycloak.realm</code></td><td>Realm the operator provisions into. Must already exist.</td></tr><tr><td><code>operator.keycloak.adminClientId</code></td><td>Admin client the operator authenticates as. Must exist <strong>in that realm</strong>.</td></tr><tr><td><code>operator.keycloak.adminClientSecretRef.name</code> / <code>.key</code></td><td>Secret holding the admin client secret. Key defaults to <code>admin-client-secret</code>.</td></tr></tbody></table>

## Operator database

An optional database server for the operator, added in 2.0.2. When `operator.database.host` is set, the operator generates the database names for each validator itself. Sandbox mode needs it, because sandbox validators have no `spec.database`.

<table><thead><tr><th width="330">Value</th><th width="120">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>operator.database.host</code></td><td>empty</td><td>PostgreSQL host. Leave empty to require <code>spec.database</code> on every <code>Validator</code>.</td></tr><tr><td><code>operator.database.port</code></td><td><code>5432</code></td><td>PostgreSQL port.</td></tr><tr><td><code>operator.database.credentialsSecretName</code></td><td>empty</td><td>Secret with the database credentials, under the keys <code>username</code> and <code>password</code>.</td></tr></tbody></table>

{% hint style="danger" %}
**The operator database applies to every validator, not only sandbox ones.** When `operator.database.host` is set, the operator ignores each `Validator`'s own `spec.database`, except `pqsDatabase`. Leave it empty on clusters that run validators with their own `spec.database`.
{% endhint %}

## Sandbox mode values

Sandbox mode, added in 2.0.2, lets a signed-in user create a **DevNet** validator by entering only a name. It is off by default.

<table><thead><tr><th width="330">Value</th><th width="140">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>api.sandbox.enabled</code></td><td><code>false</code></td><td>Turns sandbox mode on.</td></tr><tr><td><code>api.sandbox.sponsorSvUrl</code></td><td>empty</td><td>Sponsor Super Validator the API gets onboarding tokens from.</td></tr><tr><td><code>api.sandbox.scanAddress</code></td><td>empty</td><td>Scan address the API reads the Splice version and migration ID from.</td></tr><tr><td><code>api.sandbox.synchronizerUrl</code></td><td>empty</td><td>Sequencer URL for new validators.</td></tr><tr><td><code>api.sandbox.connectionType</code></td><td><code>trust-single</code></td><td><code>trust-single</code> or <code>bft</code>.</td></tr></tbody></table>

With sandbox mode on, the API serves `POST /api/v1/validators`. On create, it gets an onboarding token from the sponsor SV and stores it as Secret `<validator-name>-onboarding-secret`, reads the Splice version and migration ID from Scan, and creates the `Validator` with managed Keycloak and an owner label set to the caller's identity. Each user sees only the validators and applications they own, and can create one validator. If a sandbox URL is missing, create returns `503`. Sandbox validators have no `spec.database`, so sandbox mode also needs the [operator database](#operator-database).

{% hint style="warning" %}
**Known limitations of sandbox mode**

* It works on DevNet only.
* Validators without an owner label — for example ones applied with `kubectl` — are hidden from every user. There is no admin view.
* The onboarding Secret is written before the `Validator`. It is left behind if the create fails, and it is not deleted with the validator.
  {% endhint %}

## Component values

<table><thead><tr><th width="300">Value</th><th width="150">Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>operator.replicaCount</code></td><td><code>1</code></td><td><strong>Must remain 1.</strong> The operator has no leader election; a second replica double-reconciles every resource.</td></tr><tr><td><code>api.replicaCount</code></td><td><code>1</code></td><td><strong>Must remain 1.</strong> Canton console sessions are held in process, so they do not survive being load-balanced across replicas.</td></tr><tr><td><code>ui.replicaCount</code></td><td><code>2</code></td><td>The UI is stateless and runs highly available by default, with a pod disruption budget and topology spread.</td></tr><tr><td><code>operator.pdb.enabled</code> / <code>api.pdb.enabled</code></td><td><code>true</code></td><td>Pod disruption budgets with <code>maxUnavailable: 1</code>. Because both components run a single replica, a node drain can still evict them — expect a brief interruption while the pod reschedules, rather than a blocked drain.</td></tr><tr><td><code>api.namespace</code></td><td>release namespace</td><td>Namespace the API reads validators from. The API's RBAC is namespaced to the release namespace, so pointing this elsewhere produces authorisation errors.</td></tr><tr><td><code>api.upload.maxFileSize</code> / <code>api.upload.maxRequestSize</code></td><td><code>10MB</code></td><td>Size limits for DAR uploads, added in 2.0.2. 10 MiB matches Canton's default gRPC max inbound message size. If you raise them, also raise the participant's Ledger API max inbound message size.</td></tr><tr><td><code>operator.rbac.clusterAdmin</code></td><td><code>false</code></td><td>Leave <code>false</code>. When <code>true</code>, the operator service account is bound to <code>cluster-admin</code> instead of the chart's least-privilege role.</td></tr><tr><td><code>ui.grafana.baseUrl</code></td><td>—</td><td>Base URL for the Grafana deep links in the UI. See <a href="https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/user-guide-canton/grafana-dashboards.md">Grafana Links</a>.</td></tr><tr><td><code>monitoring.serviceMonitor.enabled</code></td><td><code>false</code></td><td>Set <code>true</code> to have Prometheus scrape validator component metrics. Requires the Prometheus Operator CRDs.</td></tr><tr><td><code>certManager.enabled</code></td><td><code>false</code></td><td>Set <code>true</code>, with <code>certManager.certificate.create</code> and <code>certManager.certificate.dnsNames</code>, to have cert-manager issue the platform certificate.</td></tr></tbody></table>

{% hint style="warning" %}
**Harden the OpenAPI endpoints before exposing the platform publicly.** The chart publishes `/swagger-ui` and `/v3/api-docs` on the same hostname as the API, and both are served without authentication. If that is not acceptable in your environment, restrict them with a Traefik middleware via `api.ingress.middlewares`, or block them at your edge.
{% endhint %}

***

## Upgrading

```bash
helm upgrade catalyx-canton catalyx/catalyx-canton -n <namespace> -f my-values.yaml
```

{% hint style="danger" %}
**Helm does not upgrade CRDs.** `helm upgrade` never touches the chart's `crds/` directory. When a release changes the `Validator` or `Application` schema, apply the CRDs explicitly before upgrading:

```bash
kubectl apply -f <chart>/crds
```

{% endhint %}

Existing validators are re-reconciled after an upgrade. The operator applies rolling updates to component deployments, so a component with more than one replica is updated without downtime.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/installation-instructions-canton/platform-installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
