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.

Please make sure that an ingress controller of nginx or Traefik is installed.

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

If your server only reaches the Internet via a proxy, you must set up your environment so that this proxy is used with k3s and helm. If this is the case, follow the instructions in this section:

Set up Proxy for k3s and helm

Edit the file ~/.bashrc for your deployment user and add the following lines:
```
export http_proxy="proxy:port"
export https_proxy="proxy:port"
export no_proxy=localhost,.svc,.cluster.local,127.0.0.0/8,<local IP>
```
Replace the placehoder “<local IP>“ with the IP address of your server.

If you need to pass username and password to the proxy, change the first two lines to
```
export http_proxy="username:password@proxy:port"
export https_proxy="username:password@proxy:port"
```
In the k3s installation script, some commands are executed as the root user with sudo. We must therefore ensure that the command called with sudo also sees the proxy variables.
To ensure this, call the command
```
sudo visudo
```
and add the following lines to the end of the file:
```
Defaults  env_keep += "http_proxy"
Defaults  env_keep += "https_proxy"
Defaults  env_keep += "no_proxy"
Defaults  env_keep += "HTTP_PROXY"
Defaults  env_keep += "HTTPS_PROXY"
Defaults  env_keep += "NO_PROXY"
```

3. Log out and log in again with your user so that the changes in the .bashrc file from step 1 are applied.

Execute the installation of k3s with the command

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.27.9+k3s1 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

Make sure that the complete certificate chain is contained in a file in correct order in x509 PEM format. The content of certificates in PEM formate looks like this:

-----BEGIN CERTIFICATE-----
<Many lines of certificate data encoded in base64>
-----END CERTIFICATE-----

In a certificate chain, multiple blocks of certificates are present, representing the server, intermedate and root certificates.

The correct order of the blocks is from top to bottom:

server certificate at the top
intermediate cerificate(s), if any
root certificate at the bottom

Also 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 other tools). In this case you can 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.
If your cluster has access to the internet, then you can pull the images directly from the registry provided by MID. In this case replace the value of the repologin property with the value provided from MID. Otherwise see below.
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 instances, separate the URLs with a space.
Save the values.yaml file.

Option: Use a private container registry

If your Kubernetes cluster has no access to the internet, you can pull the images from the MID registry, re-tag them and push them to your private registry.

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.7.1-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.

Add Web Origin to Keycloak

For Smartfacts to function, it is necessary to corret a value in the Keycloak configuration.

Get the Keycloak administrator password:

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

Get the URL of keycloak:

sudo kubectl get ingress -n smartfacts | grep identity | tr -s ' ' | cut -d ' ' -f3

Call this URL in a browser. Klick on “Administration Console” and log in with Username “keycloak-admin” and the password returned in the step above.

Select “Clients” and the client ID “smartfacts”.

Scroll down until you see the property “Web Origins”. Insert a plus sign “+” into the value field.

Scroll to the bottom of the page and klick on the “save” button

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”.

Create a Smartfacts Model Warehouse

Open the Smartfacts URL in your browser: https://smartfacts.<yoursmartfactsdomain> and log-in with the account manager credentials (user “acm”, password “acm”).
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 the logs of a pod

With the following command you can get the log files of the Smartfacts platform (pod “sfit-platform”). If you deployed with a namespace named other than “smartfacts”, adjust the value of the second variable “ns”.

If you have to call “kubectl” with “sudo”:

pod=genoslc ns=smartfacts sudo bash -c 'kubectl logs $(kubectl get pods -n $ns | grep $pod | cut -d " " -f1) -n $ns'

If “sudo” is not required:

pod=genoslc ns=smartfacts bash -c 'kubectl logs $(kubectl get pods -n $ns | grep $pod | cut -d " " -f1) -n $ns'

If you need to get the logs of another pod, change the value of the variable “pod” at the beginning of the line. Available pod names for the Smartfacts installation are the following:

value for pod variable	POD
sfit-platform	The Smartfacts platform
sfit-spa	The Smartfacts SPA
mongodb	The mongodb database
genoslc	The OSLC Connector for Smartfacts
keycloak	The keycloak pod (identity provider for PoC installations with dummy users)

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 ""

Reset lost password for keycloak-admin user

In rare cases, it might happen that the password of the keycloak-admin user is different from the password in the secret “smartfacts-keycloak-admin-secret” and is not known anymore. This section describes the steps necessary to reset this password.

To reset the password for the keycloak-admin user:

Get the password from the secret like described in the section “Show Keycloak password” above. Save the password in a password manager.
Edit the secret “smartfacts-keycloak-admin-secret”, this command will open the secret in a vi editor:
```
sudo kubectl edit secret smartfacts-keycloak-admin-secret -n smartfacts
```
1. replace the value of the field “KEYCLOAK_USER” with the base64 value for “tmp-admin”: dG1wLWFkbWlu
2. Save and quit

Restart the keycloak pod:

pod=keycloak ns=smartfacts bash -c 'kubectl delete pod $(kubectl get pods -n $ns | grep $pod | cut -d " " -f1) -n $ns'

Sign in into the keycloak UI with the user “tmp-admin” and the password saved from the secret
In the Keycloak UI, switch to the realm “Master” and then to the section “users”
1. Klick on “View all users”
2. Klick on the ID of the user “keycloak-admin”
3. Go to section “Credentials” and insert the correct password in the fields in section “Reset Password”
  1. Switch “Temprory” to “OFF”
  2. Klick on “Reset Password” and confirm the Reset Password dialog
4. Log off of Keycloak
Edit the secret “smartfacts-keycloak-admin-secret” again
```
sudo kubectl edit secret smartfacts-keycloak-admin-secret -n smartfacts
```
1. replace the value of the field “KEYCLOAK_USER” with the base64 value for “keycloak-admin”: a2V5Y2xvYWstYWRtaW4=
2. Save and quit

Restart the keycloak pod

pod=keycloak ns=smartfacts bash -c 'kubectl delete pod $(kubectl get pods -n $ns | grep $pod | cut -d " " -f1) -n $ns'

Sign in into keycloak with keycloak-admin and the password saved from the secret
1. In the Keycloak UI switch to the realm “Master” and then to section “users”
  1. Klick on “View all users”
  2. Delete the user “tmp-admin”
log out of Keycloak

How to Move k3s data to another partition or diskThe default locations for k3s data are the following directories on the host machine:

/run/k3s
/var/lib/kubelet/pods
/var/lib/rancher

If the hard disk on which the standard directories are located is too small and you do not have the option of enlarging the hard disk, then move the k3s data to another hard disk. These instructions show the necessary steps. It is recommended that you create a snapshot of the virtual machine before making the changes.

stop all k3s services

sudo systemctl stop k3s
sudo /usr/local/bin/k3s-killall.sh

create variable with mount path to your new disk

newLocation=<path to your large disk> # alter this to the correct mount point of the disk to use

Copy files to the new location (change location in line 1)

sudo mv /run/k3s/ $newLocation/k3s/
sudo mv /var/lib/kubelet/pods/ $newLocation/k3s-pods/
sudo mv /var/lib/rancher/ $newLocation/k3s-rancher/

Create symbolic links

sudo ln -s $newLocation/k3s/ /run/k3s
sudo ln -s $newLocation/k3s-pods/ /var/lib/kubelet/pods
sudo ln -s $newLocation/k3s-rancher/ /var/lib/rancher

Start k3s service again
```
sudo systemctl start k3s
```

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.

PoC Deployment on Kubernetes with use of Keycloak as OIDC provider