Installation Instructions

Prerequisites

1. Setup Kubernetes or OpenShift cluster

Supported version of OpenShift: 4.7. Supported version of Kubernetes: 1.17 and later. We recommend AWS (EKS) or Google Cloud (GKE), but you can install it on a standalone cluster as well.
Define your cluster size considering the following minimum requirements and your business needs.
Minimal requirements for the Catalyst Blockchain Platform Hyperledger Fabric service for one organization — 1 instance with:
  • 2 core CPU
  • 4GB RAM
  • 10GB disk space
Minimal requirements for one node:
Node
CPU
Memory, Mi
Storage, Gi
CA
0.1
128
1
Peer
0.1
128
1
Orderer
0.1
128
1
Deciding on the size of the cluster, please consider the expected load of the nodes.
Note: Each chaincode installed to a peer runs as a separate pod and consumes additional resources (CPU and RAM).

2. Install Helm to your workstation

Installation manuals: https://helm.sh/docs/intro/install/ No customization is needed.
Supported version of Helm: 3.*.

3. Install Traefik ingress

The ingress-controller is needed for traffic routing to expose nodes (peer, CA, orderer). The Catalyst Blockchain Platform Hyperledger Fabric service creates a CRD resource (IngressRouteTCP in case of using Traefik or Route in case of using OpenShift), which is automatically started and deleted along with each node.
Installation manuals: https://github.com/traefik/traefik-helm-chart No customization is needed, the default port ( :443 ) for HTTPS traffic will be used.
Note: We recommend installing Traefik to a separate namespace from the application (creation of a namespace for the Catalyst Blockchain Platform Hyperledger Fabric service is described in step 6).
Supported version of Traefik: 2.3.
In case of using OpenShift, you should skip this step and specify it in the Helm chart values later (Helm chart values are described in the Setup section), because OpenShift has a built-in ingress-controller server.

4. Install cert-manager to create TLS certificate

TLS certificate is needed for secured communication between a User and the Сatalyst Blockchain Platform Hyperledger Fabric service components.
Installation manuals: https://cert-manager.io/docs/installation/helm/ We recommend using the last release of the official helm chart.
Note: You can skip this step and specify your TLS certificate and key as a Kubernetes secret in Helm chart values instead later (Helm chart values are described in the Setup section). You can find the manual on how to create a Kubernetes secret here: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets

5. Create an A-record in a zone in your domain's DNS management panel and assign it to the load balancer created upon Traefik or OpenShift installation

Catalyst Blockchain Platform Hyperledger Fabric service needs a wildcard record *.<domain> to expose nodes. All created nodes (peers, orderers, CAs) will have a <NodeName>.<domainName> address.
For example, in case you are using AWS, follow these steps:
  1. 1.
    Go to the Route53 service.
  2. 2.
    Create a new domain or choose the existing domain.
  3. 3.
    Create an A record.
  4. 4.
    Switch “alias” to ON.
  5. 5.
    In the “Route traffic to” field select “Alias to application and classic load balancer.”
  6. 6.
    Select your region (where the cluster is installed).
  7. 7.
    Select an ELB balancer from the drop-down list.*
*Choose the ELB balancer, which was automatically configured upon the Traefik chart installation as described in step 3 (or upon OpenShift installation in case of using OpenShift). You can check the ELB by the following command:
1
kubectl get svc -n ${ingress-namespace}
Copied!
where ${ingress-namespace} — the name of the namespace, where the ingress was installed. ELB is displayed in the EXTERNAL-IP field.

6. Create a namespace for the Catalyst Blockchain Platform Hyperledger Fabric service application

1
kubectl create ns ${ns_name}
Copied!
where ${ns_name} — name of namespace (could be any). 6.1. Get the credentials to the Helm repository in the JFrog artifactory provided by the IntellectEU admin team.
6.2. Add the repo to Helm with the username and password provided:
1
helm repo add catbp <https://intellecteu.jfrog.io/artifactory/catbp-helm> --username ${ARTIFACTORY_USERNAME} --password ${ARTIFACTORY_PASSWORD}
Copied!
As a result: "catbp" has been added to your repositories

