How to create a UBOS development VM for VMware Workstation on any `x86_64` system

/docs/linux/developer/create-developer-vm/x86_64-vmware-workstation/

Note

As of February 2025, the Gnome UI may not come up. That appears to be an upstream bug related to the VMWare virtual graphics card that causes the Gnome session to crash.

These instructions should work on Windows and Linux.

Install VMWare Workstation

This product can be obtained from https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion. It appears it is now available free of charge.

Note: on some Linux versions, like Arch, VMWare Workstation may be available through package repositories, which might make installation and management easier.

Obtain an Arch Linux image

Download an ISO with a recent data in its filename from one of the mirrors listed at https://archlinux.org/download/.

Run the Arch Linux image as the virtual machine to create the development VM with

Run VMWare Workstation.
In VMware Workstation, create a new virtual machine:
- In the “Home” tab, select “Create a New Virtual Machine”.
- In “Virtual Machine Configuration”, select “Typical (recommended)”. Click “Next”.
- In “Install operating system from”, select “Use ISO image”. Using “Browse…”, select the ISO image you downloaded earlier. Ignore the warning that it could not detect which operating system is in this image. Click “Next”.
- In “Guest Operating System”, select “Linux”, and then in the “Version” popup, “Other Linux 6.x kernel 64-bit”. Click “Next”.
- In “Virtual Machine Name”, set the “Name” to “ubosdev_x86_64-vmware-YYYYMMDD-I” where YYYYMMDD is the date, and I is a number starting with 1. Accept the default for the “Location”. Click “Next”.
- In “Disk Size”, set the size to 60.0 GB. Select “Split virtual disk into multiple files”. Click “Next”.
- In “This virtual machine will be created with the following settings:”, click “Customize Hardware…”, and then:
  - In the “Hardware” tab:
    - Set Memory to 8192 GB
    - Set Processors to 2
    - Leave the other settings unchanged. Click “Close”.
  - In the “Options” tab:
    - Select “Advanced”, and in “Firmware type” select “UEFI”.
  Click “Finish”.
- In “Install the Guest Operating System” and “Install VMWare Tools”, click “Close”.
- If a “Hint” window comes up with advice about swap space, ignore it and click “OK”.
The VM is now starting.

Install Arch on the empty disk and configure it

Wait for the shell to appear.

Update the bootstrap VM and install some packages we need:

# pacman -Sy
# pacman -S archlinux-keyring
# pacman -Su
# pacman -S btrfs-progs gptfdisk parted dosfstools arch-install-scripts vi

If there is an error about the kernel image not existing, ignore it.

Zero out the first bytes on the disk for extra robustness:

# dd if=/dev/zero of=/dev/sda bs=1M count=8 conv=notrunc

Clear the partition table:
```
# sgdisk --clear /dev/sda
```

Create the partitions (UEFI, /boot and /) and change them to the right types.

# sgdisk --new=1::+1M /dev/sda
# sgdisk --new=2::+512M /dev/sda
# sgdisk --new=3:: /dev/sda
# sgdisk --typecode=1:EF02 /dev/sda
# sgdisk --typecode=2:EF00 /dev/sda

Make sure changes are in effect:
```
# sync
# partprobe /dev/sda
```
Create filesystems for partitions other than the UEFI partition:
```
# mkfs.vfat  /dev/sda2
# mkfs.btrfs /dev/sda3
```

Mount the partitions so we can install:

# mount /dev/sda3 /mnt
# mkdir /mnt/boot
# mount /dev/sda2 /mnt/boot

Perform the actual install of the base packages:
```
# pacstrap /mnt base
```

Generate the right fstab:

# genfstab -U -p /mnt >> /mnt/etc/fstab

Chroot into your future root disk and finish the installation:

# arch-chroot /mnt

Add the UBOS keyring so we can install our own packages:

# curl -O https://depot.ubosfiles.net/yellow/$(uname -m)/os/ubos-keyring-0.9-2-any.pkg.tar.xz
# pacman -U ubos-keyring-0.9-2-any.pkg.tar.xz
# rm ubos-keyring-0.9-2-any.pkg.tar.xz

Add the UBOS tools repo:

