This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

This section contains guides on how to install the United Manufacturing Hub.

Learn how to install the United Manufacturing Hub using completely Free and Open Source Software.

1 - Flatcar Installation (Bare Metal)

This page describes how to deploy the United Manufacturing Hub on Flatcar Linux on bare metal.

Here is a step-by-step guide on how to deploy the UMH stack on Flatcar Linux, a Linux distribution designed for container workloads, with high security and low maintenance.

This is a good option if you want to deploy the UMH stack on edge devices or IPCs.

Before you begin

Your system must meet the following requirements before you can install the United Manufacturing Hub:

  • CPU cores: 4
  • Memory size: 8 GB
  • Hard disk size: 32 GB

You need the latest version of our iPXE boot image:

The image needs to be written to a USB stick. If you want to know how to do this, follow our guide on how to flash an operating system onto a USB-stick.

You also need a computer with an SSH client (most modern operating systems already have it) and either UMHLens or OpenLens installed.

Additionally, this guide assumes a configuration similar to the following:

%%{ init: { 'flowchart': { 'curve': 'bumpY' } } }%% flowchart LR A(Internet) -. WAN .- B[Router] subgraph Internal network B -- LAN --- C[Edge device] B -- LAN --- D[Your computer] end
For optimal functionality, we recommend assigning a static IP address to your edge device. This can be accomplished through a static lease in the DHCP server or by setting the IP address during installation. Changing the IP address of the edge device after installation may result in certificate issues, so we strongly advise against doing so. By assigning a static IP address, you can ensure a more stable and reliable connection for your edge device.

Install Flatcar Linux on the edge device

  1. Connect the USB stick to the edge device and boot it. Each device has a different way of booting from USB, so you need to consult the documentation of your device.
  2. Accept the License.
  3. Select the correct network settings. If you are unsure, select DHCP, but keep in mind that a static IP address is strongly recommended.
  4. Select the correct drive to install Flatcar Linux on. If you are unsure, check the troubleshooting section.
  5. Check that the installation settings are correct and press Confirm to start the installation.

Now the installation will start. You should see a green command line soon after, that says [email protected] ~$~. Now remove the USB stick from the device. At this point the system is still installing. After a few minutes, depending on the speed of your network, the installation will finish and the system will reboot. Now you should see a grey login prompt that says flatcar-1-umh login:, as well as the IP address of the device.

Please note that the installation may take some time. This largely depends on the available resources including network speed and system performance.

Connect to the edge device

Now you can leave the edge device and connect to it from your computer via SSH.

If you are on Windows 11, we recommend using the default Windows terminal, that you can find by typing terminal in the Windows search bar or Start menu. Next, connect to the edge device via SSH, using the IP address you saw on the login prompt:

ssh [email protected]<ip-address>

If you are not on Windows 11, you can use MobaXTerm to connect to the edge device via SSH. Open MobaXTerm and click on Session in the top left corner. Then click on SSH and enter the IP address of the edge device in the Remote host field. Click on Advanced SSH settings and enter core in the Username field. Click on Save and then on Open.

The default password for the core user is umh.

Import the cluster configuration

  1. From your SSH session, run the following command to get the cluster configuration:

    sudo kubectl config view --raw

    The output should look similar to this:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://127.0.0.1:6443
  name: default
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
  user:
    client-certificate-data: <long string>
    client-key-data: <long string>

  2. Copy the output.

  3. Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.

  4. Paste the output.

  5. Update the server field to the IP address of the device, e.g.:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://192.168.0.123:6443 # <- update this
...

  6. If you want, you can also update the name field to something more meaningful, e.g.:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://192.168.0.123:6443
    name: my-edge-device # <- update this
...

  7. Click on Add clusters.

Access the UMH stack

  1. Open UMHLens / OpenLens on your device.

  2. From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.

  3. Click on a cluster to connect to it.

  4. Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.

    lens-namespaces
    lens-namespaces

  5. Select the united-manufacturing-hub Release to inspect the release details, the installed resources, and the Helm values.

Troubleshooting

The installation stops at the green login prompt

To check the status of the installation, run the following command:

systemctl status installer

If the installation is still running, you should see something like this:

● installer.service - Flatcar Linux Installer
     Loaded: loaded (/usr/lib/systemd/system/installer.service; static; vendor preset: enabled)
     Active: active (running) since Wed 2021-05-12 14:00:00 UTC; 1min 30s ago

Otherwise, the installation failed. You can check the logs to see what went wrong.

I don’t know which drive to select

You can check the drive type from the manual of your device.

  • For SATA drives (spinning hard disk or SSD), the drive type is SDA.
  • For NVMe drives, the drive type is NVMe.

