This page describes the steps for installing Smartfacts for testing Smartfacts in a Proof of Concept. To simplify the installation process, Smartfacts is not connected to your OIDC provider. Instead, a Keycloak is contained in the deployment, which is used as the OIDC provider.

Preparations

If not done so far please prepare your infrastructure as described in https://smartfacts.atlassian.net/wiki/spaces/SPD/pages/54624257/Installing+Smartfacts+for+Proof+of+Concepts#Prepare-your-infrastructure.

Setup the Kubernetes Environment

You need a Kubernetes cluster to deploy Smartfacts in. If you already have a Kubernetes infrastructure on AWS, GCP or Azure, you can use this.

If you don’t have a Kubernetes infrastructure you can set up a single node cluster at a vm. The following section will describe how to set zu such a cluster.

Install k3s

curl -sfL https://get.k3s.io | sh -

Wait 30 seconds.

You can test it with the command sudo kubectl get node. It will provide an output similar to this one:

NAME   STATUS  ROLES                 AGE   VERSION

mysrv  Ready   control-plane,master  161d  v1.23.6+k3s1

For more information see: https://rancher.com/docs/k3s/latest/en/quick-start

Install helm

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 && chmod 700 get_helm.sh && ./get_helm.sh

For more information see: https://helm.sh/docs/intro/install

Set Link to Cluster Configuration

sudo mkdir -p /root/.kube
sudo ln -s /etc/rancher/k3s/k3s.yaml /root/.kube/config

Prepare Deployment

Add MID Repository

You will need a username and password to download the helm chart and containers from MID's repository. You will receive username and password from your MID contact or from cops@mid.de.

sudo helm repo add mid-smartfacts https://repo.secure.mid.de/chartrepo/smartfacts --username <USERNAME> --password <PASSWORD>

sudo helm repo update

Provide Certificates and Key as Base64 String

Prerequisite: The complete certificate chain is in a file as base64-encoded x509 certificates. The certificates are contained in the file in the correct order (server certificate at the top, root certificate at the bottom). See Section “Certificates” above in this article.

Save certificate chain as a base64 string:

cat <your certificate chain.crt> | base64 -w0 > chain.crt.base64

Save certificate key as base64 string:

cat <your certificate key.key> | base64 -w0 > key.base64

Customize Values File

• Change to your user's home directory on the server and create a new text file values.yaml with the following content:

  global:
    domain: "<your-domain>"
    instance: "smartfacts-poc"
    registry: "repo.mid.de"
    repologin: <login provided by MID>
    cert:
      crtFullChain: "<FULL-CHAIN-CERT-BASE64>"
      key: "<CERT-KEY-BASE64>"
    ingress:
      enabled: true
      # Smartfacts supports Traefik and nginx as Ingress Controller. 
      # The default is Traefik.
      # If you use nginx as ingress controller please comment in this line:
      #ingressClassType: "nginx" 
  spa:
    cspConf:
      externalUrls: "" # space separated list of your tool urls (IBM Jazz, Jama, Codebeamer)
  plugin:
    importPlugins: true # "true" for first installation, "false" for minor updates will speed up the update process a lot
  genoslc:
    enabled: true # Set to false if you want to use Smartfacts only (no OSLC connection to itger tools). In this case you cann skip the rest of this "genoslc" section.
    env:
      trsEnabled: false # Set to true if you use Smartfacts as data source for a link index
      configuration:
        # Give a list of up to 5 usernames of users which will have the administration right to change settings in Smartfacts.
        # At leas one administrator user must be stated here.
        administrators: 
          - acm # replace this value with the username of the person who should configure the oauth10a information for the OSLC Connector for Smartfacts
        # key used to encrypt the oauth10a configuration data
        oauth10aEncryptionKey: "" # define the key which is used to encrypt the oauth10a information in the database
  mailservice:
    enabled: false
  camp:
    enabled: false
  kafka:
    enabled: false

• Replace the value of the domain property with your domain name.

• Replace the value of the repologin property with the value provided from MID.

• Replace the placeholder of the crtFullChain property with the content of the file chain.crt.base64.

• Replace the placeholder of the key property with the content of the key.base64 file.

• Replace the placeholder for the externalUrls property with the URL of your Jama or Codebeamer instance. If you connect multiple instance delement the URLs with a space.

• Save the values.yaml file.

Install Smartfacts

Execute the Installation

Enter the following command to execute the Installation:

sudo helm upgrade --install --timeout 20m0s smartfacts mid-smartfacts/smartfacts -f values.yaml --version 4.6.4-genoslcv2 -n smartfacts --create-namespace

Watch Deployment (in a new Session)

Open a second session on the server and enter the following command:

sudo watch kubectl get deployments -n smartfacts

