Local virtual machine installation using k3os

Deploy the UMH stack in a local virtual machine using k3os

  6 minute read  

Here is a step-by-step guide on how to install the UMH stack in a virtual machine on your local system. This is the starting point if you just want to try out our product and see what it is capable of, or you are developing a new feature and want to test it before opening a pull request.

If you want to deploy UMH to production see how to Deploy the full UMH stack onto an edge PC.

Host machine requirements

  • Operating system (64-bit):
    • Windows 8.1, 10, 11
    • Mac OS X 10.13 (High Sierra), 10.14 (Mojave), 10.15 (Catalina)
    • Linux Ubuntu 18.04+, Debian 9+, CentOS/RHEL 6+, Oracle 6+, Fedora 30+, Gentoo, Arch, openSUSE Leap 15.1, or any other system based on Linux Kernel 2.6, 3.x, 4.x, 5.x
  • Hardware:
    • CPU: 2 cores or more
    • RAM: 8GB or more
    • Storage: 10GB free

Installation

1. Create virtual machine

  1. Download and install your preferred hypervisor. We suggest VirtualBox, and you can download it here.

  2. Download the latest version of K3OS here. Pay attention to download the file named k3os-amd64.iso.

  3. Open VirtualBox and press New.

  4. Give your machine a name, like umh, type Linux and Version Other Linux (64-bit). Press Next.

  5. Insert 4096MB as the value for the quantity of RAM. You may need more if you decide to customize the services with the development.yaml file.

  6. Select Create a virtual disk now and click on Create.

  7. Select VDI (VirtualBox Disk Image) and press Next.

  8. Select Dynamically allocated and press Next.

  9. Give it 10,00 GB and press Create.

  10. Go into Settings and navigate in the Storage section.

  11. Press the blue disk icon on the right of Controller: IDE. Then press Add. Navigate through your filesystem to locate the ISO file you downloaded earlier and add it.

  12. Optional: if you customized the development.yaml, check whether you have to increase the CPU power, in which case navigate in System section and select the Processor tab. Then increase the number of CPUs to 4.

2. Setup k3os

  1. Start the virtual machine by pressing the green arrow button and wait for the initialization.

    Untitled

  2. Type the username rancher and press Enter.

  3. Type sudo k3os install and press Enter to begin the system installation.

  4. Choose the option 1 and press Enter to install to disk.

  5. Type y and press Enter to configure the system with a cloud-init file.

  6. Type https://umh.app/development.yaml and press Enter.

  7. Type y to format the disk and proceed with the installation.

  8. At the end of the installation the virtual machine will reboot automatically. Once you get to a screen similar to the one at step 4, write donw your IPv4-Adress(right under the k3os-logo) and navigate into the menu Machine > ACPI Shutdown.

  9. Press the yellow gear button to open the virtual machine settings and navigate into the Storage section. Select k3os-amd64.iso and press the remove button.

    Untitled.png

3. Setting up NAT-Network

  1. Go back to Tools on the left of VirtualBox and navigate to Network

    Untitled

  2. Press Create on the top left and after installation navigate to NAT-Networks → Port-Forwarding.

    Untitled

  3. Press under IPv4 Add new port Forwarding rule and add the following rules:

    Type in for example Name: Node-RED → Host-Port:1880 → Guest-IP:Your IPv4-Adress which you have written down → Guest-Port:1880 → then press Apply.

    Untitled

  4. Restart VirtualBox and go again into your VM-Settings. In the network section open the Attached to drop down menu and select the NAT-Network option. Finally, press the OK button.

    Untitled

  5. Start your VM by pressing start.

    Untitled

  6. You should now see the login for k3os. Make sure that the IPv4-Address(located under Address right under the k3os-logo) is still the same as the one you have written down. If it is not the same shut down your VM (Machine →ACPI-Shutdown) and replace the old IPv4 in Portforwarding→ Guest-IP and restart Virtual-Box. Repeat step 7.

    Untitled

  7. If the IPv4-Address is the same or you have replaced the old one(check step above) you can login with the Username and Password rancher. Then wait until the UMH stack installation is ready and something like shown below is showing up. Press Enter.

    Untitled

🗒️If you want to connect to your microservices make sure to type in localhost in place of the ipv4 address e.g. localhost:1880/nodered

4. Connecting via SSH

  1. Open MobaXTerm on your device. You can get MobaXTerm for free from their Website

  2. Open a new Session by clicking on “Session” in the upper left corner.

    Untitled

  3. Select SSH on the upper part of the new window and type in the IP address (in this case localhost since we use port-forwarding) of the VM in the field “Remote Host”. Check the Box next to“specify Username” and type in rancher in the field next to it.

  4. Press OK to start the connection.

  5. When connecting to the Edge PC it should ask for a password. The default password is rancher. Type it in and press Enter.

  6. You are now successfully logged in via SSH and the interface should look like in the picture below.

    Untitled

5. Getting Kubernetes credentials and setting up UMHLens

  1. Open UMHLens on your device. You can get UMHLens for free from this GitHub Repository.

  2. Click the three horizontal lines in the upper left corner and choose files → preferences .

  3. Click on Kubernetes and select “Add custom repo”, type in https://repo.umh.app as the URL and decide on a name for the repository.

  4. Execute cat /etc/rancher/k3s/k3s.yaml in your SSH session on your laptop (in MobaXTermif you are using a windows OS) to retrieve the Kubernetes credentials. Copy the content of the result into your clipboard with Ctrl + C.

  5. Click File (three horizontal lines in the upper left corner) and then Add Cluster.

  6. Paste the clipboard into the kubeconfig prompt of UMHLens.

  7. Change the IP Address in the kubeconfig to localhost. the port (the last 4 numbers after the colon) needs to stay unchanged. Click then on Add Cluster.

    Untitled

  8. Click on the Cluster to connect to it.

  9. Write ****helm repo add united-manufacturing-hub https://repo.umh.app/into the terminal of the UMHLens Cluster.

  10. Write helm repo updateto update.

  11. Fully close the UMHLens App and start UMHLens again.

  12. Click on Browse Clusters in Catalog, then connect to the Cluster.

  13. Click on Helm -> Releases and change the namespace from default to united-manufacturing-hub in the upper right corner

  14. Click on the Release united-manufacturing-hubto be able to inspect the values.yaml file, which holds the configurations of all microservices used in the cluster.

️️ There’s a bug in OpenLens version 6 that doesn’t load the helm chart. Please refer to this if you have any problem

What’s next

You have successfully deployed the UMH stack in a local virtual machine.

The next step will be to gather some kind of data, and since you did a local installation you probably want to simulate it. We have a guide to generate data with an MQTT Simulator.

You could also directly connect NodeRED without having data. Follow this guide to see how.

If you are not sure on what to do you can get back to the Getting Started page.

Last modified February 17, 2023: update (#208) (ea731fc)