> 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-besu/version-1.1.0/installation-instructions.md).

# Installation Instructions

Welcome to the Installation Guide for CatalyX Blockchain Manager — Hyperledger Besu Edition. This document provides a step-by-step approach to installing CatalyX Blockchain Manager.

{% stepper %}
{% step %}

### Step 1 — 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 based on the following minimum requirements and your business needs.

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

{% step %}

### Step 2 — Install Helm to your workstation

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

No customization is needed.

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

{% step %}

### Step 3 — Install Traefik ingress

The ingress controller is needed for traffic routing to expose nodes (domains and applications). The CatalyX Blockchain Manager Besu service creates a CRD resource (IngressRoute when using Traefik) 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 in a separate namespace from the application.
{% endhint %}

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

{% step %}

### Step 4 — Install cert-manager to create a TLS certificate

A TLS certificate is needed for secured communication between a user and the CatalyX Blockchain Manager Besu service components.

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

We recommend using the latest release of the official Helm chart.

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

{% step %}

### Step 5 — Create an A-record in your domain's DNS management panel

CatalyX Blockchain Manager Besu service needs a wildcard record `*.<domain>` to expose nodes. All created nodes will have a `<NodeName>.<domainName>` address.

For example, on AWS:

1. Go to the Route53 service.
2. Create a new domain or choose an existing one.
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 the ELB balancer from the drop-down list (this is the ELB automatically configured during Traefik installation in Step 3).

You can check the ELB with:

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

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

{% step %}

### Step 6 — Create a namespace for the CatalyX Blockchain Manager Besu service

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

where `${ns_name}` is the name of the namespace (can be any name).

#### Step 6.1 — Get Helm repository credentials

Get credentials for the Helm repository in the JFrog Artifactory from the IntellectEU admin team.

#### Step 6.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 %}

### Step 7 — Create an ImagePullSecret

Create an ImagePullSecret to access the CatalyX Blockchain Manager Besu service deployable images. For example:

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

where:

* `${your-name}` — your Docker username
* `${your-password}` — your Docker password
* `${your-email}` — your Docker email
* `${ns_name}` — the namespace created in Step 6

{% hint style="info" %}
If you want to use a readiness check with a private image repository, create a Kubernetes secret with your credentials and specify it in the Helm chart. Refer to the [Kubernetes documentation on pulling from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

Ask IntellectEU to provide you with the Helm chart configuration instructions.
{% endhint %}
{% endstep %}

{% step %}

### Step 8 — Set up Keycloak realm

{% hint style="info" %}
To install Keycloak, follow the [Keycloak on Kubernetes guide](https://www.keycloak.org/getting-started/getting-started-kube).
{% endhint %}

Ask IntellectEU to provide you with the `realm.json` file, then import it to create the necessary clients, scopes, and users in your Keycloak realm.

{% hint style="info" %}
The user roles `besu_viewer` and `besu_writer` will be evaluated by the CatalyX Blockchain Manager Besu service.
{% endhint %}

{% hint style="warning" %}
After creating the realm, set the URL and realm name in the Helm chart values.
{% endhint %}
{% endstep %}
{% endstepper %}

## Setup

{% hint style="danger" %}
**Please contact IntellectEU to obtain access to CatalyX Blockchain Manager setup instructions.**
{% endhint %}


---

# 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-besu/version-1.1.0/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.