Workbrew Deployment Guide: SimpleMDM

Before you begin following this guide, you should:

• Have access to a SimpleMDM instance, with user permissions to:
  
  • Allow Configuration Changes
  • Allow Group Changes
  • Allow API Management
• A Workbrew workspace:
  
  • New to Workbrew? Create a free account and follow the Getting Started guide.
• Be aware of the system requirements for Workbrew (and Homebrew):
  
  • Everything Homebrew requires:
    
    • An Apple Silicon CPU or 64-bit Intel CPU.
    • macOS Ventura (13) (or higher) installed on officially supported hardware.
    • The Bourne-again shell for installation (i.e. bash).
    • Don’t worry about the Command Line Tools (CLT) for Xcode requirement, Xcode CLT will be installed as part of deployment.
  • Device enrolled in SimpleMDM.
  • User account in the `admin` group or in the `workbrew_users` group

Are you an experienced SimpleMDM administrator? These steps will get you up and going quickly. Read on for more detailed explanations.

1. In SimpleMDM, retrieve your API key by signing into your SimpleMDM account, visiting "Settings" and then selecting the "API" tab. The API key should have “read” permissions for Devices and Device Groups.
2. In the Workbrew console, enter the workspace settings and select SimpleMDM as the MDM Type. Enter your SimpleMDM API Secret Access Key, and then save the Workbrew Workspace API key and installation script.
3. In SimpleMDM, add the Workbrew Workspace API key and installation script as a standalone script and create a job to run it on your devices.

Important: The installation script must run and complete successfully before the next step. SimpleMDM has no builtin way of enforcing the order in which jobs run and apps are installed, we recommend you add the installation script and ensure all devices have successfully run it before continuing setup. Alternatively you can use Munki which allows you to run the installation script as a command during pre-installation.

4. In SimpleMDM, add the Workbrew .pkg as a Custom App.
5. In SimpleMDM, use an Assignment Group to deploy the Workbrew .pkg to your devices.
6. In the Workbrew console, after deployment to a device, check Devices to ensure the expected device appears (please be aware that device inventory is updated periodically, not in real time).
7. If needed, check the Troubleshooting guide and FAQ or contact us for support.

Workbrew is installed using a signed .pkg file, which installs several components:

• The Workbrew agent.
• The Secure Workbrew CLI, a wrapper around the standard Homebrew CLI.

‍

Before installing the Workbrew .pkg on each device, you must run a (bash) script which connects the Workbrew agent to your Workbrew Console. The script also installs Command Line Tools for Xcode if your devices do not already have it. The Workbrew Console connection wizard will guide you through customization to your install script.

You can deploy the installation script as a script and configure a Job to run it. SimpleMDM has no builtin way of enforcing the order in which commands run and apps are installed. We recommend you add the installation script and ensure all devices have successfully run it before continuing with installing the Workbrew .pkg.

You can deploy the Workbrew .pkg as a Custom App. You can use an Assignment Group to deploy the Workbrew .pkg to your devices.

In brief, you will perform these steps to ready Workbrew for deployment:

• Create a SimpleMDM API key,
• Complete the Workbrew Console connection wizard, adding the API key in the process,
• Add the Workbrew Package and setup script to SimpleMDM,
• Create an Assignment Group for Workbrew to install the Custom App,

To populate your Workbrew Console with information about your devices and users, Workbrew requires API access to your SimpleMDM instance. In this section, you will create an API key with sufficient permissions and retain the credentials for input into Workbrew. The API key should have “read” permissions for Devices and Device Groups, all other permissions can be set to “none”.

To complete this step, retrieve your API key by signing into your SimpleMDM account, visiting "Settings" and then selecting the "API" tab. See the SimpleMDM Documentation for more information.

Add SimpleMDM to your Workbrew workspace

The API Token created in the previous step will allow Workbrew to read from your SimpleMDM instance using the API. In this section, you will register SimpleMDM as your MDM of choice within Workbrew.

• From the Workbrew Console, select Settings. Ensure you are in the Workspace tab.
• Under MDM Type, select “SimpleMDM”.
• In the SimpleMDM API Secret Access Key field, enter the SimpleMDM API key generated in the previous section.
• Click Update Workspace.

Open Workbrew Workspace API key and installation script, copy the script, and store it for later. This script will run as a Job independent from the Custom App.

Add the script

The Workbrew Workspace API key and installation script saved in the previous step prepares the device for a Workbrew installation, setting environment variables for workspace directories and the Workbrew Workspace API key. It also installs a Homebrew dependency, Command Line Tools for Xcode, using MacOS’s `softwareupdate` utility. In this section, you will add the script to SimpleMDM and run it with a Job.

Important: The installation script must run and complete successfully before the next step. SimpleMDM has no builtin way of enforcing the order in which jobs run and apps are installed, we recommend you add the installation script and ensure all devices have successfully run it before continuing setup. Alternatively you can use Munki which allows you to run the installation script as a command during pre-installation.

To add the script to SimpleMDM, follow the instructions in Creating a script until you reach the following numbered steps:

• 3. Name the script “Workbrew Workspace installation and setup”
• 4. Paste the script copied from the previous step.

The script can be run with a Job. Follow the instructions in Creating a Job until you reach the following numbered steps:

• 3. Name the job “Run Workbrew setup script”
• 4. Select the script added previously.
• 5. Select the target devices.
• 6. Select when to run the script. Please note the above warning about sequencing: this script must be run before the Workbrew .pkg is installed.

Add the package

The Workbrew .pkg installs Workbrew, including the agent, CLI, and Homebrew. In this section, you will add the package to SimpleMDM so that it can be distributed as part of an Assignment Group.

Download the package, and then follow the instructions under Adding macOS Packages until you reach the following numbered step:

• 3. Upload the Package file to SimpleMDM. Make sure to wait for the upload to complete before navigating away from the page.

The Custom App will be deployed through an Assignment Group. In this step, you will create an Assignment Group and add the Workbrew Custom App to it.

Follow the steps in Creating and Using Assignment Groups until you reach the following numbered steps:

• 3. Click "Save".
• 3. Select "Install Apps and Media".

You can now assign device groups or devices to the group. Once Workbrew has been deployed to a device, it will appear on the Workbrew Console

• Getting Started
• Frequently Asked Questions
• Troubleshooting
• Workbrew Blog