Documentation archive
v4.0.0
Deploy
Install
Install Rhize services
⚠️
This documentation is for Rhize v4.0.0. If you don’t need a specific version, switch to the latest documentation

Install Rhize services

The final installation step is to install the Rhize services in your Kubernetes cluster.

Prerequisites

This topic assumes you have done the following:

  • Set up Kubernetes and Configured Keycloak. All the prerequisites for those topics apply here.

  • Configured load balancing for the following DNS records:

    ServiceDomain
    Admin UIrhize-ui.<YOUR_DOMAIN>
    Keycloakrhize-auth.<YOUR_DOMAIN>
    GraphQLrhize-api.<YOUR_DOMAIN>
    NATSrhize-mqtt.<YOUR_DOMAIN>
    Grafanarhize-grafana.<YOUR_DOMAIN>

    Note that rhize- is only the recommended prefix of the subdomain. Your organization may use something else.

Overrides

Each service is installed through a Helm YAML file. For some of these services, you might need to edit this file to add credential information and modify defaults.

Common values that are changed include:

  • URLs and URL links
  • The number of replicas running for each pod
  • Ingress values for services exposed on the internet

Get client secrets

Client secrets are necessary for Rhize services to authenticate with Keycloak. These secrets are stored with Kubernetes secrets.

  1. Go to Keycloak and get the secrets for each client you’ve created.

  2. Create Kubernetes secrets for each service. You can either create a secret file, or pass raw data from the command line.

    How you create Kubernetes secrets depends on your implementation details and security procedures. For guidance, refer to the official Kubernetes topic, Managing Secrets using kubectl.

    With raw data, the command might look something like this:

    kubectl create secret generic libre-client-secrets \
  -n libre \
  --from-literal=dashboard=G4hoxIL37F5S9DQgeDYGQejcJ6oJhOPA \
  --from-literal=libreWorkflow=GTy1x64U0IHAUTWizugEAnN47a9kWgX8 \
  --from-literal=libreISA95=Yvtx1tZWCPFayvDCzHTTInEz9gnuLyLc \
  --from-literal=libreBaas=KYbMHlRLhXwiDNFuDCl3qtPj1cNdeMSl \
  --from-literal=libreUI=54yUQqmvgcxoKPaIbPZTQGlEs8Xu2qH0

  3. Create secrets for login passwords. Each service with its own user in Keycloak can have its password supplied through Kubernetes secrets.

    As you install services through Helm, their respective YAML files reference these secrets.

Add the Rhize Helm Chart Repository

You must add the helm chart repository for Rhize.

  1. Add the Helm Chart Repository

    helm repo add libre https://gitlab.com/api/v4/projects/42214456/packages/helm/stable
helm repo update

Install and add roles for the DB

You must install the libreBaas database service first. You also need to configure the libreBaas service to have roles in Keycloak.

If enabling the Audit Trail, also the include the configuration in Enable change data capture.

If you need Row Level Access Control, configure your scope map.

  1. Modify the DB Helm file with your code editor. Edit any necessary overrides.

  2. Use Helm to install the database:

    helm install -f baas.yaml libre-baas libre/baas -n libre

    To confirm it works, run the following command:

    kubectl get pods

    All statuses should be RUNNING.

  3. Return to the Keycloak UI and add all libre roles to the admin group.

  4. Proxy the http:8080 port on libre-baas-dgraph-alpha.

    kubectl port-forward -n libre pod/baas-baas-alpha-0 8080:8080

  5. Get a token using the credentials. With curl, it looks like this:

    curl --location --request POST '<KEYCLOAK_URL>/realms/libre/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'client_id=libreBaas' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

  6. Post the schema:

    curl --location --request POST '<BAAS_URL>/admin/schema' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/octet-stream' \
--data-binary '@<SCHEMA_FILE>'

    This creates more roles.

  7. Go to Keycloak UI and add all new libreBaas roles to the libreAdminGroup.

If the install is successful, the Keycloak UI is available on its default port.

Install services

Each of the following procedures installs a service through Helm.

The syntax to install a Rhize service must have arguments for the following:

  • The chart YAML file
  • The packaged chart
  • The path to the unpackaged chart or directory

Additionally, use the -n flag to ensure that the install is scoped to the correct namespace:

