> 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/hyperledger-fabric/version-2.4/operations-guide/installation-instructions.md).

# Installation Instructions

## Prerequisites

{% stepper %}
{% step %}

#### Set up a Kubernetes or OpenShift cluster

{% hint style="info" %}
**Supported OpenShift version:** 4.7

**Supported Kubernetes version:** 1.17 and later

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

**Minimum cluster size:**

* Catalyst Blockchain Platform (1 instance per org): 2 core CPU, 4 GB RAM, 10 GB disk space
* Each additional node:

| Node    | CPUe | Memory (Mi) | Storage (Gi) |
| ------- | ---- | ----------- | ------------ |
| CA      | 0.1  | 128         | 1            |
| Peer    | 0.1  | 128         | 1            |
| Orderer | 0.1  | 128         | 1            |

{% hint style="info" %}
Consider the expected load and increase values accordingly. Each chaincode installed to a peer runs as a separate pod consuming additional resources.
{% endhint %}
{% endstep %}

{% step %}

#### Install Helm to your workstation

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

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

{% step %}

#### Install Traefik ingress

The ingress controller is needed for traffic routing to expose nodes (peer, CA, orderer). The Catalyst Blockchain Platform creates a CRD resource (`IngressRouteTCP` for Traefik or `Route` for OpenShift), automatically started and deleted with each node.

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 %}

{% hint style="info" %}
If using **OpenShift**, skip this step — OpenShift has a built-in ingress controller. Specify it in Helm chart values later.
{% endhint %}
{% endstep %}

{% step %}

#### Install cert-manager for TLS

TLS certificate is needed for secured communication between users and the Catalyst Blockchain Platform components.

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 [Kubernetes TLS secrets](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets).
{% endhint %}
{% endstep %}

{% step %}

#### Create a wildcard DNS A-record

Catalyst Blockchain Platform needs a wildcard record `*.<domain>` to expose nodes. All nodes (peers, orderers, CAs) will have a `<NodeName>.<domainName>` address.

**For AWS (Route 53):**

1. Go to Route53 and create or select a domain.
2. Create an A record, switch **Alias** to ON.
3. In **Route traffic to**, select "Alias to application and classic load balancer."
4. Select your region and ELB balancer.

See the [AWS](broken://pages/892343ca4ac0b02e38a3ac05ca806c90130bcd97) guide for detailed ingress and DNS setup options.
{% endstep %}

{% step %}

#### Create a namespace

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

**6.1** — Get credentials to the Helm repository from the IntellectEU admin team.

**6.2** — Add the repo:

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

{% 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}
```

{% endstep %}

{% step %}

#### Deploy a message broker (RabbitMQ)

A message broker is required for internal architecture workflows.

{% hint style="info" %}
No specific configurations are needed. Use the [official RabbitMQ documentation](https://www.rabbitmq.com/download.html). Minimum recommended setup: 1 GB RAM.
{% endhint %}
{% endstep %}

{% step %}

#### Deploy a database

A database is required to support internal workflows and store users' action logs.

{% hint style="info" %}
No secure data is stored in the database.
{% endhint %}

Catalyst Blockchain Platform supports **PostgreSQL** and **MySQL**:

{% hint style="danger" %}
**Supported PostgreSQL version:** 12.8 and later

**Supported MySQL version:** 8.0.21 and later
{% endhint %}

* MySQL: <https://dev.mysql.com/doc/mysql-getting-started/en/>
* PostgreSQL: <https://www.postgresql.org/docs/12/tutorial-install.html>

Minimum recommended: 1 GB RAM.
{% endstep %}

{% step %}

#### (Optional) Set up secret storage

Digital identities are stored as a private key and x509 certificate. Two options:

{% tabs %}
{% tab title="Kubernetes Secrets (default)" %}
Enabled by default. For each enrolled identity, a corresponding Kubernetes secret is created. No additional configuration required — use the default configuration in Helm chart values.
{% endtab %}

{% tab title="Hashicorp Vault" %}
Provides more control over identities, better encryption, backups, and other benefits.

See the [Hashicorp Vault Prerequisites](broken://pages/12b0875fc0485e4b8a462f2bf8e347082d003f50) guide before configuring this option.

{% hint style="info" %}
**Performance note:** Each action with Hyperledger Fabric SDK requires an identity, and all identities are stored in Hashicorp Vault. A caching mechanism is included — identities loaded from Vault are cached for a default TTL of 10 seconds.
{% endhint %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

***

## Setup: Configure Helm Chart Values

<details>

<summary>1. domainName</summary>

```yaml
# -- address where the application will be hosted.
# All created nodes will have <NodeName>.proxy.<domainName> address
domainName: ""
```

</details>

<details>

<summary>2. auth</summary>

Two authentication methods are supported: `basic` and `openid`.

```yaml
auth:
  enabled: true
  # -- available methods: 'basic', 'openid'
  method: basic

  basic:
    username: ""
    password: ""
    # Or specify credentials via Kubernetes secret (keys: username, password)
    authSecret: ""

  openid:
    url: ""
    wellKnownURL: ""
    clientID: ""
    roleBasedAuthEnabled: false
```

</details>

<details>

<summary>3. ingressConfig</summary>

```yaml
ingressConfig:
  provider:
    # Supported: traefik, openshift, istio
    name: traefik
    traefik:
      ingressClass: ""
    traefikCRD:
      tlsStore:
        enabled: false
        name: default
    istio:
      gateway: ""
      port: 443
  enabled: false
  tls:
    enabled: false
    certManager:
      enabled: false
      email: "your-email@example.com"
      server: "https://acme-staging-v02.api.letsencrypt.org/directory"
    secretName: ""
```

</details>

<details>

<summary>4. amqp (RabbitMQ)</summary>

```yaml
amqp:
  readinessCheck:
    enabled: true
    initContainer:
      image:
        repository: busybox
        pullPolicy: IfNotPresent
        tag: latest
  host: "rabbitmq.rabbitmq"
  port: "5672"
  # Or specify via Kubernetes secret (keys: username, password)
  credentialsSecret:
  username: "test1"
  password: "Abcd1234"
  vhost: "test1"
```

</details>

<details>

<summary>5. database</summary>

```yaml
database:
  readinessCheck:
    enabled: true
    initContainer:
      image:
        repository: busybox
        pullPolicy: IfNotPresent
        tag: latest
  # 'postgres' or 'mysql'
  type: postgres
  host: "postgresql.postgresql"
  port: "5432"
  # Or specify via Kubernetes secret (keys: username, password)
  credentialsSecret:
  username: "test1"
  password: "Abcd1234"
  dbname: "test1"
  # Set to true to use AWS IAM authentication
  authAws: false
```

</details>

<details>

<summary>6. identityStore (Hashicorp Vault)</summary>

```yaml
identityStore: vault
vault:
  enabled: true
  roleId: <role_id>
  secretId: <secret_id>
  address: <vault_address>
  pathPrefix: <path_prefix>
```

</details>

***

## Install the Catalyst Blockchain Platform

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

**Verify the installation:**

```bash
helm ls                  # Status 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/hyperledger-fabric/version-2.4/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.