As soon as all deployments are available, the installation is ready.

A note on Smartfacts PoC Test Users

For the Smartfacts PoC you can use the generated test users “poc1”…”poc50”. All poc-users have the same password “poc”. For managing the test users in the CAMP use the account administrator user “acm” which has the password “acm”.

Setting-Up the CAMP (Customer Accounts for MID Products)

Create the Account

This section is used to add the users who will be authorized to use the instance and to assign the licenses. When you open https://camp.<yoursmartfactsdomain>, and log in with the user “acm” (password “acm”) you will be taken to account setup wizard.

1. In section 1, upload the license file MID has provided in step 4 by clicking the  upload button in the upper right-hand corner and by selecting the license file.

2. In section 2, set an account name.

3. In section 3, synchronize the users from OpenLDAP to CAMP by clicking UPDATE USERS AND GROUPS.

4. Assign licenses to users and groups in the CAMP.

   Activate the control box for the user “acm@smartfacts.local” assign licenses by clicking ASSIGN LICENSES.

The creation of the account is now complete and licenses are assigned to the acm user.

Assign licenses to all users

Please log out from the camp an log in again. After the account setup wizard is now complete, the CAMP will now display the account management page.

To activate the Smartfacts license for all users, follow these steps:

1. Scroll to the section “Groups” at the bottom of the page

2. Create a new group called “Smartfacts users” and acitvate the slider “Automatically add all users to group”

   

3. Klick the button “ADD”

4. Scroll to the section “Licenses” at the top of the page

5. Klick on the “Assign licenses” symbol for the Smartfacts license
   

   

6. Change the filter from “SHOW ALL” to “ONLY GROUPS”

7. Activate the check box of the group “Smartfacts users”
   

   

8. Klick the button “CONFIRM”

Now all Users have a Smartfacts license assigned.

Create a Smartfacts Model Warehouse

1. Open the Smartfacts URL in your browser: https://smartfacts.<yoursmartfactsdomain> and log-in with the account manager credentials (user “acm”, password “acm”).

2. You will now be asked to create a Model Warehouse.

   1. Click on CREATE A NEW MODEL WAREHOUSE.

   2. In the create dialog, first select the previously created account.

   3. Provide a name for the Model Warehouse.

   4. Optionally, activate the check box Create Demo Models if you want some demo content to be added to the Model Warehouse.

Model Warehouse creation is the final step in the Smartfacts platform set-up process.

Install the Plug-Ins

It depends on which tools you want to use in connection with Smartfacts. Smartfacts provides a plug-in for every tool which is supported. You can download the plug-ins from the main menu via the command Get Plug-ins.

Troubleshooting

For general Kubernetes Troubleshooting you can consult the https://kubernetes.io/docs/reference/kubectl/cheatsheet/.

Detect running containers

sudo kubectl -n smartfacts get pods

Show log of specific container

sudo kubectl -n smartfacts logs <ContainerId>

Show certtool logs

Show certtool output from Job

sudo kubectl logs job.batch/smartfacts-certtool -c certtool -n smartfacts

Show Secret written by certtool (Attention: The secret does not exist if the certtool did not succeed!)

sudo kubectl get secret smartfacts-truststore -o 'go-template={{index .data "certtool.log"}}' -n smartfact

Show Keycloak password

If it is necessary to login into the admin UI of Keycloak, the password for the admin user “keycloak-admin” can be optained by the following command.

sudo kubectl get secret smartfacts-keycloak-admin-secret -o 'go-template={{index .data "KEYCLOAK_PASSWORD"}}' -n smartfacts | base64 -d; echo ""

Postgres Password – How to Fix the "'global.postgresql.auth.postgresPassword' must not be empty" Error

During Smartfacts installation, some users may face an unexpected issue with Postgres, which is part of the Keycloak service. This issue may occur in different scenarios, such as syntax, certificate or repologin errors in a values.yaml file, network issues etc.

These issues may occur during the Execute the Installation step if some of the previous steps were completed incorrectly. This step consists of two parts:

• Creation of the smartfacts namespace in your K8s or K3s cluster

• Deployment of the Smartfacts resources to this namespace with Helm package manager

If any of the previous steps were completed incorrectly, a smartfacts namespace will be created, however, checks and jobs will terminate the deployment with the error message.

After fixing all the errors, it is possible to rerun the installation, but a new error message will occur:

During normal installation, the password for the Postgres user will be generated and assigned to the Kube secrets automatically. However, if the installation was interrupted, then this password will be missing and you must set it manually in Helm.

The best solution is to delete the incomplete smartfacts namespace, rather than setting the password manually. To do this, run this command:

sudo kubectl delete namespace smartfacts

After execution of this command, the smartfacts namespace will be deleted and you can successfully install the application.