> 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-1.10/operations-guide/installation-instructions.md).

# Installation Instructions

## Prerequisites

{% stepper %}
{% step %}

#### Set up a Kubernetes or OpenShift cluster

{% hint style="info" %}
**Supported Kubernetes version:** 1.21 and later.

We recommend AWS (EKS) or Google Cloud (GKE), but you can install on a standalone cluster as well.
{% endhint %}

Define your cluster size considering the following minimum requirements:

**Catalyst Blockchain Manager Canton service (1 instance):**

* 2 core CPU
* 4 GB RAM
* 10 GB disk space

**Per additional node (Domain, Participant, or Application):**

| Node        | CPUe | Memory (Gi) | Storage (Gi) |
| ----------- | ---- | ----------- | ------------ |
| Domain      | 1    | 1           | 1            |
| Participant | 1    | 1           | 1            |
| Application | 1    | 1           | 1            |

{% hint style="info" %}
When deciding on cluster size, consider the expected load of the nodes and increase these values accordingly.
{% endhint %}
{% endstep %}

{% step %}

#### Install Helm to your workstation

Installation guide: <https://helm.sh/docs/intro/install/>

No customization is needed.

{% hint style="danger" %}
**Supported Helm version:** 3.X
{% endhint %}
{% endstep %}

{% step %}

#### Install Traefik ingress

The ingress-controller is needed for traffic routing to expose nodes (domains & applications). Catalyst creates an `IngressRoute` CRD that is automatically started and deleted along with each application.

Installation guide: <https://github.com/traefik/traefik-helm-chart>

No customization is needed. The default port (`:443`) for HTTPS traffic will be used.

{% hint style="info" %}
We recommend installing Traefik to a separate namespace from the application.
{% endhint %}

{% hint style="danger" %}
**Supported Traefik version:** 2.3
{% endhint %}
{% endstep %}

{% step %}

#### Install cert-manager for TLS certificates

TLS certificate is needed for secured communication between a user and the Catalyst Blockchain Manager Canton service.

Installation guide: <https://cert-manager.io/docs/installation/helm/>

{% hint style="info" %}
You can skip this step and specify your TLS certificate and key as a Kubernetes secret in Helm chart values instead. See the [Kubernetes secret documentation](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets).
{% endhint %}
{% endstep %}

{% step %}

#### Create a wildcard DNS A-record

Catalyst needs a wildcard record `*.<domain>` to expose nodes. All created nodes (domains, participants, applications) will have a `<NodeName>.<domainName>` address.

**For AWS (Route 53):**

1. Go to the Route53 service.
2. Create a new domain or choose an existing domain.
3. Create an A record.
4. Switch **Alias** to ON.
5. In **Route traffic to**, select "Alias to application and classic load balancer."
6. Select your region.
7. Select an ELB balancer from the drop-down list.

<details>

<summary>How to find your ELB</summary>

Choose the ELB balancer that was automatically configured during Traefik chart installation:

```bash
kubectl get svc -n ${ingress-namespace}
```

Where `${ingress-namespace}` is the name of the namespace where the ingress was installed. The ELB is displayed in the `EXTERNAL-IP` field.

</details>
{% endstep %}

{% step %}

#### Create a namespace

```bash
kubectl create ns ${ns_name}
```

Where `${ns_name}` is the name of the namespace (can be any value).
{% endstep %}

{% step %}

#### Add the Helm repository

**7.1** — Get credentials to the Helm repository in JFrog Artifactory from the IntellectEU admin team.

**7.2** — Add the repo to Helm:

```bash
helm repo add catbp https://intellecteu.jfrog.io/artifactory/catbp-helm \
  --username ${ARTIFACTORY_USERNAME} \
  --password ${ARTIFACTORY_PASSWORD}
```

Expected result: `"catbp" has been added to your repositories`
{% endstep %}

{% step %}

#### Create an ImagePullSecret

```bash
kubectl create secret intellecteu-jfrog-access regcred \
  --docker-server=intellecteu-catbp-docker.jfrog.io \
  --docker-username=${your-name} \
  --docker-password=${your-password} \
  --docker-email=${your-email} \
  -n ${ns_name}
```

{% hint style="info" %}
If you want to use a readiness check and a private repository for the image, create a Kubernetes secret. See: [Kubernetes pull image from private registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)
{% endhint %}
{% endstep %}

{% step %}

#### Set up Keycloak realm or Auth0 tenant

{% tabs %}
{% tab title="Keycloak" %}
Download the `realm.json` file and import it to create the necessary clients, scopes, and users in your Keycloak realm.

{% hint style="info" %}
User roles `canton_viewer` & `canton_writer` will be evaluated by the Catalyst Blockchain Manager Canton service.
{% endhint %}
{% endtab %}

{% tab title="Auth0" %}
If you want to enable Auth0 as an option for ledger authentication, set up a tenant.

After creating the tenant, set `enabled`, domain, api id, client id, and client secret in the helm values.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### (Optional) Set up Monitoring & Dashboard