helm install <service_name> \
  -f <service-overide-file>.yaml \
  <path/to/directory> \
  -n <ns>

For the full configuration options, read the official Helm install reference.

Redpanda

Rhize uses Redpanda to buffer requests to Restate and connect to Agent.

Install Redpanda with these steps:

  1. If the Redpanda repository doesn’t exist, add it:

    helm repo add redpanda https://charts.redpanda.com
helm repo update

  2. Modify the Redpanda Helm overrides as needed.

  3. Install with Helm:

    helm install redpanda -f redpanda.yaml redpanda/redpanda -n libre

Alloy

Install Alloy with these steps:

  1. If the Grafana repository doesn’t exist, add it:

    helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

  2. Modify the Alloy Helm overrides as needed.

  3. Install with Helm:

    helm install alloy -f alloy.yaml grafana/alloy -n libre

Grafana LGTM

Grafana LGTM includes Tempo and Grafana. Rhize uses Tempo to trace BPMN processes.

Install Grafana LGTM with these steps:

  1. Modify the Grafana LGTM Helm overrides as needed.

  2. Install with Helm:

    helm install lgtm-distributed -f lgtm-distributed.yaml grafana/lgtm-distributed -n libre

If the install is successful, the Grafana service is available on its default port.

Restate

Rhize uses Restate as a platform for orchestrating other services.

Install Restate with these steps:

  1. Modify the Restate Helm overrides as needed.

  2. Install with Helm:

    helm install restate -f restate.yaml oci://ghcr.io/restatedev/restate-helm -n libre

So that you can register certain services with Restate, proxy the Restate port:

kubectl port-forward -n libre pod/restate-0 9070:9070

Workflow

The Workflow service is the custom engine Rhize uses to process low-code workflows modeled in the Workflow UI.

Requirements: The Workflow service requires the libreBaas, Restate, and Tempo services.

Install Workflow with these steps:

  1. Modify the Workflow Helm overrides as needed.

  2. Install with Helm:

    helm install workflow -f workflow.yaml libre/workflow -n libre

  3. When the Workflow service starts, it should register with Restate. Verify this with:

    curl localhost:9070/deployments | jq '.deployments[].uri'

    This will show the URL of each registered service. If Workflow’s URL is not present, register it with:

    curl --location 'http://localhost:9070/deployments' \
  --header 'Content-Type: application/json' \
  --data '{"uri":"http://workflow.libre.svc.cluster.local:29080", "force":true}'

Typescript Host Service

Install Typescript Host Service with these steps:

  1. Modify the Typescript Host Service Helm overrides as needed.

  2. Install with Helm:

    helm install typescript-host-service -f typescript-host-service.yaml libre/typescript-host-service -n libre

  3. When the Typescript Host Service starts, it should register with Restate. Verify this with:

    curl localhost:9070/deployments | jq '.deployments[].uri'

    This will show the URL of each registered service. If Typescript Host Service’s URL is not present, register it with:

    curl --location 'http://localhost:9070/deployments' \
  --header 'Content-Type: application/json' \
  --data '{"uri":"http://typescript-host-service.libre.svc.cluster.local:9081", "force":true}'

QuestDB

QuestDB is used by Rhize to store timeseries data, however it can be substitude for another historian.

Install QuestDB with these steps:

  1. If it doesn’t exist, add the QuestDB repository:

    helm repo add questdb https://helm.questdb.io/
helm repo update

  2. Modify the QuestDB Helm overrides as needed.

  3. Install with Helm:

    helm install questdb -f questdb.yaml questdb/questdb -n libre

ISA-95

Install ISA-95 with these steps:

  1. Modify the ISA-95 Helm overrides as needed.

  2. Install with Helm:

    helm install isa95 -f isa95.yaml libre/isa95 -n libre

  3. When the ISA-95 service starts, it should register with Restate. Verify this with:

    curl localhost:9070/deployments | jq '.deployments[].uri'

    This will show the URL of each registered service. If ISA-95’s URL is not present, register it with:

    curl --location 'http://localhost:9070/deployments' \
  --header 'Content-Type: application/json' \
  --data '{"uri":"http://isa95.libre.svc.cluster.local:29080", "force":true}'

Install Admin UI

The Rhize agent bridges your plant processes with the Rhize data hub.

