hostmgr

What is it?

This tool suite is used to create and manage VMs on our Buildkite CI Mac hosts:

• hostmgr is a command-line tool to:
  • Create, package and publish VMs… (when we prepare new VMs for new macOS or Xcode versions)
  • List installed VMs, fetch VMs, start and stop VMs… (when running this tool on our CI hosts, to boot VMs and run Buildkite jobs in them)
• hostmgr-helper is a helper tool used to display the VM's GUI in a window on the host machine.
  • This helper shows up as a Menu Bar item in your Mac, listing running VMs and allowing you to VNC to them, show their UI in a window, or stop them.
  • It is especially useful when creating new OS templates for VMs, to go through the macOS setup wizard via the GUI when configuring the template VM.

Installation

Those tools are installed in our macOS CI hosts when those are deployed, using the Ansible playbook

When you need to install those tools on your local machine—typically to create new OS templates or Xcode VMs—follow the below instructions:

(We can potentially automate this step, but for now this is still manual)

1. Run sudo mkdir -p /opt/ci/ && sudo chown <your-mac-user-name> /opt/ci.
2. Create a few directories: mkdir -p /opt/ci/bin /opt/ci/vm-images /opt/ci/working-vm-images.
3. Download hostmgr and hostmgr-helper from the latest release and move them to /opt/ci/bin.
4. Give the downloaded binaries executable permission: chmod u+x /opt/ci/bin/hostmgr /opt/ci/bin/hostmgr-helper.
5. You might also need to remove the quanrantine flag from downloaded executables so they can run from Terminal:
   • Either by right-clicking the executable in the Finder, selecting "Open" in the context menu, and click "Open" button.
   • Or by running xattr -d com.apple.quarantine /opt/ci/bin/hostmgr /opt/ci/bin/hostmgr-helper.
6. Add /opt/ci/bin to your PATH so that the VM tools will be able to use hostmgr and hostmgr-helper
7. Create a config file in /opt/ci/hostmgr.json. You can copy the file we use to provision our macOS CI hosts directly there.
8. Open a Terminal and run hostmgr-helper to launch the "hostmgr-helper" macOS app, which needs to be running during building VM images.

Release

1. Create a PR to update the version property.
2. After the PR is merged, create a tag named same as the updated version,
3. Once the tag is pushed up to this repo, a CI job will be automatically kicked off to create a GitHub release for the tag.