7. Create a "secret" file in Kubernetes (or OpenShift) with the provided by the IntellectEU admin team username and password in the namespace you created earlier

For example, create this Secret, naming it intellecteu-jfrog-access:
1
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}
Copied!
where:
  • ${your-name} — your Docker username.
  • ${your-password} — your Docker password.
  • ${your-email} — your Docker email.
  • ${ns_name} — the namespace created for the Catalyst Blockchain Platform Hyperledger Fabric service on the previous step.

8. Deploy a message broker

Currently, only RabbitMQ is supported.
Version: 3.7 and later.
No specific configurations are needed. You can check the official production checklist: https://www.rabbitmq.com/production-checklist.html
We recommend 1GB RAM as a minimum setup.
Info: In case you want to use a readiness check and use a private repository for the image, you should create a “secret” file with your credentials in Kubernetes/OpenShift for further specifying it in the Helm chart upon Catalyst Blockchain Platform installation. Please refer to the official Kubernetes documentation: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
Helm chart configuration instructions you will find here.

9. Deploy a database

Catalyst Blockchain Platform supports PostgreSQL and MySQL. You can use any.
Supported version of PostgreSQL: 12.8 and later.
Supported version of MySQL: 8.0.21 and later.
No specific configurations are needed. You can use the official manuals:
We recommend 1GB RAM as a minimum setup.
Info: In case you want to use a readiness check and use a private repository for the image, you should create a “secret” file with your credentials in Kubernetes/OpenShift for further specifying it in the Helm chart upon Catalyst Blockchain Platform installation. Please refer to the official Kubernetes documentation: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
Helm chart configuration instructions you will find here.

As a result, you will get:

  1. 1.
    Kubernetes (or Openshift) cluster deployed.
  2. 2.
    Helm installed to your workstation.
  3. 3.
    Traefik ingress installed to your Kubernetes cluster. In case of using OpenShift you should skip this step. You will specify OpenShift in the Helm chart values instead (as described in the Setup section).
  4. 4.
    Cert-manager installed to your cluster or TLS certificate prepared.
  5. 5.
    A-record created, for example, in your account on AWS or Google Cloud.
  6. 6.
    Namespace created in your cluster and Helm repository added to your workstation.
  7. 7.
    Kubernetes (OpenShift) secret created in the namespace on your Kubernetes (OpenShift) cluster.
  8. 8.
    A message broker (RabbitMQ) deployed.
  9. 9.
    A database deployed.

Setup

Configure helm chart values

Following values are needed to be configured.
  • domainName
1
# -- address where application will be hosted. All created nodes (peers, orderers, cas) will have <NodeName>.proxy.<domainName> address
2
domainName: ""
Copied!
  • auth
You can choose one of two possible methods:
  • basicAuth
  • openID
1
# -- auth config
2
auth:
3
# -- enabled auth for api/v1 endpoints
4
enabled: true
5
# -- available methods are: 'basic', 'openid'
6
method: basic
7
# -- BasicAuth
8
basic:
9
## -- BasicAuth username
10
username: ""
11
## -- BasicAuth password
12
password: ""
13
14
# -- OpenID authorization scheme. Only public access type is supported.
15
openid:
16
## --OpenID provider endpoint for obtaining access token
17
url: ""
18
## -- OpenID configuration is a Well-known URI Discovery Mechanism
19
wellKnownURL: ""
20
## - OpenID client ID
21
clientID: ""
Copied!
  • openshiftRoute
Specify enabled = true in case of using OpenShift.
1
# -- Route for Openshift Controller
2
openshiftRoute:
3
enabled: false
4
# -- it requires a raw certificate here
5
certificate: ""
6
# -- it requires a raw private key here
7
key: ""
Copied!
  • ingressConfig
1
2
# -- IngressRoute for Traefik Ingress Controller
3
ingressConfig:
4
# -- specify whether to create IngresRoute resource
5
enabled: false
6
tls:
7
enabled: false
8
# -- Certificate and Issuer will be created with Cert-Manager. Names will be autogenerated.
9
# if `certManager.enabled` `ingressConfig.tls.secretName` will be ignored
10
certManager:
11
enabled: false
12
13
server: "https://acme-staging-v02.api.letsencrypt.org/directory"
14
# -- secret name with own tls certificate to use with ingress
15
secretName: ""
16
tlsStore:
17
enabled: false
Copied!
  • amqp
