Local virtual machine installation using k3os

Jeremy Theocharis -
⚠️
Please note that k3OS is deprecated. We recommend switching to flatcar instead.

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.
0:00
/

2. Setup k3os

  1. Start the virtual machine by pressing the green arrow button and wait for the initialization.
  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.

3. Setting up NAT-Network

  1. Go back to Tools on the left of VirtualBox and navigate to Network
  2. Press Create on the top left and after installation navigate to NAT-Networks → Port-Forwarding.
  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.
  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.
  5. Start your VM by pressing start.
  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.
  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.

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

ℹ️
See also "Connecting via SSH"

5. Getting Kubernetes credentials and setting up UMHLens

ℹ️
See also "Adding UMH Helm repo"