I recently found myself in a common homelab dilemma: I needed a dedicated machine for a jumphost and remote development environment, but all my spare hardware was already tied up with my Proxmox server running other services. So, I decided to leverage my existing Proxmox setup and install Omakub inside a virtual machine.
Omakub, based on Ubuntu, provides a clean and efficient workspace, perfect for keeping my main PC clutter-free while still having a powerful Linux environment at my fingertips. This guide will walk you through setting up a fresh Ubuntu 24.04 VM in Proxmox and then installing Omakub.
VM Specification
For this setup, I allocated the following resources to my Proxmox VM:
VCPU: 8
RAM: 16 GB
Storage: 512 GB SSD
Step by Step: Ubuntu 24.04 Installation (Proxmox VM)
Download Ubuntu 24.04 ISO:
First, grab the official Ubuntu 24.04 Desktop ISO from the Ubuntu website.
https://releases.ubuntu.com/24.04/
Create a New VM in Proxmox:
Follow the standard Proxmox procedure to create a new virtual machine.
Mount the downloaded Ubuntu ISO as a CD/DVD drive.
Configure the VM with the specifications mentioned above (8 VCPU, 16 GB RAM, 512 GB SSD).
Ensure you select “Qemu Agent” in the VM options for better integration.
Install Ubuntu 24.04:
Boot the VM and proceed with a fresh installation of Ubuntu 24.04 Desktop. Follow the on-screen prompts to set up your user, timezone, etc.
Post-Installation Setup
Once Ubuntu is installed and you’ve rebooted into your fresh desktop, perform these crucial steps before installing Omakub:
Update all repositories:
sudo apt update && sudo apt upgrade -y
If a reboot is requested after the update, go ahead and reboot your VM.
Install essential tools:
sudo apt install -y vim qemu-guest-agent openssh-server
After ensuring your system is updated and services are running, you can enable Remote Desktop for easier access.
Open Settings > System > Remote Desktop.
Toggle Remote Desktop to ON.
For Remote Login, you can choose to set a specific port (the default RDP port is 3389).
Set your desired username and password for remote access.
Now, you can test connecting to your Ubuntu VM using an RDP client. I use Microsoft Remote Desktop on my Mac.
Omakub Installation
Once you have successfully connected to your Ubuntu VM via RDP, you can proceed with the Omakub installation using their convenient one-line script.
Open a terminal in your Ubuntu VM and run:
wget -qO- https://omakub.org/install | bash
Follow the on-screen prompts to select your preferred options. The installation will take some time and will eventually request a reboot.
Post-Omakub Installation & Troubleshooting
After Omakub is installed and your VM has rebooted, try to connect again via RDP.
Xorg Session: Omakub uses Xorg. If you experience lagging or a black screen upon login, ensure you select “Ubuntu on Xorg” after entering your username and before typing your password. Look for a small gear icon (or similar) in the bottom right corner of the login screen to choose the session type.
RDP Black Screen Troubleshooting (macOS Microsoft Remote Desktop):
If you encounter a black screen specifically when using Microsoft Remote Desktop on macOS, you might need to adjust the RDP connection file:
Right-click on your existing connection in Microsoft Remote Desktop.
Select “Export” to save the connection settings as an .rdp file.
Open the saved .rdp file with a text editor.
Locate the line:
use redirection server name:i:0
Change it to:
use redirection server name:i:1
Save the modified file.
Import the edited file as a new connection in Microsoft Remote Desktop.
A common issue when using Remote Desktop from macOS to a Linux VM (especially with Omakub) is that macOS’s system-level shortcuts can conflict with the VM’s shortcuts, particularly those involving the Super key (Cmd key on Mac). For example, Super+Space often triggers Spotlight on macOS instead of Omakub’s application launcher.
To resolve this, you can adjust the hotkeys within Omakub to avoid conflicts:
Ulauncher (“Type app to launch”):
Original:Super + Space
New:Shift + Super + Space
You can find and modify this shortcut within Omakub’s settings, often under “Keyboard” or “Custom Shortcuts,” specifically looking for Ulauncher.
“See all apps” (System):
Original:Super + A
New:Shift + Super + A
“Close app” (Windows):
Original:Super + W
New:Shift + Super + W
By changing these keybindings in Omakub, you allow macOS to retain its system-level shortcuts while still having access to Omakub’s features with non-conflicting combinations.
Conclusion
You’ve now successfully installed Omakub on an Ubuntu 24.04 virtual machine within Proxmox! This setup provides a powerful and isolated environment for your jumphost and remote development needs, all while leveraging your existing homelab infrastructure. Enjoy your clean main PC and your new Omakub workspace!
Check kubectl command in master node. Now, it will display more than 1 node (which is the includes all the installed worker nodes).
kubectl get node
⚠️ If you stuck in when starting k3s-agent. Make sure worker node and master node can be connecting. it could be firewall, proxy server, or incorrect/mismatched MTU. Script below can be use for check the connectivity.
curl -ks https://ipaddress:6443/ping
Install and Configure services in the Master Node
Because we disable some service in the master node. Now we are going to install it the replacement services.
HELM - Package Manager Installation
Install Helm using script below (the latest script can be seen on the Helm docs):
MetalLB - Load Balancer Installation and Configuration
Services
As default, all resources in Kubernetes are isolated, specifically pods.
Pods are isolated by default. To enable communication between pods or with the external network, you need to configure Services.
There are several type of service:
ClusterIP → Default services, ClusterIP services provide an internal IP address within the cluster that other pods can use to communicate. They are not directly accessible from outside the cluster.
NodePort (Port 30000-32767) → NodePort services expose a port on each node in the cluster, allowing external access. The port range 30000-32767 is the default range.
LoadBalancer → LoadBalancer services provision an external load balancer that distributes traffic to multiple pods.
Pull the nginx-ingress from the repository, it will download tgz file.
# run this in the home dir or other directoryhelm pull nginx-stable/nginx-ingress# extract the tgztar xvf nginx-ingress-*
Change directory to nginx-ingress and edit values.yaml file.
cd nginx-ingress# edit values.yamlvim values.yaml# locate ingressClass and change the variable below to true...ingressClass:... setAsDefaultIngress: true...
Search the nginx, we will use bitnami/nginx for the webserver nginx
helm search repo nginx
Pull the nginx from the repository, it will download tgz file.
# run this in the home dir or other directoryhelm pull bitnami/nginx# extract the tgztar xvf nginx-* #make sure the nginx not nginx-ingress
Change directory to metallb and edit values.yaml file.
cd nginx# editvim values.yaml#locate these variables...ingress: enabled: true ... hostname: nginx.demo.local # make sure this FQDN is pointing to the ingress IP ... ingressClassName: "nginx" # check using `kubectl get ingressclass`...