If you are unsure, you can boot into the edge device with any Linux distribution and run the following command:

lsblk

The output should look similar to this:

NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda      8:0    0 223.6G  0 disk
├─sda1   8:1    0   512M  0 part /boot
└─sda2   8:2    0 223.1G  0 part /
sdb      8:0    0  31.8G  0 disk
└─sdb1   8:1    0  31.8G  0 part /mnt/usb

In this case, the drive type is SDA. Generally, the drive type is the name of the first drive in the list, or at least the drive that doesn’t match the size of the USB stick.

I can access the cluster but there are no resources

First completely shut down UMHLens / OpenLens (from the system tray). Then start it again and try to access the cluster.

If that doesn’t work, access the edge device via SSH and run the following command:

systemctl status k3s

If the output contains a status different from active (running), the cluster is not running. Otherwise, the UMH installation failed. You can check the logs with the following commands:

systemctl status umh-install
systemctl status helm-install

If any of the commands returns some errors, is probably easier to reinstall the system.

What’s next

  • You can follow the Getting Started guide to get familiar with the UMH stack.
  • If you already know your way around the United Manufacturing Hub, you can follow the Administration guides to configure the stack for production.

2 - Flatcar Installation (Virtual Machine)

This page describes how to deploy the United Manufacturing Hub on Flatcar Linux in a virtual machine.

Here is a step-by-step guide on how to deploy the UMH stack on Flatcar Linux, a Linux distribution designed for container workloads, with high security and low maintenance, in a virtual machine.

This is a good option if you want to deploy the UMH stack on a virtual machine to try out the installation process or to test the UMH stack.

Before you begin

You need the latest version of our iPXE boot image.

The image needs to be written to a USB stick. If you want to know how to do this, follow our guide on how to flash an operating system onto a USB-stick.

You also need to have a virtual machine software installed on your computer. We recommend VirtualBox, which is free and open source, but other solutions are also possible.

Additionally, you need to have either UMHLens or OpenLens installed.

Create a virtual machine

Create a new virtual machine in your virtual machine software. Make sure to use the following settings:

  • Operating System: Linux
  • Version: Other Linux (64-bit)
  • CPU cores: 4
  • Memory size: 8 GB
  • Hard disk size: 32 GB

Also, the network settings of the virtual machine must allow communication with the internet and the host machine. If you are using VirtualBox, you can check the network settings by clicking on the virtual machine in the VirtualBox manager and then on Settings. In the Network tab, make sure that the Adapter 1 is set to Bridged Adapter.

Install Flatcar Linux

  1. Start the virtual machine.
  2. Accept the License.
  3. Set a static IP address.
  4. Select sda as the disk.
  5. Select Confirm.

Now the installation will start. You should see a green command line soon after, that says [email protected] ~$~. At this point the system is still installing. After a few minutes, depending on the speed of your network, the installation will finish and the system will reboot.

By default, it will reboot into the installation environment. Just shut down the virtual machine and remove the ISO image from the CD drive, then boot the virtual machine again. This way, the installation process will continue, at the end of which you will a grey login prompt that says flatcar-1-umh login:, as well as the IP address of the device.

Please note that the installation may take some time. This largely depends on the available resources including network speed and system performance.

Connect to the virtual machine

You can leave the virtual machine running and connect to it using SSH, so that is easier to work with it.

Open a terminal on your computer and connect to the edge device via SSH, using the IP address you saw on the login prompt:

ssh [email protected]<ip-address>

If you are on Windows, you can use MobaXTerm to connect to the edge device via SSH. Open MobaXTerm and click on Session in the top left corner. Then click on SSH and enter the IP address of the edge device in the Remote host field. Click on Advanced SSH settings and enter core in the Username field. Click on Save and then on Open.

The default password for the core user is umh.

Import the cluster configuration

  1. From your SSH session, run the following command to get the cluster configuration:

    sudo kubectl config view --raw

    The output should look similar to this:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://127.0.0.1:6443
  name: default
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
  user:
    client-certificate-data: <long string>
    client-key-data: <long string>

  2. Copy the output.

  3. Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.

  4. Paste the output.

  5. Update the server field to the IP address of the device, e.g.:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://192.168.0.123:6443 # <- update this
...

  6. If you want, you can also update the name field to something more meaningful, e.g.:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <long string>
    server: https://192.168.0.123:6443
    name: my-edge-device # <- update this
...

  7. Click on Add clusters.

Access the UMH stack

  1. Open UMHLens / OpenLens on your device.

  2. From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.

  3. Click on a cluster to connect to it.

  4. Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.

    lens-namespaces
    lens-namespaces

  5. Select the united-manufacturing-hub Release to inspect the release details, the installed resources, and the Helm values.

Troubleshooting

