Learn how to install the United Manufacturing Hub using completely Free and Open Source Software.
This is the multi-page printable view of this section. Click here to print.
Installation
- 1: Flatcar Installation (Bare Metal)
- 2: Flatcar Installation (Virtual Machine)
- 3: Local k3d Installation
1 - Flatcar Installation (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:
- ipxe-x86_64-efi: for reasonably modern systems.
- ipxe-x86_64-bios: for older systems.
- ipxe-arm64-efi: for ARM systems. Currently, Raspberry Pi 4 is not supported.
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:
Install Flatcar Linux on the edge device
- 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.
- Accept the License.
- Select the correct network settings. If you are unsure, select DHCP, but keep in mind that a static IP address is strongly recommended.
- Select the correct drive to install Flatcar Linux on. If you are unsure, check the troubleshooting section.
- 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
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>
Copy the output.
Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.
Paste the output.
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 ...
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 ...
Click on Add clusters.
Access the UMH stack
Open UMHLens / OpenLens on your device.
From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.
Click on a cluster to connect to it.
Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.
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)
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
- Start the virtual machine.
- Accept the License.
- Set a static IP address.
- Select
sda
as the disk. - 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
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>
Copy the output.
Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.
Paste the output.
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 ...
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 ...
Click on Add clusters.
Access the UMH stack
Open UMHLens / OpenLens on your device.
From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.
Click on a cluster to connect to it.
Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.
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 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
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
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
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
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 the6443
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.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
Add the UMH Helm repository.
helm repo add united-manufacturing-hub https://repo.umh.app/
Update the Helm repository.
helm repo update
Create the namespace.
kubectl create namespace united-manufacturing-hub
Install the UMH stack.
helm install united-manufacturing-hub united-manufacturing-hub/united-manufacturing-hub -n united-manufacturing-hub
Open UMHLens / OpenLens on your device.
From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.
Click on a cluster to connect to it.
Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.
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:
Open a terminal and run the following command to get the kubeconfig file:
k3d kubeconfig get united-manufacturing-hub
Copy the output of the command.
Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.
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.