1. Installation

7 minute read

There are three options to setup a development environment:

1. using a seperate device in combination with k3OS and our installation script (preferred). This requires an external device and is a fully automated installation.
2. using minikube (recommended for developers working on the core functionalities of the stack). This method allows you to install the stack on your device and is semi-automated.
3. manual installation (recommended for production environments, if you want to have fine grained control over the installation steps). This can be executed either on an external device or on your device.

The focus of this article is to provide all necessary information to install it in a compressed tutorial. There are footnotes providing additional information on certain steps, that might be new to certain user groups.

Option 1: using a seperate device in combination with k3OS and our installation script

Note: this content is also available in a presence workshop with an experienced facilitator guiding the participants through the installation and answering questions. Contact us for more information!

Prerequisites

This installation methods requires some previous setup

• an edge device with x86 architecture. We recommend using the K300 from OnLogic
• the latest version of k3OS ¹ installed on a bootable USB-stick ².
• a computer with SSH / SFTP client ³ and Lens (for accessing the Kubernetes cluster) installed. We recommend a laptop with an Ethernet port or with an Ethernet adapter.
• local LAN (with DHCP) available via atleast two Ethernet cables and access to the internet.⁴.
• a computer monitor connected with the edge device
• a keyboard connected with the edge device

Installation

This step is also available via a step-by-step video: TODO

k3OS

1. Insert your USB-stick with k3OS into your edge device and boot from it ⁵
2. Install k3OS. When asked for a cloud-init file, enter this URL and confirm: https://www.umh.app/development.yaml. If you are paranoid or want to setup devices for production you could copy the file, modify and host it yourself. Here is the template

This process takes around 15 - 20 minutes depending on your internet connection and there will be no further information about the installation status on the output of the device visible (the information on the computer screen).

Getting access to the device

To verify whether the installation worked and to access Grafana (the dashboard) and Node-RED, we will first enable SSH via password authentification, fetch the login details for Kubernetes and then login via Lens.

Step 1: Login

The login console will look like “messed up” due to the logs of the installation process in the steps above.

Immediatly after start. Nothing is messed up yet.

"Messed up" login screen

You can “clean it up” by pressing two times enter.

You can also immediatly proceed with entering the default username rancher (do not forget to press enter) and the default password rancher to login.

Logging into k3OS using the username `rancher`

Logging into k3OS using the password `rancher`

After a successfull login you should see the current IP address of the device on your computer screen.

Successfully logged into k3OS

Step 2: Enable SSH password authentification

Enable SSH password authentification in k3OS ⁶. This is currently not necessary anymore as the automated setup script will do that automatically, therefore this step can be skipped. This paragraph only exists to remind you that this setting is not the default behavior of k3OS and should be deactivated in production environments.

For production environments we recommend using a certificate to authenticate, which is enabled by default. This can be archieved by modifying the cloud-init file and linking to a public key stored on your GitHub account.

Step 3: Connect via SSH

Connect via SSH ³ from your laptop with the edge device. The IP address is shown on the computer screen on your edge device (see also step 1). If it is not available anymore, you can view the current IP address using ip addr.

Username: rancher Password: rancher

Step 4: Getting Kubernetes credentials

Execute cat /etc/rancher/k3s/k3s.yaml in your SSH session on your laptop to retrieve the Kubernetes credentials. Copy the content of the result into your clipboard.

Execute `cat /etc/rancher/k3s/k3s.yaml`

Copy the content

Connect with the edge device using the software Lens and the Kubernetes credentials from your clipboard.

Add a new cluster in Lens

Select `Paste as text`

Paste from the clipboard

Ensure that you have adjusted the IP in the Kubernetes credentials with the IP of the edge device.

You have now access to the Kubernetes cluster!

Verifying the installation and extracting credentials to connect with the dashboard

The installation is finished when all Pods are “Running”. You can do that by clicking on Pods on the left side.

Click in Lens on Workloads and then on Pods

Select the relevant namespaces `factorycube-server` and `factorycube-edge`

everything should be running

Some credentials are automatically generated by the system. One of them are the login credentials of Grafana. You can retrieve them by clicking on “Secrets” on the left side in Lens. Then search for a secret called “grafana-secret” and open it. Press “decode” and copy the password into your clipboard.

Press on the left side in Lens on Configuration and then Secret.

Then select grafana-secret

Then click on the eye on the right side of adminpassword to decrypt it

Opening Grafana and Node-RED

Grafana is now accessible by opening the following URL in your browser: http://<IP>:8080 (e.g., http://192.168.1.2:8080). You can login by using the username admin and password from your clipboard.

Node-RED is accessible by opening the following URL in your browser: http://<IP>:1880/nodered.

Once you have access, you can proceed with the second article Connecting machines and creating dashboards.

Option 2: using minikube

This option is only recommended for developers. Therefore, the installation is targeted for them and might not be as detailed as option 1.

Prerequisites

• minikube installed according to the official documentation
• repository cloned using git clone https://github.com/united-manufacturing-hub/united-manufacturing-hub.git or downloaded and extracted using the download button on GitHub.
• helm ⁷ and kubectl ⁸ installed

Steps

1. Start minikube using minikube start. If minikube fails to start, see the drivers page for help setting up a compatible container or virtual-machine manager.
   

   Output of the command `minikube start`

2. If everything went well, kubectl is now configured to use the minikube cluster by default. kubectl version should look like in the screenshot.
   

   Expected output of `kubectl version`

3. Go into the cloned repository and into the folder deployment/factorycube-edge
4. execute: kubectl create namespace factorycube-edge && kubectl create namespace factorycube-server
   

   Expected output of `kubectl create namespace`

5. Execute the following command to get an example development configuration: curl https://docs.umh.app/examples/factorycube-server/development_values.yaml --output development_values.yaml
   

   Output of curl

6. Install factorycube-edge by executing the following command: helm install factorycube-edge . --values ./development_values.yaml -n factorycube-edge
   

   Output of `helm install`

7. Go to the factorcube-server folder, e.g. cd ../factorycube-server
8. Install factorycube-server by executing the following command: helm install factorycube-server . -n factorycube-server
   

   Output of `helm install`

Now go grab a coffee and wait 15-20 minutes until all pods are “Running”.

Now you should be able to see the cluster using Lens

Option 3: manual installation

For a manual installation, we recommend that you take a look at the installation script and follow these commands manually and adjust them when needed.