How to use MacStadium's Private Cloud for Continuous Integration for macOS or iOS projects
In this article, we’ll get started with setting up a MacStadium Private Cloud to run builds for your macOS or iOS project. We’ll be using a Private Cloud, which is powered by VMware on dedicated Mac hardware.
Continuous Integration (CI) is a term in modern development for ensuring that your code passes a series of tests (integration tests, historically) on every code check-in. This means having a central point where your code can be checked and have the results reported back to you. This allows teams to iterate rapidly and collaborate on their Source Code Management (SCM) platform of choice (e.g Github, Gitlab or Bitbucket).
In the Linux world, CI is easier than the Mac world, as there are tools like Docker to provide isolated runtime environments for repeatable tests. In the Mac world, this is harder, as there aren’t native containerization tools. We do however have virtualization tools, like VMware (see What’s the difference between containers and virtual machines for more details). This means that on top of MacStadium’s physical Mac hosts, we can create several virtual macOS machines and use them as targets for running our tests on.
In this guide…
- How to use MacStadium’s Private Cloud for Continuous Integration for macOS or iOS projects
- In this guide…
- Choosing a Plan
- Connecting to Your Cloud
- Connecting to vSphere Web Client
- Creating a Virtual Machine
- Installing macOS
- Install VMware Guest Tools
- Installing Build Tools
- Run a Fastlane Test Build
- Next Steps
- Manage your macOS builds with Buildkite
Choosing a Plan
Virtualization means you can run more than one virtual host per physical machine, which means you are dividing up the resources of a single host into several. This means you need to choose the amount of physical machines you need based on how many concurrent builds you want to do. The more concurrent builds you do, the less time developers are waiting for builds. Beyond concurrency, you will need to run a virtual machine for each version of macOS that you are targeting.
A good rule of thumb is 2-3 virtual machines per physical host.
To get started:
- Pick the plan that suits you: https://www.macstadium.com/cloud/
- Choose the data center closest to you
- Choose “Start Trial” and create an account
MacStadium will provision your new environment and email you at the account you nominated. Typically this takes 2-3 working days.
Connecting to Your Cloud
The provisioning team at MacStadium will create a ticket that you can access in https://portal.macstadium.com with your IP Plan document (Excel format, but Google Docs imports it if required).
To access your environment, you will first need to connect via a VPN:
- On Windows, see Configuration Cisco IPSEC VPN in Windows using Shrew VPN Client
- On macOS, see How to setup a MacStadium Cisco IPSEC VPN connection
Connecting to vSphere Web Client
Now that you’ve connected to VPN, you can connect to your vCenter instance. We will use the web interface, although there are native options for Windows and macOS.
- Click the “vCenter Web Client” url in “Step 2: vCenter Login” in your IP Plan.
- Copy and paste in the username and password, being careful to not include whitespace at the end of the fields
If you have vSphere 6.5+ then you can use the HTML5 version by changing your login url to
/ui, for instance https://10.92.192.10/ui.
Otherwise, if you are using the flash version and you receive a white screen, you might need to whitelist the site in your Browser. In Chrome, this is under Content Settings > Flash. You will need to add an exception under allow for the IP address of your vCenter host (e.g 10.92.192.10). Then refresh the original page and it should load.
You should now be able to see your Private Cloud!
Creating a Virtual Machine
Depending on the plan you selected, you will have a different amount of physical hosts, but these are all represented as part of your “Cluster”, which exists in your “Data center” in vSphere. As you grow, this lets you manage multiple networks or groups of hosts within the one interface. For now, we will be dealing with the cluster that represents your private cloud, named something like “MacPro_Cluster”.
We are going to create a single virtual machine running macOS:
- Right-click on the Cluster in the Navigator and select “New Virtual Machine”
- Select “Create a new virtual machine” and Next
- Choose a name, e.g “macOS-10.12” and Next
- In “Select a compute resource”, click Next. If you are prompted, you might need to select a specific host to deploy on if your cloud doesn’t have [DRS Mode] turned on. This just means that your VM will run on that specific host vs VMware determining a host for you.
- Select the datastore for your VM’s files, generally you will only have one of these. Select Next.
- Select the default presented for Compatibility and Next.
- Select Guest OS Family
Otherand Guest OS Version
Apple Mac OS X 10.12 (64-bit). Don’t worry that this won’t match the actual macOS version, we only need one that is close.
- Select the follwing virtual hardware settings before selecting Next:
- New Hard Disk:
- New Network:
Browse > Private-1(The name of your private range in your IP Plan)
CPUand select “Expose hardware assisted virtualization to the guest OS” (in case you want a nested VM)
- New CD/DVD Drive:
Datastore ISO File. Select
ISO > OSX > macOS_Sierra.iso. Ensure that
- Check your summary looks correct, and then Finish.
You should now have a virtual machine listed within your Cluster in the web interface. This will take about 30 minutes.
- Right-click on the virtual machine and select
Power > Power On.
- Click on the virtual machine and then click on the preview image. You should now see the macOS installer starting up.
- Get up to the “Install macOS” screen. If you only see the DVD image, you will need to select
Utilities > Disk Utilityfrom the menu
- Select “VMware Virtual SATA Hard Drive Media”
- Select “Erase” with defaults
- Close Disk Utility and select “Untitled”
- Wait for the installer to run
- When at “How Do You Connect”, select
Local network (Ethernet)
- Select TCP/IP Connection Type
Manuallyand enter the following details before Next:
- IP Address:
10.254.50.2(The first address from your IP Plan under the Private-1 range)
- Subnet Mask:
- Router Address:
- DNS Servers:
126.96.36.199, 188.8.131.52(Google’s DNS servers)
- IP Address:
- Skip Location Services, Apple ID
- Create an Account and note the account details. For this demo, we will use
buildkitewith a password of
- Set a timezone to your local time
You should now be on the desktop, you have a working Mac virtual machine!
Install VMware Guest Tools
VMware has a set of tools that must be installed on macOS. These get mounted via a virtual CD drive.
ISO Download and Upload to vCenter:
- Download a recent version of VMware Tools (10.0.1 is here) and unzip it so that you have a
- Login into vCenter
- Use your storage tabs to navigate to your datastore
- Browse your Datastore, you can upload the ISO to the root folder or create an ISO folder
- Shutdown your machine from within macOS
- From the web interface, right-click on your virtual machine and select
Power > Power Off
- Right click on your virtual machine and select
- Change CD/DVD Drive 1 to
Datastore ISO Fileand select the ISO you uploaded.
- Right click on your virtual machine and select
Power > Power On
- Go back into the desktop of the virtual machine and log in after the reboot
- Install the VMware Tools when prompted
Installing Build Tools
Now that you have a working machine, you will need to install the basic software that you will need to run builds. You can either do this via VNC or via the Web Console, or if you enable Remote Login in the macOS settings, you can SSH in. This guide explains the latter approach as it’s easier to do repeatably and automate as you scale up.
You can access your host via SSH from your desktop provided you have the VPN connected:
All further terminal commands in this guide will assume you are logged into the above.
Homebrew is a package manager for macOS and used for installing the various tools we need. Read more about it at https://brew.sh/. This step will take about 15 minutes. You will be required to put in your password at least once.
Lots of tooling requires a modern Ruby installed (fastlane for instance), so we also update our system Ruby:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" brew install rbenv ruby-build # Add rbenv to bash so that it loads every time you open a terminal echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile source ~/.bash_profile # Install Ruby rbenv install 2.4.2 rbenv global 2.4.2 ruby -v
You can install Xcode via the App Store manually if required, but we recommend Xcode::Install, a tool for installing and managing multiple versions of Xcode. This allows you to use the one machine for multiple versions and swap between them, similar to the approach we took in the previous step for Ruby:
gem install xcode-install rbenv rehash xcversion install 9.0.1 sudo xcode-select -s /Applications/Xcode.app
Run a Fastlane Test Build
git clone https://github.com/buildkite/buildkite-fastlane-demo.git cd buildkite-fastlane-demo bundle install bundle exec fastlane test
This should run the unit tests and some integration tests. Congratulations, you have a working build environment!
Now that you have a base operating system, you can either create multiple virtual machines with the system variations you require. You can convert your VM to a Template and then use that template to create multiple VM’s that you can throw away once you no longer require them:
- Stop VM if running
- Right click on VM > Sekect “Convert to Template”
From that point you can create new VM’s from that template.
Manage your macOS builds with Buildkite
Buildkite is a service that provides orchestration for managing your builds. It connects to Github, Gitlab or Bitbucket and will trigger a build when you push changes to that service. The builds run on the hardware you provide via a software agent. You can easily install the agent on the VM we created above. See https://buildkite.com/docs/agent/osx.
What’s the difference between containers and virtual machines?
In computing, a virtual machine (VM) is an emulation of a computer system. Virtual machines are based on computer architectures and provide functionality of a physical computer. Their implementations may involve specialized hardware, software, or a combination.
VMWare provides virtual machines, which allows you to run different operating systems as the operating system interacts with virtualized hardware. Virtual Machines can be many gigabytes as they need to have the entire operating system and all the drivers and related software in the image and can take 10-20 seconds to boot.
Containers (otherwise known as Operating System Virtualization) is a more lightweight alternative that creates multiple isolated environment within an existing operating system and kernel. Ecosystems like Docker use copy-on-write filesystems to allow for completely ephemeral, isolated environments to be created to run a single process. The advantage to containers is that they start nearly instantly and the filesystem snapshots are much smaller as they don’t have to contain the entire operating system kernel. The downside is they are limited to the same operating system and kernel as the host environment.