The installation stops at the green login prompt

To check the status of the installation, run the following command:

systemctl status installer

If the installation is still running, you should see something like this:

● installer.service - Flatcar Linux Installer
     Loaded: loaded (/usr/lib/systemd/system/installer.service; static; vendor preset: enabled)
     Active: active (running) since Wed 2021-05-12 14:00:00 UTC; 1min 30s ago

Otherwise, the installation failed. You can check the logs to see what went wrong.

I can access the cluster but there are no resources

First completely shut down UMHLens / OpenLens (from the system tray). Then start it again and try to access the cluster.

If that doesn’t work, access the virtual machine via SSH and run the following command:

systemctl status k3s

If the output contains a status different from active (running), the cluster is not running. Otherwise, the UMH installation failed. You can check the logs with the following commands:

systemctl status umh-install
systemctl status helm-install

If any of the commands returns some errors, is probably easier to reinstall the system.

I can’t SSH into the virtual machine

If you can’t SSH into the virtual machine, make sure that the network settings for the virtual machine are correct. If you are using VirtualBox, you can check the network settings by clicking on the virtual machine in the VirtualBox manager and then on Settings. In the Network tab, make sure that the Adapter 1 is set to NAT.

Disable any VPNs that you might be using.

What’s next

  • You can follow the Getting Started guide to get familiar with the UMH stack.
  • If you already know your way around the United Manufacturing Hub, you can follow the Administration guides to configure the stack for production.

3 - Local k3d Installation

This page describes how to deploy the United Manufacturing Hub locally using k3d.

This can now be done using the Community Edition of the Management Console. Go check it out!

Here is a step-by-step guide on how to deploy the UMH stack using k3d, a lightweight wrapper to run k3s in Docker. k3d makes it very easy to create single- and multi-node k3s clusters in Docker, e.g. for local development on Kubernetes.

Before you begin

Your system must meet the following requirements before you can install the United Manufacturing Hub:

  • CPU cores: 4
  • Memory size: 8 GB
  • Hard disk size: 32 GB

You also need to have Docker up and running and either UMHLens or OpenLens installed.

Install dependencies

  1. Install kubectl. Refer to the kubectl installation if you need help.

    choco install kubernetes-cli


    brew install kubectl


    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

  2. Install Helm. Refer to the Helm installation if you need help.

    choco install kubernetes-helm


    brew 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

  3. Install k3d. Refer to the k3d installation if you need help.

    choco install k3d


    brew install k3d


    curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

Create a cluster

  1. Create a cluster.

    k3d cluster create united-manufacturing-hub --api-port 127.0.0.1:6443 --port 8080:[email protected]:0 --port 8090:[email protected]:0 --port 1880:[email protected]:0 --port 5432:[email protected]:0 --port 1883:[email protected]:0 --port 8883:[email protected]:0 --port 9092:[email protected]:0 --port 46010:[email protected]:0

    The --api-port flag is used to expose the Kubernetes API server on the host machine. If the 6443 port is already in use, you can use any other port. The --port flag is used to expose the ports of the services running in the cluster on the host machine. If any of the ports on the left side of the : is already in use, you can use any other port.

  2. Verify that the cluster is up and running.

    kubectl get nodes

    The output should look like this:

    NAME                                            STATUS   ROLES                  AGE   VERSION
k3d-united-manufacturing-hub-server-0           Ready    control-plane,master   10s   v1.24.4+k3s1

Install the UMH stack

  1. Add the UMH Helm repository.

    helm repo add united-manufacturing-hub https://repo.umh.app/

  2. Update the Helm repository.

    helm repo update

  3. Create the namespace.

    kubectl create namespace united-manufacturing-hub

  4. Install the UMH stack.

    helm install united-manufacturing-hub united-manufacturing-hub/united-manufacturing-hub -n united-manufacturing-hub

  1. Open UMHLens / OpenLens on your device.

  2. From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.

  3. Click on a cluster to connect to it.

  4. Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.

    lens-namespaces
    lens-namespaces

  5. Select the united-manufacturing-hub Release to inspect the release details, the installed resources, and the Helm values.

Troubleshooting

I don’t see the cluster in UMHLens / OpenLens

If you don’t see the cluster in UMHLens / OpenLens, you might have to add the cluster manually. To do so, follow these steps:

  1. Open a terminal and run the following command to get the kubeconfig file:

    k3d kubeconfig get united-manufacturing-hub

  2. Copy the output of the command.

  3. Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.

  4. Paste the kubeconfig and click Add clusters.

What’s next

  • You can follow the Getting Started guide to get familiar with the UMH stack.
  • If you already know your way around the United Manufacturing Hub, you can follow the Administration guides to configure the stack for production.