# echo '' >> /etc/pacman.conf
# echo '[virt]' >> /etc/pacman.conf
# echo 'Server = https://depot.ubosfiles.net/yellow/$arch/virt' >> /etc/pacman.conf
# echo '' >> /etc/pacman.conf
# echo '[ubos-tools-arch]' >> /etc/pacman.conf
# echo 'Server = https://depot.ubosfiles.net/yellow/$arch/ubos-tools-arch' >> /etc/pacman.conf

Install more packages:

# pacman -Sy
# pacman -S linux sudo vim btrfs-progs open-vm-tools \
  gdm gnome-console gnome-control-center gnome-session gnome-settings-daemon \
  gnome-shell gnome-keyring nautilus \
  ubos-tools-arch

If asked which alternatives to install, choose the defaults.

Create a ramdisk:
```
# mkinitcpio -p linux
```
Configure the boot loader:
```
# bootctl --path /boot install
```

Install a locale:

# perl -pi -e 's!#en_US.UTF-8 UTF-8!en_US.UTF-8 UTF-8!' /etc/locale.gen
# locale-gen

Set up networking:

# echo '[Match]' > /etc/systemd/network/wired.network
# echo 'Name=en*' >> /etc/systemd/network/wired.network
# echo '' >> /etc/systemd/network/wired.network
# echo '[Network]' >> /etc/systemd/network/wired.network
# echo 'DHCP=ipv4' >> /etc/systemd/network/wired.network
# echo 'IPv4Forwarding=1' >> /etc/systemd/network/wired.network
# echo 'IPv6Forwarding=1' >> /etc/systemd/network/wired.network

# systemctl enable systemd-networkd systemd-resolved systemd-timesyncd

Create a user with the right permissions and no password:

# useradd -m ubosdev
# chmod 755 ~ubosdev
# passwd -d ubosdev
# echo ubosdev ALL = NOPASSWD: ALL > /etc/sudoers.d/ubosdev
# chmod 600 /etc/sudoers.d/ubosdev

No root password:
```
# passwd -d root
```
Exit from the arch-chroot shell with ^D.

Remainder of networking setup:

# rm /mnt/etc/resolv.conf
# ln -s /run/systemd/resolve/stub-resolv.conf /mnt/etc/resolv.conf

Configure UEFI:

Loader configuration:

# echo timeout 4 > /mnt/boot/loader/loader.conf
# echo default arch >> /mnt/boot/loader/loader.conf

Boot entry configuration:

# echo title Arch > /mnt/boot/loader/entries/arch.conf
# echo linux /vmlinuz-linux >> /mnt/boot/loader/entries/arch.conf
# echo initrd /initramfs-linux.img >> /mnt/boot/loader/entries/arch.conf
# echo options root=PARTUUID=$(lsblk -o PARTUUID /dev/sda3 | tail -1 ) rw >> /mnt/boot/loader/entries/arch.conf

Power off the virtual machine:
```
# systemctl poweroff
```
Remove the ISO file from the VM:
- In the tab for your VM, click “Edit virtual machine settings”.
- Select “CD/DVD (SATA)” on the left, and then uncheck “Connected” and “Connect at power on”.
- Click “Save”.

Remaining configuration

Start the VM again.
At the console, log in as ubosdev. There is no password.

Fix the locale (command won’t run earlier)

% sudo localectl set-locale LANG=en_US.UTF-8

Enable Gnome:
```
% sudo systemctl enable gdm
```
Power off the virtual machine:
```
% sudo systemctl poweroff
```

Now your virtual machine is in the same state as the pre-configured development VM described in Developer setup.

Clean up the VM files and create a zip file for distribution

In the Finder, find the directory that corresponds to the virtual machine. This may be ~/Virtual Machines.localized/ubosdev_aarch64-vmware-YYYYMMDD-I.vmwarevm.

In this directory:
- Delete all files named vmware.log or vmware-N.log where N is a number.

Compress and package the directory:

% zip -r ubosdev_aarch64-vmware-YYYYMMDD-I.vmwarevm.zip ubosdev_aarch64-vmware-YYYYMMDD-I.vmwarevm

How to create a UBOS development VM for VMware Workstation on any x86_64 system

Install VMWare Workstation

Obtain an Arch Linux image

Run the Arch Linux image as the virtual machine to create the development VM with

Install Arch on the empty disk and configure it

Remaining configuration

Clean up the VM files and create a zip file for distribution

How to create a UBOS development VM for VMware Workstation on any `x86_64` system