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

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.
• 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.

Download and install JDK 17.

Install Python, Ant, RPM and rpm2cpio:

brew install python ant rpm rpm2cpio gnu-tar libarchive

In your .bashrc or equivalent, add or combine:

export PKG_CONFIG_PATH="/opt/homebrew/opt/libarchive/lib/pkgconfig"
export PATH="/opt/homebrew/opt/gnu-tar/libexec/gnubin:$PATH"

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 [email protected]: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

• 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.
  • Uyuni docs for the requirements
  • SUSE Multi-Linux Manager docs for the requirements

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 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

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.

If you're using SLE Micro, you must register your system. If you work at SUSE, you can get the product key from Okta → SUSE Okta B2C → SUSE Customer Center. In SCC, go to My Organizations → Organization → Subscriptions, search for micro and then copy the Registration Code for the architecture you're using.

If you didn't enter the credentials during the initial setup, you can later provide them from the terminal.

SUSEConnect -e <YOUR_SCC_EMAIL> -r <REGISTRATION_CODE>

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
echo "127.0.0.1 server.local server localhost" > /etc/hosts
hostnamectl set-hostname server.local

Check that it works:

hostname -f
# Should return: server.local

We use Avahi for multicast DNS and uyuni-tools which provides a set of admin tools.

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

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.

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 [email protected]

You can disable SSH password login after that by editing /etc/ssh/sshd_config:

sed -i 's/^#*PasswordAuthentication yes$/PasswordAuthentication no/' /etc/ssh/sshd_config

Install the product. If you run into installation issues, be sure to check hostname -f returns the correct FQDN.

mgradm install podman

After the setup is done, you should see the product login page at https://server.local.

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.

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 refresh-branding-jar deploy deploy-static-resources restart-tomcat restart-taskomatic

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.

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.

First, ensure you've applied the latest database migrations.

If that's done, ensure you're using GNU tar, not BSD tar which ships out of the box with macOS.

tar --version
# Should return something similar to: tar (GNU tar) 1.35

If you're on wrong tar, install it as described earlier in this guide, then clear ivy cache, reinstall dependencies, and try again.

rm -rf ~/.ivy2/
rm java/lib/*.jar
ant -Divy.cache.ttl.default=0 -Divy.resolution.fresh=true -f java/manager-build.xml ivy

Followed by a new deploy.

For further debugging, check logs in the container, most likely starting with Tomcat.

ssh [email protected]
mgrctl exec "cat /var/log/tomcat/*"

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

• libvirt #75: no functional network driver on macOS