Skip to content

Uyuni Development Environment on macOS

Jump to bottom
Karl Tarvas edited this page Jul 11, 2024 · 54 revisions

The below setup has been tested on macOS Catalina (10.15) through Ventura (13.3).

Tooling & system configuration

Xcode command line tools and Homebrew are used for tooling dependencies, while VMware Fusion is used for virtualization. Alternative setups are also possible, but are not addressed in this guide.

  • Install Xcode command line tools
    • Open Terminal and run $ xcode-select --install. If the service times out, you can also download the tools from the Apple Developer portal.
    • Once done, run $ sudo xcodebuild -license to accept the license agreement neither one of us read.
  • Download and install Homebrew
  • Download and install VMware Fusion

After VMWare Fusion is installed, give it escalated security permissions. Open System Preferences → Privacy & Security → Accessibility, then add and enable VMWare Fusion.

Host tooling

Download and install JDK 11.

Install Python, Ant, RPM and rpm2cpio:

$ brew install python ant rpm rpm2cpio

In your .bashrc or equivalent, add or combine:

export PATH="/usr/local/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/libarchive/lib"
export CPPFLAGS="-I/usr/local/opt/libarchive/include"
export PKG_CONFIG_PATH="/usr/local/opt/libarchive/lib/pkgconfig"

Source your rc or relaunch your terminal session to ensure the environment is correct.
Confirm you're using the Brew version of pip3, the command should be found in /usr/local/bin, not /usr/bin. If the latter is found instead, PATH is incorrectly configured.

$ which pip3
/usr/local/bin/pip3

Install yaml for Python:

$ pip3 install PyYAML

In a location of your choice, clone obs-to-maven, and then add it to $PATH:

$ cd ~/Repositories
$ git clone git@github.com:uyuni-project/obs-to-maven.git
$ cd obs-to-maven
$ pip3 install setuptools
$ pip3 install .

Note: You can also run python3 setup.py install instead of pip3 install . to install the obs-to-maven setup after installing setuptools.

Then in your .bashrc or equivalent:

export PATH="<path to parent directory>/obs-to-maven:$PATH"

Then source your rc or start a new terminal session.

Edit obs-to-maven/obs_maven/core.py and update the shebang to use Homebrew's Python and the related packages, note the addition of local:

#!/usr/local/bin/python3

Install Podman, we use it to communicate with remote containers.

$ brew install podman

Creating a virtual machine

  • Download the base OS ISO. If you have SSO access, you can use SCC via Okta → SUSE Okta B2C → SUSE Customer Center.
    NB! Check the docs for which specific OS version you need to use, not all versions are supported.
    • For SUMA, use the SLE Micro self-install image
    • For Uyuni, use the openSUSE Leap Micro self-install image

The below steps are written referencing SLE Micro, but should carry over cleanly to openSUSE Leap Micro.

  • Open VMWare Fusion, select File → New and use the ISO you downloaded
  • Before the finish step, choose Customize Settings
  • Open the Processors & Memory settings pane and update the specs. See Hardware Requirements in the docs for recommended minimal values.
    • For a server: at least 2 processor cores, at least 4GB memory for a server
    • For a client and a minion: at least 1 processor core, at least 2GB memory
  • Open the Advanced settings pane, turn on Disable Side Channel Mitigations
  • Open Hard Disk and increase the disk size, at least 400GB dynamically allocated for a server
  • Start the VM

Handy tip: VMware Fusion captures your mouse and keyboard by default, the key combination to break out is cmd + ctrl.

If you have correctly inserted the disk image, you'll be greeted with the boot menu.

Choose installation, the default setup suffices, but notably:

  • Be sure to choose the correct keyboard layout for your keyboard
  • Take note of the root password you choose

Configuring the virtual machine

Once your installation is successful, you'll be greeted by a login prompt, log in as root with the password you just set.
If you prefer, you can ip addr to get the IP of the VM and then SSH in from the host as root, this way copy-paste will work etc and it's generally more convenient to work.

If you use SSH, you might need to disable locale forwarding for SSH.

Register your system with SCC

If you're using SLE Micro, you must register your system. You can get the product key from SCC under My Organizations → Organization → Subscriptions, search for micro and then copy the Registration Code for the architecture you're using.

$ SUSEConnect -e <YOUR_SCC_EMAIL> -r <REGISTRATION_CODE>

SSH public key authentication

Both managing and deploying to your server will be easier if you don't need to use password login. To copy your public key from the host to the VM, you can use ssh-copy-id from the host:

$ ssh-copy-id -i ~/.ssh/id_rsa.pub root@server.local

You can disable SSH password login after that. In the VM, edit /etc/ssh/sshd_config:

PasswordAuthentication no

Give the VM a fully qualified domain name (FQDN)

The server's FQDN is tied to the SSL certificate it uses to securely communicate with clients. Below we're going to configure the VM as server.local, if you want to use a different setup, change the values accordingly.