Install the [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) on your cluster.

Once installed, configure Keycloak OAuth2 authentication on Grafana following the [Grafana Keycloak documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/keycloak/).

{% hint style="info" %}
A default dashboard JSON file is available for import in Grafana.
{% endhint %}
{% endstep %}

{% step %}

#### Enter License Key

Request a license key and set it in the Helm chart values.
{% endstep %}
{% endstepper %}

***

## Setup

### Configure Helm Chart Values

<details>

<summary>Full list of Helm chart values</summary>

```yaml
# -- address where application will be hosted.
domainName: ""

auth:
  enabled: true
  keycloak:
    enabled: true
  keycloakUrl: ""
  keycloakRealm: ""
  # Configure below only if keycloak.enabled=false
  url: ""
  client:
    idApiOperator: ""
    idUI: ""
    secret: ""
    externalSecret:
      enabled: false
      remoteSecretRef: ""
      secretStoreRef:
        name: ""
        kind: "SecretStore"

rbac:
  enabled: true
  serviceAccountName: canton-console
  automountServiceAccountToken: false

operator:
  replicaCount: 1
  image:
    repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-operator
    pullPolicy: IfNotPresent
    tag: ""
  imagePullSecrets: []
  resources: {}
  nodeSelector: {}
  tolerations: []
  affinity: {}
  keycloakClient:
    secret: ""
    externalSecret:
      enabled: false
      remoteSecretRef: ""
      secretStoreRef:
        name: ""
        kind: "SecretStore"
  probes:
    enabled: true
    livenessProbe:
      initialDelaySeconds: 60
      periodSeconds: 10
      timeoutSeconds: 1
      successThreshold: 1
      failureThreshold: 3
    readinessProbe:
      initialDelaySeconds: 40
      periodSeconds: 10
      timeoutSeconds: 1
      successThreshold: 1
      failureThreshold: 5

api:
  darsPvc:
    enabled: true
    size: 5Gi
    mountPath: /dars-storage
    storageClass: ""
  environment: "dev"
  replicaCount: 1
  image:
    repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-console
    pullPolicy: IfNotPresent
    tag: ""
  imagePullSecrets: []
  service:
    port: 8080
    portName: http
  resources: {}
  nodeSelector: {}
  keycloakClient:
    secret: ""
    externalSecret:
      enabled: false
      remoteSecretRef: ""
      secretStoreRef:
        name: ""
        kind: "SecretStore"
  probes:
    enabled: true
    livenessProbe:
      initialDelaySeconds: 90
      periodSeconds: 10
      timeoutSeconds: 3
      successThreshold: 1
      failureThreshold: 3
    readinessProbe:
      initialDelaySeconds: 60
      periodSeconds: 10
      timeoutSeconds: 10
      successThreshold: 1
      failureThreshold: 5
  licenseKey:
    key: ""
    secret:
      enabled: false
      name: ""
      key: ""
  ledgerAuth:
    auth0:
      enabled: false
      domain: ""
      apiIdentifier: ""
      clientId: ""
      clientSecret: ""

ui:
  autoscaling:
    enabled: false
    minReplicas: 1
    maxReplicas: 5
    targetCPUUtilizationPercentage: 80
  replicaCount: 1
  image:
    repository: intellecteu-catbp-docker.jfrog.io/catbp/canton/canton-console-ui
    pullPolicy: IfNotPresent
    tag: ""
  imagePullSecrets: []
  service:
    port: 80
    portName: http
  resources: {}
  nodeSelector: {}
  keycloakClient:
    id: ""

ingressConfig:
  provider:
    name: traefikCRD
    traefikCRD:
      tlsStore:
        enabled: false
        name: default
  enabled: false
  tls:
    enabled: false
    certManager:
      enabled: false
      email: ""
      server: "https://acme-staging-v02.api.letsencrypt.org/directory"
    secretName: ""
  stripApplicationPrefix:
    enabled: true
    regex:
      - "/.*(/api)?/"

monitoring:
  enabled: false
  serviceMonitor:
    interval: 30s
  prometheusRules:
    enabled: false
    labels: {}
  grafana:
    enabled: false
    url: ""
    user: admin
    email: admin@domain.com
    clusterDashboard: ""
    service:
      name: grafana
      namespace: monitoring
      port: 80
```

</details>

***

## Install the Catalyst Blockchain Manager Canton Service

```bash
helm upgrade --install ${canton_release_name} catbp/canton-console \
  --values values.yaml \
  -n ${ns_name}
```

Where:

* `${canton_release_name}` — name of the release (any name/alias)
* `catbp/canton-console` — chart name ("catbp" is the repo, "canton-console" is the chart)
* `values.yaml` — your values file
* `${ns_name}` — the namespace created earlier

**Verify the installation:**

```bash
helm ls                  # Check "status" field — should show "deployed"
kubectl get pods         # All pod statuses must be "Running"
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.10/operations-guide/installation-instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.