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
This section contains guides on how to install the United Manufacturing Hub.
1 - Advanced Installation
Additional requirements and considerations when installing the United Manufacturing Hub on a virtual machine.
This page describes advanced requirements and considerations when installing the United Manufacturing Hub. It is meant to be an additional guide for the Installation guide page.
You may also find these step-by-step installation guides helpful:
Storage Configuration
When setting up your virtual machine for UMH:
Partition Layout
- The default Rocky Linux installation typically creates a large
/homepartition - During OS installation, you may use custom partitioning to ensure the root partition (
/) has sufficient space ()
Install location
- The kubernetes data directory is stored in
/var/lib/rancher/k3sby default. - This can be overridden by setting the
K3S_DATA_DIRenvironment variable. See Kubernetes Configuration Variables for more information.
Virtual Machine Configuration
There are some specific settings that are recommended for the virtual machine:
Networking
- Use a bridged network adapter
- NAT or host-only adapters will prevent external connections to your instance
- The VM must be able to:
- Access the internet for installation and updates
- Communicate with other devices on your network
- Accept incoming connections from clients
Advanced Requirements
CPU Configuration
- Enable CPU virtualization extensions (VT-x/AMD-V) on the host
- Allocate physical CPU cores rather than virtual cores when possible
- For production environments, reserve the CPU resources
Memory Settings
- Use static memory allocation rather than dynamic/balloon drivers
- Reserve the memory in the hypervisor to prevent memory swapping
Other Settings
- Disable unnecessary virtual hardware (like sound cards, USB controllers)
- Use paravirtualized drivers when available for better performance
General Script Control Variables
For advanced users, the following variables can be used to control the behavior of the script:
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
AUTO_SELECT_EXTERNAL_IP | auto_select_external_ip | false | If true, automatically pick the first non-loopback network interface and set EXTERNAL_IP/EXTERNAL_IP_INTERFACE/EXTERNAL_IP_GATEWAY based on it. |
GENERAL_IGNORE_ERRORS | ignore_errors | false | If true, the script will ignore errors and continue, mainly used for troubleshooting. |
GENERAL_TIMEOUT | TIMEOUT | 120 | Time in seconds to wait for a process before timing out (default: 2 minutes). |
GENERAL_INTERVAL | INTERVAL | 5 | Interval in seconds to check a process status (default: every 5 seconds). |
GENERAL_RETRIES | RETRIES | 10 | Number of retries for certain checks (default: 10). |
UNINSTALL | UNINSTALL | false | If true, the script will uninstall the UMH, Companion, and Kubernetes instead of installing them. |
EXTERNAL_IP | EXTERNAL_IP | (unset) | Manually set the external IP of the machine. |
EXTERNAL_IP_INTERFACE | EXTERNAL_IP_INTERFACE | (unset) | Manually set the network interface associated with EXTERNAL_IP. |
EXTERNAL_IP_GATEWAY | EXTERNAL_IP_GATEWAY | (unset) | Manually set the default gateway associated with EXTERNAL_IP_INTERFACE. |
DNS_SERVER | DNS_SERVER | (unset) | Manually set the DNS server to be used by mgmtcompanion. |
Tooling Installation Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
TOOL_K3S_VERSION | INSTALL_K3S_VERSION | v1.29.5+k3s1 | Specifies the version of k3s to be installed. |
TOOL_K3S_SELINUX_VERSION | INSTALL_K3S_SELINUX_VERSION | k3s-selinux-1.5-1.el9.noarch.rpm | Specifies the version (or RPM) of k3s SELinux policy to install on RHEL systems. |
TOOL_KUBECTL_VERSION | INSTALL_KUBECTL_VERSION | v1.29.5 | Specifies the version of kubectl to be installed. |
TOOL_HELM_VERSION | INSTALL_HELM_VERSION | v3.13.2 | Specifies the version of helm to be installed. |
TOOL_K3S_CUSTOM_TLS_SAN | CUSTOM_TLS_SAN | (unset) | Custom TLS Subject Alternative Names for k3s. For example, IP addresses or a domain name for TLS certificates. |
TOOL_K3S_KUBECONFIG | KUBECONFIG | /etc/rancher/k3s/k3s.yaml | Path to the kubeconfig file to be used by kubectl, helm, etc. |
Kubernetes Configuration Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
KUBE_NODE_NAME | NODE_NAME | Uses the system’s hostname | Node name in the Kubernetes cluster. |
AUTO_PATCH_HOSTNAME | auto_patch_hostname | false | If true, automatically sets the system hostname to NODE_NAME without user confirmation. |
| (Set internally) | INSTALL_K3S_EXEC | (constructed dynamically) | Internal variable to pass additional flags (like --tls-san) during k3s installation. This is auto-generated; not usually set directly. |
K3S_DATA_DIR | K3S_DATA_DIR | k3s default (/var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root) | Specifies the data directory for k3s by setting the --data-dir flag. |
Speedtest Configuration Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
SPEEDTEST_MIN_DOWNLOAD | MIN_DOWNLOAD | 50000000 | Minimum download speed in bits per second (default: 50 Mbps). |
SPEEDTEST_MIN_UPLOAD | MIN_UPLOAD | 10000000 | Minimum upload speed in bits per second (default: 10 Mbps). |
SPEEDTEST_MIN_PING | MIN_PING | 50 | Maximum ping in milliseconds (default: 50). |
| (Script-internal) | MEASURED_UPLOAD | 0 | Automatically set by script after running speed test; not typically set by the user. |
| (Script-internal) | MEASURED_DOWNLOAD | 0 | Automatically set by script after running speed test; not typically set by the user. |
| (Script-internal) | MEASURED_PING | 0 | Automatically set by script after running speed test; not typically set by the user. |
UMH Installation Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
UMH_SKIP_INSTALL | skip_umh_install | false | If true, skips the installation of the United Manufacturing Hub (UMH). |
UMH_FORCE_OVERWRITE | force_umh_overwrite | false | If true, forces overwriting an existing UMH installation without prompting the user. |
UMH_VERSION | UMH_VERSION | 0.27.0 | Specifies which version of the UMH chart to install. |
UMH_HELM_CHART_URL | UMH_HELM_CHART_URL | https://management.umh.app/helm/umh | The URL of the UMH Helm chart repository. |
ALLOW_HELM_PRERELEASE | ALLOW_HELM_PRERELEASE | false | If true, allows Helm to install pre-release versions of UMH. |
IS_LITE_INSTALL | IS_LITE_INSTALL | false | If true, installs a “lite” version of UMH; forcibly sets skip_umh_install to true. |
IS_FULL_INSTALL | IS_FULL_INSTALL | true | True if installing the “full” version of UMH. Note that it becomes false if IS_LITE_INSTALL is true. |
Management Companion Installation Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
MGMT_AUTH_TOKEN | AUTH_TOKEN | (unset) | Required. A 64-character hex string (256-bit) used by the Management Companion for authentication. |
MGMT_INSECURE_TLS_SKIP_CERTIFICATE_CHECK | insecure_tls_skip_certificate_check | false | If true, skip TLS certificate checks. Useful in development or if you have a proxy intercepting traffic. |
MGMT_CUSTOM_URL | CUSTOM_MGMT_URL | https://management.umh.app | A custom management URL for specialized setups. |
MGMT_CUSTOM_IMAGE_VERSION | IMAGE_VERSION | latest | Custom version tag for the Management Companion Docker image (e.g., staging). |
MGMT_SKIP_INSTALL | skip_companion_install | false | If true, skips the installation of the Management Companion. |
MGMT_SKIP_RHEL_SHA1_SIGNATURES | SKIP_RHEL_SHA1_SIGNATURES | false | On RHEL-based systems, if true, does not temporarily enable SHA1 signatures (needed for some older packages). |
MGMT_CONFIG_DEBUG_DISABLE_BACKEND_CONNECTION | MGMT_CONFIG_DEBUG_DISABLE_BACKEND_CONNECTION | false | Disables the backend connection for debugging. |
MGMT_API_URL | API_URL | $CUSTOM_MGMT_URL/api | API endpoint used by the Management Companion to communicate with the UMH backend. |
MGMT_STATIC_URL | STATIC_URL | $CUSTOM_MGMT_URL/static | URL for static resources (Kubernetes YAML files, etc.). |
MGMT_CONFIGMAP_URL | CONFIGMAP_URL | $STATIC_URL/kubernetes/configmap.yaml | Location of the companion’s ConfigMap YAML. |
MGMT_SECRET_URL | SECRET_URL | $STATIC_URL/kubernetes/secret.yaml | Location of the companion’s Secret YAML. |
MGMT_STATEFULSET_URL | STATEFULSET_URL | $STATIC_URL/kubernetes/statefulset.yaml | Location of the companion’s StatefulSet YAML. |
MGMT_ROLE_URL | ROLE_URL | $STATIC_URL/kubernetes/role.yaml | Location of the companion’s Role YAML. |
MGMT_ROLE_BINDING_URL | ROLE_BINDING_URL | $STATIC_URL/kubernetes/rolebinding.yaml | Location of the companion’s RoleBinding YAML. |
MGMT_PVC_URL | PVC_URL | $STATIC_URL/kubernetes/pvc.yaml | Location of the companion’s PVC YAML. |
MGMT_KUBELET_URL | KUBELET_URL | $STATIC_URL/kubernetes/kubelet-config.yaml | Location of the Kubelet configuration YAML. |
MGMT_REGISTRIES_URL | REGISTRIES_URL | $STATIC_URL/kubernetes/registries.yaml | Custom Docker registry configuration for k3s. |
Location Variables
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
LOCATION_ENTERPRISE | LOCATION_ENTERPRISE | (unset) | Enterprise name/location for site identification. |
LOCATION_SITE | LOCATION_SITE | (unset) | Site name/location for site identification. |
LOCATION_AREA | LOCATION_AREA | (unset) | Area name/location for site identification. |
LOCATION_LINE | LOCATION_LINE | (unset) | Production line name/location for site identification. |
LOCATION_WORKCELL | LOCATION_WORKCELL | (unset) | Workcell name/location for site identification. |
Additional Installation Options
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
SILENT | SILENT | false | If true, the script proceeds without interactive confirmations (all prompts default to “yes”). |
SKIP_HARDWARE_TEST | SKIP_HARDWARE_TEST | false | If true, skip hardware checks (CPU cores, memory, disk space, SSE4.2). Useful for dev or limited resource machines. |
DISABLE_HARDWARE_STATUS_CHECK | DISABLE_HARDWARE_STATUS_CHECK | false | If true, skip or ignore hardware checks in the status messages. |
Release Channel
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
RELEASE_CHANNEL | RELEASE_CHANNEL | stable | Channel to use for UMH updates/notifications. Options: enterprise, stable, nightly |
Helm Flags
| Environment Variable | Script Variable | Default Value | Description |
|---|---|---|---|
| (Set internally) | CHART_VERSION | UMH_VERSION | Used by the script to pass --version to Helm when installing the UMH chart. |
SAME_TOPIC_EXPERIENCE | SAME_TOPIC_EXPERIENCE | false | If true, uses the same Kafka topic across certain analytics solutions (internal optional feature). |
Environment Variables for Testing and Troubleshooting
These variables let you run only portions of the script for debugging:
| Environment Variable | Default | Description |
|---|---|---|
INSTALL_HELM | false | If true, only executes the Helm installation portion of the script. |
UNINSTALL_HELM | false | If true, only executes the Helm uninstallation portion of the script. |
INSTALL_KUBECTL | false | If true, only executes the kubectl installation portion of the script. |
UNINSTALL_KUBECTL | false | If true, only executes the kubectl uninstallation portion of the script. |
INSTALL_KUBERNETES | false | If true, only installs k3s (and does pre-checks). |
UNINSTALL_KUBERNETES | false | If true, only uninstalls k3s (and does relevant cleanup). |
Other Internal Variables
Below variables are set or used internally and typically do not need to be overridden:
TMP_FILE_BASE_DIR(Defaults to/tmp, used to specify base directory for temporary files)SENTRY_DSN(Used for error reporting to Sentry)INSTALL_HELM/UNINSTALL_HELM(See testing & troubleshooting table)INSTALL_KUBECTL/UNINSTALL_KUBECTL(See testing & troubleshooting table)INSTALL_KUBERNETES/UNINSTALL_KUBERNETES(See testing & troubleshooting table)
How to Override Variables
To override any variable, simply export it before running the script, or prepend it on the command line. For example:
export UMH_VERSION="0.28.1"
export MGMT_AUTH_TOKEN="0123456789abcdef..."
export SILENT="true"
./install.sh
Or in a single line:
export UMH_VERSION="0.28.1" && export MGMT_AUTH_TOKEN="0123456789abcdef..." && export SILENT="true" && ./install.sh
2 - Flatcar Installation
This page describes how to deploy the United Manufacturing Hub on Flatcar
Linux.
Here is a step-by-step guide on how to deploy the United Manufacturing Hub on Flatcar Linux, a Linux distribution designed for container workloads with high security and low maintenance. This will leverage the UMH Device and Container Infrastructure.
The system can be installed either bare metal or in a virtual machine.
Before you begin
Ensure your system meets these minimum requirements:
- 4-core CPU
- 8 GB system RAM
- 32 GB available disk space
- Internet access
You will also need the latest version of the iPXE boot image, suitable for your system:
- ipxe-x86_64-efi: For modern systems, recommended for virtual machines.
- ipxe-x86_64-bios: For legacy systems.
- ipxe-arm64-efi: For ARM architectures (Note: Raspberry Pi 4 is currently not supported).
For bare metal installations, flash the image to a USB stick with at least 4 GB of storage. Our guide on flashing an operating system to a USB stick can assist you.
For virtual machines, ensure UEFI boot is enabled when creating the VM.
Lastly, ensure you are on the same network as the device for SSH access post-installation.
System Preparation and Booting from iPXE
Identify the drive for Flatcar Linux installation. For virtual machines, this is typically sda. For bare metal, the drive depends on your physical storage. The troubleshooting section can help identify the correct drive.
Boot your device from the iPXE image. Consult your device or hypervisor documentation for booting instructions.
You can find a comprehensive guide on how to configure a virtual machine in Proxmox for installing Flatcar Linux on the Learning Hub.
Installation
At the first prompt, read and accept the license to proceed.
Next, configure your network settings. Select DHCP if uncertain.
The connection will be tested next. If it fails, revisit the network settings.
Ensure your device has internet access and no firewalls are blocking the connection.
Then, select the drive for Flatcar Linux installation.
A summary of the installation will appear. Check that everything is correct and confirm to start the process.
Shortly after, you’ll see a green command line core@flatcar-0-install. Remove
the USB stick or the CD drive from the VM. The system will continue processing.
The installation will complete after a few minutes, and the system will reboot.
When you see the green core@flatcar-1-umh login prompt, the installation is complete, and the device’s IP address will be displayed.
Installation time varies based on network speed and system performance.
Connect to the Device
With the system installed, access it via SSH.
For Windows 11 users, the default Windows Terminal is recommended. For other OS users, try MobaXTerm.
To do so, open you terminal of choice. We recommend the default Windows Terminal, or MobaXTerm if you are not on Windows 11.
Connect to the device using this command, substituting <ip-address> with your
device’s IP address:
ssh core@<ip-address>
When prompted, enter the default password for the core user: umh.
Troubleshooting
The Installation Stops at the First Green Login Prompt
If the installation halts at the first green login prompt, check the installation status with:
systemctl status installer
A typical response for an ongoing installation will look 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
If the status differs, the installation may have failed. Review the logs to identify the issue.
Unsure Which Drive to Select
To determine the correct drive, refer to your device’s manual:
- SATA drives (HDD or SSD): Typically labeled as
sda. - NVMe drives: Usually labeled as
nvm0n1.
For further verification, boot any Linux distribution on your device and execute:
lsblk
The output, resembling the following, will help identify the drive:
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 most cases, the correct drive is the first listed or the one not matching the USB stick size.
No Resources in the Cluster
If you can access the cluster but see no resources, SSH into the edge device and check the cluster status:
systemctl status k3s
If the status is not active (running), the cluster isn’t operational. Restart it with:
sudo systemctl restart k3s
If the cluster is active or restarting doesn’t resolve the issue, inspect the installation logs:
systemctl status umh-install
systemctl status helm-install
Persistent errors may necessitate a system reinstallation.
I can’t SSH into the virtual machine
Ensure that your computer is on the same network as the virtual machine, with no firewalls or VPNs blocking the connection.
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.