Configure connection settings to your message broker.
1
# -- external RabbitMQ Message broker parameters
2
amqp:
3
readinessCheck:
4
# -- Whether to perform readiness check with initContainer. Simple `nc` command
5
enabled: true
6
# -- which image to use for initContainer performing readiness check
7
initContainer:
8
image:
9
repository: busybox
10
pullPolicy: IfNotPresent
11
tag: latest
12
# -- example values for rabbitmq queue. change them for your env
13
host: "rabbitmq.rabbitmq"
14
port: "5672"
15
username: "test1"
16
password: "Abcd1234"
17
vhost: "test1"
18
Copied!
Info: In case of using a private repository specify the secret you created before in the api.imagePullSecrets section:
1
api:
2
imagePullSecrets:
3
- name: mysecret1 # for registry with api images
4
- name: mysecret2 # for registry with busybox images
5
Copied!
  • database
Configure connection settings to your database.
1
# -- external database parameters
2
database:
3
readinessCheck:
4
# -- Whether to perform readiness check with initContainer. Simple `nc` command
5
enabled: true
6
# -- which image to use for initContainer performing readiness check
7
initContainer:
8
image:
9
repository: busybox
10
pullPolicy: IfNotPresent
11
tag: latest
12
# -- database type. `postgres` or `mysql` can be specified here
13
type: postgres
14
# -- example values for postgres database. change them for your env
15
host: "postgresql.postgresql"
16
port: "5432"
17
username: "test1"
18
password: "Abcd1234"
19
dbname: "test1"
20
Copied!
Info: In case of using a private repository specify the secret you created before in the api.imagePullSecrets section:
1
api:
2
imagePullSecrets:
3
- name: mysecret1 # for registry with api images
4
- name: mysecret2 # for registry with busybox images
5
Copied!
You can configure other helm chart values if needed. You can see the full list of values here:
1
## -- Declare variables to be passed into your templates.
2
3
# -- address where application will be hosted. All created nodes (peers, orderers, cas) will have <NodeName>.<domainName> address
4
domainName: ""
5
# -- available envs: prod, staging, testing, dev. For customer usage suggested only 'prod'
6
logs:
7
level: info
8
# -- auth config
9
auth:
10
# -- enabled auth for api/v1 endpoints
11
enabled: true
12
# -- available methods are: `basic`, `openid`
13
method: basic
14
# -- BasicAuth
15
basic:
16
## -- BasicAuth username
17
username: ""
18
## -- BasicAuth password
19
password: ""
20
# -- OpenID authorization mechanism
21
openid:
22
## --OpenID provider endpoint for obtaining access token
23
url: ""
24
## -- OpenID configuration is a Well-known URI Discovery Mechanism
25
wellKnownURL: ""
26
## - OpenID client ID
27
clientID: ""
28
# # - OpenID client secret
29
# clientSecret: ""
30
# -- Whether to parse and send logs to centralised storage
31
# FluentD Output Configuration. Fluentd aggregates and parses logs
32
# FluentD is a part of Logging Operator. CRs `Output` and `Flow`s will be created
33
logOutput:
34
# -- This section defines Loki specific configuration
35
loki:
36
enabled: false
37
# -- url of loki instance
38
url: http://loki.logging.svc.cluster.local:3100
39
# -- labels to set on log streams
40
# format `label_name`: `log_field_name`
41
labels:
42
namespace: namespace
43
app_name: app_name
44
# -- This section defines logz.io specific configuration
45
logzIo:
46
enabled: false
47
# -- message bus configuration
48
messageBus:
49
queue: message_bus
50
topic: message_bus_exchange
51
# -- this module enabled integration with prometheus-operator. Fetches metrics from all the peers, orderers and CAs in the system
52
monitoring:
53
# -- specify whether to create monitoring resources
54
# prometheus operator and grafana need to be installed beforehand
55
enabled: false
56
# -- configuration for ServiceMonitor resource
57
serviceMonitor:
58
enabled: false
59
# -- how often to pull metrics from resources
60
interval: 15s
61
# -- HTTP path to scrape for metrics
62
path: /metrics
63
# -- RelabelConfigs to apply to samples before scraping
64
relabelings: []
65
# -- MetricRelabelConfigs to apply to samples before ingestion
66
metricRelabelings: []
67
grafana:
68
# -- grafana default admin username and email. Grafana is authenticated through default API authentication automatically.
69
user: admin
71
# -- grafana defaul path to dashboard
72
dashboardPath: "/grafana/d/pUnN6JgWz/hyperledger-fabric-monitoring?orgId=1&refresh=30s&kiosk&var-namespace="
73
# -- grafana service and port for ingress
74
service:
75
name: grafana
76
namespace: monitoring
77
port: 80
78
# -- Route for Openshift Controller
79
openshiftRoute:
80
enabled: false
81
# -- it requires a raw certificate here
82
certificate: ""
83
# -- it requires a raw private key here
84
key: ""
85
# -- IngressRoute for Traefik Ingress Controller
86
ingressConfig:
87
# -- specify whether to create IngresRoute resource
88
enabled: false
89
tls:
90
enabled: false
91
# -- Certificate and Issuer will be created with Cert-Manager. Names will be autogenerated.
92
# if `certManager.enabled` `ingressConfig.tls.secretName` will be ignored
93
certManager:
94
enabled: false
95
96
server: "https://acme-staging-v02.api.letsencrypt.org/directory"
97
# -- secret name with own tls certificate to use with ingress
98
secretName: ""
99
tlsStore:
100
enabled: false
101
rbac:
102
# -- Whether to create RBAC Resourses (Role, SA, RoleBinding)
103
enabled: true
104
# -- Service Account Name to use for api, ui, operator, consumer
105
serviceAccountName: fabric-console
106
# operator component values
107
operator:
108
# -- number of operator pods to run
109
replicaCount: 1
110
# -- operator image settings
111
image:
112
repository: intellecteu-catbp-docker.jfrog.io/catbp/fabric-platform/fabric-console
113
pullPolicy: Always
114
tag: 2.2
115
# -- operator image pull secrets
116
imagePullSecrets:
117
- name: intellecteu-jfrog-access
118
# -- annotations for operator pods
119
podAnnotations: {}
120
# -- security context on a pod level
121
podSecurityContext: {}
122
# -- security context on a container level
123
securityContext: {}
124
# -- CPU and Memory requests and limits
125
resources:
126
limits:
127
cpu: "150m"
128
memory: "300Mi"
129
requests:
130
cpu: "100m"
131
memory: "100Mi"
132
# -- Specify Node Labels to place operator pods on
133
nodeSelector: {}
134
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
135
tolerations: []
136
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
137
affinity: {}
138
# -- metrics server and Prometheus Operator configuration
139
metrics:
140
# -- should metrics server be enabled
141
enabled: false
142
# -- service port for metrics server
143
servicePort: 8082
144
# -- container port for metrics server
145
containerPort: 8082
146
# -- HTTP path to scrape for metrics.
147
path: /metrics
148
serviceMonitor:
149
# -- should ServiceMonitor be created
150
enabled: false
151
# -- how often to pull metrics from resources
152
interval: 30s
153
# -- RelabelConfigs to apply to samples before scraping
154
relabelings: []
155
# -- MetricRelabelConfigs to apply to samples before ingestion.
156
metricRelabelings: []
157
## api component values
158
api:
159
# -- api autoscaling settings
160
autoscaling:
161
enabled: false
162
minReplicas: 1
163
maxReplicas: 5
164
targetCPUUtilizationPercentage: 80
165
# targetMemoryUtilizationPercentage: 80
166
# -- number of api pods to run
167
replicaCount: 1
168
# -- api image settings
169
image:
170
repository: intellecteu-catbp-docker.jfrog.io/catbp/fabric-platform/fabric-console
171
pullPolicy: Always
172
tag: 2.2
173
# -- api image pull secrets
174
imagePullSecrets:
175
- name: intellecteu-jfrog-access
176
# -- api service port and name
177
service:
178
port: 8000
179
portName: http
180
# -- annotations for api pods
181
podAnnotations: {}
182
# -- securtiry context on a pod level
183
podSecurityContext: {}
184
# -- security context on a container level
185
securityContext: {}
186
# -- CPU and Memory requests and limits
187
resources:
188
limits:
189
cpu: "150m"
190
memory: "500Mi"
191
requests:
192
cpu: "100m"
193
memory: "200Mi"
194
# -- Specify Node Labels to place api pods on
195
nodeSelector: {}
196
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
197
tolerations: []
198
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
199
affinity: {}
200
# -- metrics server and Prometheus Operator configuration
201
metrics:
202
# -- should metrics server be enabled
203
enabled: false
204
# -- service port for metrics server
205
servicePort: 8082
206
# -- container port for metrics server
207
containerPort: 8082
208
# -- HTTP path to scrape for metrics.
209
path: /metrics
210
serviceMonitor:
211
# -- should ServiceMonitor be created
212
enabled: false
213
# -- how often to pull metrics from resources
214
interval: 30s
215
# -- RelabelConfigs to apply to samples before scraping
216
relabelings: []
217
# -- MetricRelabelConfigs to apply to samples before ingestion.
218
metricRelabelings: []
219
ui:
220
# -- number of ui pods to run
221
replicaCount: 1
222
# -- ui image settings
223
image:
224
repository: intellecteu-catbp-docker.jfrog.io/catbp/fabric-platform/fabric-console-ui
225
tag: 2.2
226
# -- api image pull secrets
227
imagePullSecrets:
228
- name: intellecteu-jfrog-access
229
# -- ui service port and name
230
service:
231
port: 3001
232
portName: http
233
# -- annotations for consumer pods
234
podAnnotations: {}
235
# -- security context on a pod level
236
podSecurityContext: {}
237
# -- security context on a container level
238
securityContext: {}
239
# -- CPU and Memory requests and limits
240
resources:
241
limits:
242
cpu: "100m"
243
memory: "100Mi"
244
requests:
245
cpu: "30m"
246
memory: "50Mi"
247
# -- Specify Node Labels to place ui pods on
248
nodeSelector: {}
249
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
250
tolerations: []
251
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
252
affinity: {}
253
# -- external RabbitMQ Message broker parameters
254
amqp:
255
readinessCheck:
256
# -- Whether to perform readiness check with initContainer. Simple `nc` command
257
enabled: true
258
# -- which image to use for initContainer performing readiness check
259
initContainer:
260
image:
261
repository: busybox
262
pullPolicy: IfNotPresent
263
tag: latest
264
# -- example values for rabbitmq queue. change them for your env
265
host: "rabbitmq.rabbitmq"
266
port: "5672"
267
username: "test1"
268
password: "Abcd1234"
269
vhost: "test1"
270
# -- external database parameters
271
database:
272
readinessCheck:
273
# -- Whether to perform readiness check with initContainer. Simple `nc` command
274
enabled: true
275
# -- which image to use for initContainer performing readiness check
276
initContainer:
277
image:
278
repository: busybox
279
pullPolicy: IfNotPresent
280
tag: latest
281
# -- database type. `postgres` or `mysql` can be specified here
282
type: postgres
283
# -- example values for postgres database. change them for your env
284
host: "postgresql.postgresql"
285
port: "5432"
286
username: "test1"
287
password: "Abcd1234"
288
dbname: "test1"
Copied!

Install the Catalyst Blockchain Platform Hypeledger Fabric service

Use the following command:
1
helm upgrade --install ${fabric_release_name} catbp/fabric-console --values values.yaml -n ${ns_name}
Copied!
where:
  • ${fabric_release_name} — name of the Catalyst Blockchain Platform Hypeledger Fabric service
    release. You can choose any name/alias. It is used to address for updating, deleting the Helm chart.
  • catbp/fabric-console— chart name, where “catbp” is a repository name, “fabric-console” is the chart name.
  • values.yaml — a values file.
  • ${ns_name} — name of the namespace you've created before.
You can check the status of the installation by using these commands:
  • helm ls— check the "status" field of the installed chart.
Status “deployed” should be shown.
  • kubectl get pods— get the status of applications separately.
All pods statuses must be “running.”
  • kubectl describe pod $pod_name — get detailed information about pods.
Last modified 5d ago