The Admin UI is the graphical frontend to handle events and define work masters.

Requirements: The Admin UI requires the Workflow services.

After installing all other services, install the UI with these steps:

  1. Modify the UI Helm overrides as needed.

  2. Install with Helm:

    helm install admin-ui -f admin-ui.yaml libre/admin-ui -n libre

If the install is successful, the UI is available on its default port.

Agent

The Rhize agent bridges your plant processes with the Rhize data hub. It collects data emitted from the plant and publishes it to the message broker.

Requirements: Agent requires the Graph DB, Tempo, Redpanda, and an event broker service to communicate with.

Install Agent with these steps:

  1. Modify the Agent Helm overrides as needed.

  2. In the Rhize UI, add a Data Source for Agent to interact with:

    • In the lefthand menu, open Master Data > Data Sources > + Create Data Source.
    • Input a name for the Data Source.
    • Add a Connection String and Create.
    • Add any relevant Topics.
    • Activate the Data Source.

  3. Install with Helm:

    helm install agent -f agent.yaml libre/agent -n libre

To verify that Agent is working, check the Redpanda UI.

Optional Services

Audit Trail

The Rhize Audit service provides an audit trail for database changes. The Audit service uses PostgreSQL for storage.

Install Audit with these steps:

  1. Modify the Audit trail Helm YAML file. It is recommended to change the PostgreSQL username and password values.

  2. Install with Helm:

    helm install audit -f audit.yaml libre/audit -n libre

  3. Create partition tables in the PostgreSQL database:

    create table public.audit_log_partition( like public.audit_log );
select partman.create_parent( p_parent_table := 'public.audit_log', p_control := 'time',  p_interval := '1 Month', p_template_table := 'public.audit_log_partition');

For details about maintaining the Audit trail, read Archive the PostgresQL Audit trail.

Enable change data capture

The Audit trail requires change data capture (CDC) to function. To enable CDC in libre BAAS, include the following values for the Helm chart overrides:

alpha:
  # Change Data Capture (CDC)
  cdc:
    # Enable
    enabled: true
    # If configured for security, configure in NATS url. For example `nats://username:password@nats:4222`
    nats: nats://nats:4222
    # Adjust based on high-availability requirements and cluster size.
    replicas: 1

KPI

The Rhize KPI service is a GraphQL service which calcualtes ISO22400 KPIs using timseries tables.

Install KPI with these steps:

  1. Modify the KPI Helm overrides as needed.

  2. Install with Helm:

    helm install kpi -f kpi.yaml libre/kpi -n libre

Solace

Solace is an event broker that can be used alongside Agent, though it can be substituted for any other event broker.

  1. Add the Solace Charts Helm repo.

    helm repo add solacecharts https://solaceproducts.github.io/pubsubplus-kubernetes-helm-quickstart/helm-charts
helm repo update

  2. Modify the Solace Helm overrides as needed.

  3. Install with Helm:

    helm install solace -f solace.yaml solacecharts/pubsubplus -n libre

Note

Solace can be installed in high availability by using pubsubplus-ha instead of pubsubplus. See detailed instructions on github.

Apollo Router

While Rhize provides a built in GraphQL Playground using Apollo’s Sandobx, Apollo Router can be installed to unite queries for different services in a single endpoint outside of Rhize’s interface.

Requirements: Router requires the GraphDB service.

Install Router with these steps:

  1. Modify the Router Helm overrides as needed.

  2. Install with Helm:

    helm install router -f router.yaml libre/router -n libre

If the install is successful, the Router explorer is available on its default port.

Optional: change service configuration

The services installed in the previous step have many parameters that you can configure for your performance and deployment requirements. Review the full list in the Service configuration reference.

Troubleshoot

For general Kubernetes issues, the Kubernetes dashboard is great for troubleshooting, and you can configure it to be accessible through the browser.

For particular problems, try these commands:

  • Is my service running?

    To check deployment status, use this command:

     kubectl get deployments

    Look for the pod name and its status.

  • Access service through browser

    Some services are accessible through the browser. To access them, visit local host on the service’s default port.

  • I installed a service too early. If you installed a service too early, use Helm to uninstall:

    helm uninstall libreBaas

    Then perform the steps you need and reinstall when ready.

Configure KeycloakRow Level Access Control