Installation Instructions
Prerequisites
1. Setup Kubernetes or OpenShift cluster
Supported version of Kubernetes: 1.21 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 requiremensts for the Catalyst Package Manager for 1 instance with:
-
2 core CPU
-
4GB RAM
-
10GB disk space
-
-
Other prerequisites: Canton Participant node, Canton Domain (optional). Minimal requirements for one node:
Node |
CPUe |
Memory, Gi |
Storage, Gi |
Domain |
1 |
1 |
1 |
Participant |
1 |
1 |
1 |
Application |
1 |
1 |
1 |
Deciding on the size of the cluster, please consider the expected load of the nodes and increase these values accordingly. |
2. Install Helm to your workstation
Installation manuals: helm.sh/docs/intro/install/
No customization is needed.
Supported version of Helm: 3.X. |
3. Install Traefik ingress
The ingress-controller is needed for traffic routing to expose nodes (domains & applications). The Catalyst Package Manager creates a CRD resource (IngressRoute in case of using Traefik), that is automatically started and deleted along with each application (and on demand for domains).
Installation manuals: github.com/traefik/traefik-helm-chart
No customization is needed, the default port ( :443 ) for HTTPS traffic will be used.
We recommend installing Traefik to a separate namespace from the application (creation of a namespace for the Catalyst Package Manager is described in step 6). |
NOTE: Supported version of Traefik: 2.3.
4. Install cert-manager to create TLS certificate
TLS certificate is needed for secured communication between a User and the Сatalyst Package Manager components.
Installation manuals: cert-manager.io/docs/installation/helm/
We recommend using the last release of the official helm chart.
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: |
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
Canton Package Manager needs a wildcard record *.<domain>'
to expose nodes. All created nodes (domains, participants, applications) will have a <NodeName>.<domainName>
address.
For example, in case you are using AWS, follow these steps:
-
Go to the Route53 service.
-
Create a new domain or choose the existing domain.
-
Create an A record.
-
Switch “alias” to ON.
-
In the “Route traffic to” field select “Alias to application and classic load balancer.”
-
Select your region (where the cluster is installed).
-
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:
|
6. Create a namespace for the Catalyst Package Manager application
kubectl create ns `${ns_name`}
where
— name of namespace (can be any).${ns_name
}
6.1 Get the credentials to the Helm repository in the JFrog artifactory provided by the IntellectEU admin team
In case you have any blocker please reach out to catalyst-support@intellecteu.com |
6.2 Add the repo to Helm with the username and password provided
helm repo add catbp-canton-package-manager https://intellecteu.jfrog.io/artifactory/catbp-canton-package-manager --username ${ARTIFACTORY_USERNAME} --password ${ARTIFACTORY_PASSWORD}
As a result: "helm-local" has been added to your repositories
7. Create an ImagePullSecret to access the Catalyst Package Manager deployable images
For example, create this Secret, naming it intellecteu-jfrog-access
:
kubectl create secret intellecteu-jfrog-access regcred --docker-server=intellecteu-catbp-docker-cpm.jfrog.io --docker-username= ${your-name} --docker-password= ${your-password} --docker-email=`${your-email} -n ${ns_name}
where:
-
${your-name
} -
${your-password
} -
${your-email
} -
${ns_name
}
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 for further specifying it in the Helm chart upon Catalyst Package Manager installation. Please refer to the official Kubernetes documentation: kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ Helm chart configuration instructions you will find here. |
Install CPM Daml Contract Templates (Dars)
Once logged into jFrog Artifactory download at
Install cpm-0.0.3.dar to your Canton Participant/Validator
Install CPM Helm Chart
Use the following command:
helm install ${cpm_release_name} catbp/canton-package-manager --values values.yaml -n ${ns_name}
where:
*
— name of the Catalyst Package Manager release. You can choose any name/alias. It is used to address for updating, deleting the Helm chart. * catbp/canton-package-manager — chart name, where “catbp” is a repository name, “canton-package-manager” is the chart name.${cpm_release_name
}
-
values.yaml — a values file.
-
${ns_name
}
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.
Setup
Configure helm chart values
Full list of the helm chart values
# -- Domain name where the application will be hosted
domainName: ""
# -- Override for the full release name used in resource names
fullnameOverride: "canton-package-manager"
ledger:
# -- Canton ledger API host address
host: ""
# -- Canton ledger API port number
port: "5001"
# -- Canton domain identifier
domainId: ""
# -- URL for the Canton ledger API
url: ""
mainService:
# -- Override for the main service name
nameOverride: ""
# -- Enable or disable the main service
enabled: true
# -- Additional environment variables for the main service
extraEnv: {}
image:
# -- Docker image repository
repository: intellecteu-catbp-docker-cpm.jfrog.io/catbp/canton/cmp/main-service
# -- Image tag
tag: ""
# -- Image pull policy
pullPolicy: IfNotPresent
# -- Secrets to use for pulling the image
imagePullSecrets: []
# -- Number of replicas
replicas: 1
service:
# -- Kubernetes service type
type: ClusterIP
# -- Service port number
port: 80
# -- Service port name
portName: http
# -- Container port to expose
containerPort: 80
# -- Custom labels for pods
labels: {}
# -- Resource requests and limits
resources: {}
# -- Node selector for scheduling
nodeSelector: {}
listingService:
# -- Override for the listing service name
nameOverride: ""
# -- Enable or disable the listing service
enabled: true
auth:
keycloak:
# -- Keycloak realm for authentication
realm: ""
# -- Keycloak server URL
url: ""
# -- Token endpoint URL
tokenUrl: ""
# -- Keycloak client ID
clientId: ""
# -- Keycloak client secret
clientSecret: ""
externalSecret:
# -- Enable external secret reference
enabled: false
# -- Reference to the remote secret
remoteSecretRef: ""
secretStoreRef:
# -- Name of the secret store
name: ""
# -- Kind of the secret store (SecretStore or ClusterSecretStore)
kind: "SecretStore"
image:
# -- Docker image repository
repository: intellecteu-catbp-docker-cpm.jfrog.io/catbp/canton/cmp/listing-service
# -- Image tag
tag: ""
# -- Image pull policy
pullPolicy: IfNotPresent
# -- Secrets to use for pulling the image
imagePullSecrets: []
# -- Number of replicas
replicas: 1
service:
# -- Kubernetes service type
type: ClusterIP
# -- Service port number
port: 80
# -- Service port name
portName: http
# -- Container port to expose
containerPort: 80
# -- Additional environment variables for the listing service
extraEnv: {}
# -- Custom labels for pods
labels: {}
# -- Resource requests and limits
resources: {}
# -- Node selector for scheduling
nodeSelector: {}
# UI component values
ui:
# -- Override for the ui name
nameOverride: ""
# -- number of ui pods to run
replicaCount: 1
# -- api image settings
image:
repository: intellecteu-catbp-docker-cpm.jfrog.io/catbp/canton/cmp/cpm-ui
pullPolicy: IfNotPresent
# defaults to appVersion
tag: ""
# -- api image pull secrets
imagePullSecrets: []
# - name: ""
# -- extra env variables for ui pods
extraEnv: {}
# -- labels for ui pods
labels: {}
# -- api service port and name
service:
port: 80
portName: http
# -- annotations for api pods
podAnnotations: {}
# -- securtiry context on a pod level
podSecurityContext:
# runAsNonRoot: true
# runAsUser: 4444
# runAsGroup: 5555
# fsGroup: 4444
# -- security context on a container level
securityContext: {}
# Define update strategy for UI pods
updateStrategy: {}
# -- CPU and Memory requests and limits
resources: {}
# requests:
# cpu: "100m"
# memory: "50Mi"
# limits:
# cpu: "200m"
# memory: "200Mi"
# -- Specify Node Labels to place api pods on
nodeSelector: {}
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/
tolerations: []
# -- https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
affinity: {}
# -- keycloak client secret is used to get token from keycloak (set in env-specific values)
keycloakClient:
id: ""
ingressConfig:
# Enable the creation of Ingress resources
enabled: false
# Select the ingress provider (supported: traefik, traefikCRD)
provider:
name: traefikCRD
traefik:
# Ingress class name to use when provider is "traefik"
ingressClass: ""
traefikCRD:
tlsStore:
# Enable or disable creation of TLSStore
enabled: false
# Name of the TLSStore to be used (default by Traefik)
name: default
# Ingress class name to be applied to all ingress resources
className: traefik
# Annotations for HTTP ingress routes
annotationsHttp:
traefik.ingress.kubernetes.io/router.entrypoints: web
# Annotations for HTTPS ingress routes
annotationsHttps:
traefik.ingress.kubernetes.io/router.entrypoints: websecure
# List of domains and their associated paths and services
hosts:
- host: ""
paths:
- path: /cpm-main-service
pathType: Prefix
service: cpm-main-service
- path: /cpm-listing-service
pathType: Prefix
service: cpm-listing-service
# TLS configuration options
tls:
# Enable or disable TLS for ingress
enabled: false
# Name of the existing secret with TLS certs (ignored if certManager is enabled)
secretName: canton-package-manager-tls
certManager:
# Enable automatic certificate management using Cert-Manager
enabled: true
# Email to use for Let's Encrypt registration
email: services.cat-bp@intellecteu.com
# ACME server URL (production or staging)
server: https://acme-v02.api.letsencrypt.org/directory
# Middleware configuration to strip path prefixes before routing
stripApplicationPrefix:
enabled: true
type: regex
# List of regex patterns to remove from the request path
regex:
- "^/[^/]+/api/"
Install CPM CLI client
Download CPM CLI JAR executable at
Create a configuration file containing a JSON object with the following keys:
-
authUrl:
Device Authorization Endpoint of your OAuth 2.0 provider. -
tokenUrl:
Token Endpoint of your OAuth 2.0 provider. -
authClientId:
The client id to use when obtainaing an access token. -
listingUrl:
The URL of the listing service to use. -
mainUrl:
The URL of your main service.
Example:
{
"authUrl": "https://YOUR_KEYCLOAK/auth/realms/YOUR_REALM/protocol/openid-connect/auth/device",
"tokenUrl": "https://YOUR_KEYCLOAK/auth/realms/YOUR_REALM/protocol/openid-connect/token",
"authClientId": "cpm-cli",
"listingUrl": "https://participant-cpm-validator.canton.prod.catalyst.intellecteu.io/cpm-listing-service/api",
"mainUrl": "https://your-main-service"
}
You can then run the cpm cli as or to make things a bit nicer use the following snippets to create a Unix (bash/zsh)
Windows (powershell)
|