$ sysctl kernel.hostname=server
$ echo "server" | sudo tee /etc/hostname
$ echo -e ".local" | sudo tee -a /etc/mdns.allow

Install Avahi, then reboot the system:

$ transactional-update pkg install avahi
$ reboot

Edit the Avahi configuration

$ vim /etc/avahi/avahi-daemon.conf

Uncomment and set the following fields as below:

host-name=server
domain-name=local 
browse-domains=local

use-ipv4=yes
use-ipv6=yes
allow-interfaces=eth0
deny-interfaces=

publish-hinfo=yes
publish-workstation=yes
publish-domain=yes

Edit the NSS configuration:

$ vim /etc/nsswitch.conf

Uncomment and set the following fields as shown:

hosts: files mdns dns
networks: files mdns dns

Enable Avahi and start it up:

$ systemctl enable avahi-daemon
$ systemctl start avahi-daemon

Run a status check and confirm the host name is configured as expected (should be server.local):

$ systemctl status avahi-daemon
● avahi-daemon.service - Avahi mDNS/DNS-SD Stack
   Loaded: loaded (/usr/lib/systemd/system/avahi-daemon.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2020-10-07 14:43:03 CEST; 1 day 8h ago
 Main PID: 5143 (avahi-daemon)
   Status: "Server startup complete. Host name is server.local. Local service cookie is 4268603158."
    Tasks: 1
   CGroup: /system.slice/avahi-daemon.service
           └─5143 avahi-daemon: running [server.local]

Confirm that everything works as expected by pinging the VM by its name from the host:

$ ping server.local

If the daemon status is correct as shown above but you cannot ping the machine, firstly check whether you can ping the machine by the IP. If that doesn't work, make sure the VM network is set to Bridged Adapter and the firewall isn't blocking you. If you can ping the VM by IP but not by the hostname, try flushing the DNS on the host. If you're having trouble connecting after waking the host from sleep, restarting the Avahi daemon may help.

Set Uyuni up in a container

Inside the VM, add the repository for uyuni-tools, then install mgradm:

$ zypper ar https://download.opensuse.org/repositories/systemsmanagement:/Uyuni:/Stable:/ContainerUtils/openSUSE_Leap_Micro_5.5/ uyuni-container-utils
$ transactional-update pkg install mgradm
$ transactional-update pkg install mgrctl
$ reboot

After the reboot, install the product. Make sure to use the FQDN you configured earlier.

$ mgradm install podman server.local

Opening https://server.local in your browser, you should see the product login page.

Take a snapshot of your virtual machine

If everything works as expected, take a snapshot of your VM via the menu item Virtual Machine → Snapshots.

It is a good idea to take a snapshot of your VM periodically when you're done with bigger changes.

Next steps

After the installation, your system should be ready for development.

You can see the Java development guide and the frontend development guide for instructions on how to test and deploy changes.

As a quickstart, you can run the frontend proxy from the host:

$ yarn install
$ yarn proxy https://server.local

Or deploy changes into the container:

$ ant -f java/manager-build.xml ivy
$ ant -f java/manager-build.xml -Ddeploy.mode=remote-container -Ddeploy.host=server.local deploy deploy-static-resources restart-tomcat restart-taskomatic

Managing virtual machines

If you've successfully trot through the previous steps, your virtual machines are ready for regular use and don't need to be run in windowed mode anymore. The following functions in your .bashrc or similar can help manage VMs.

# List running VMs
vm-list () {
  vmrun list
}

# Start a VM, takes a list of names, for example `$ vm-start server`
vm-start () {
  for item in "$@"
  do
    vmrun start ~/Virtual\ Machines.localized/$item.vmwarevm nogui
  done
}

# Save the current state of a VM and then suspend it, takes a list of names, for example `$ vm-stop-save server`
vm-stop-save () {
  for item in "$@"
  do
    vmrun suspend ~/Virtual\ Machines.localized/$item.vmwarevm
  done
}

# Save the current state of a VM and then stop it, takes a list of names, for example `$ vm-stop-shutdown server`
vm-stop-shutdown () {
  for item in "$@"
  do
    vmrun stop ~/Virtual\ Machines.localized/$item.vmwarevm
  done
}

Using the above, you can start three virtual machines in headless mode in one line:

$ vm-start server client minion

Note that there will be a delay between the machine starting and the operating system booting to being fully functional to handle your requests.

Troubleshooting

mgradm install fails due to format mismatch

Error: cannot inspect host values: cannot inspect host data: cannot read config: While parsing config: line `[...]` doesn't match format

Try turning off locale forwarding for SSH, see this Slack thread for more context. In short, SSH forwards your locale by default, but locale names between macOS and Linux don't match, leading to parsing issues.

Notes

A fully native development environment on macOS is not possible as of this writing.
Remaining known showstoppers are:

Clone this wiki locally