Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

macOS setup experience guide: Document order (#32341)

Browse Source 
- Document order of what happens and when during new Mac setup
- Add anchor links to sections

---------

Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
This commit is contained in:
Noah Talerman
2025-09-01 11:26:23 +09:00
committed by GitHub
co-authored by Mike Thomas
parent 68005bd44f
commit 99ff046e2d
1 changed files with 51 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
articles/macos-setup-experience.md
+51 -38
View File
@@ -2,17 +2,23 @@
_Available in Fleet Premium_
In Fleet, you can customize the out-of-the-box macOS Setup Assistant with Remote Management and Automated Device Enrollment (ADE) for end users:
In Fleet, you can customize the out-of-the-box macOS setup.
* Require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac.
Here's what you can configure, and in what order each happen, to your macOS hosts during setup:
* Customize the macOS Setup Assistant by choosing to show or hide specific panes.
1. Require [end users to authenticate](#end-user-authentication-and-end-user-license-agreement-eula) with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac.
* Install a bootstrap package to gain full control over the setup experience by installing tools like Puppet, Munki, DEP notify, custom scripts, and more.
2. By default, Fleet's agent (fleetd) is installed to enroll the host to Fleet. Optionally, you can [deploy fleetd manually](#advanced).
* Install software (App Store apps, custom packages, and Fleet-maintained apps).
3. Install a [bootstrap package](#bootstrap-package) to gain full control over the setup experience by installing tools like Puppet, Munki, DEP notify, custom scripts, and more.
* Run a script.
4. By default, Fleet installs configuration profiles to [enforce OS settings](https://fleetdm.com/guides/custom-os-settings).
5. [Install software](#install-software) (App Store apps, custom packages, and Fleet-maintained apps).
6. [Run a script](#run-script).
7. Customize the [macOS Setup Assistant](#macos-setup-assistant) by choosing to show or hide specific panes.
In addition to the customization above, Fleet automatically installs the fleetd agent during out-of-the-box macOS setup. This agent is responsible for reporting host vitals to Fleet and presenting Fleet Desktop to the end user.
@@ -40,8 +46,6 @@ Using Fleet, you can require end users to authenticate with your identity provid
> (SSO)](https://fleetdm.com/docs/deploy/single-sign-on-sso) in Fleet, you still want to create a
> new SAML app for end user authentication. This way, only Fleet users can log in to Fleet.
### End user license agreement (EULA)
To require a EULA, in Fleet, head to **Settings > Integrations > Automatic enrollment > End user license agreement (EULA)** or use the [Fleet API](https://fleetdm.com/docs/rest-api/rest-api#upload-an-eula-file).
@@ -133,6 +137,45 @@ To sign the package we need a valid Developer ID Installer certificate:
3. Select **Upload** and choose your bootstrap package.
## Software and script
You can configure software installations and a script to be executed during Setup Assistant. This capability allows you to configure your end users' machines during the unboxing experience, speeding up their onboarding and reducing setup time.
If you configure software and/or a script for setup experience, users will see a window like this pop open after their device enrolls in MDM via ADE:
![screen shot of Fleet setup experience window](../website/assets/images/articles/install-software-preview-462x364@2x.png)
This window shows the status of the software installations as well as the script exectution. Once all steps have completed, the window can be closed and Setup Assistant will proceed as usual.
To replace the Fleet logo with your organization's logo:
1. Go to **Settings** > **Organization settings** > **Organization info**
2. Add URLs to your logos in the **Organization avatar URL (for dark backgrounds)** and **Organization avatar URL (for light backgrounds)** fields
3. Press **Save**
> See [configuration documentation](https://fleetdm.com/docs/configuration/yaml-files#org-info) for recommended logo sizes.
> The setup experience script always runs after setup experience software is installed. Currently, software that [automatically installs](https://fleetdm.com/guides/automatic-software-install-in-fleet) and scripts that [automatically run](https://fleetdm.com/guides/policy-automation-run-script) are also installed and run during Setup Assistant but won't appear in the window. Automatic software and scripts may run before or after setup the experience software/script. They aren't installed/run in any particular order.
### Install software
To configure software to be installed during setup experience:
1. Click on the **Controls** tab in the main navigation bar, then **Setup experience** > **4. Install software**.
2. Click **Add software**, then select or search for the software you want installed during the setup experience.
3. Press **Save** to save your selection.
### Run script
To configure a script to run during setup experience:
1. Click on the **Controls** tab in the main navigation bar, then **Setup experience** > **5. Run script**.
2. Click **Upload** and select a script (.sh file) from the file picker modal.
> Once the script is uploaded, you can use the buttons on the script in the web UI to download or delete the script.
## macOS Setup Assistant
When an end user unboxes their new Mac, or starts up a freshly wiped Mac, they're presented with the macOS Setup Assistant. Here they see panes that allow them to configure accessibility, appearance, and more.
@@ -183,36 +226,6 @@ Testing requires a test Mac that is present in your Apple Business Manager (ABM)
4. Boot up your test Mac and complete the custom out-of-the-box setup experience.
## Software and script
You can configure software installations and a script to be executed during Setup Assistant. This capability allows you to configure your end users' machines during the unboxing experience, speeding up their onboarding and reducing setup time.
If you configure software and/or a script for setup experience, users will see a window like this pop open after their device enrolls in MDM via ADE:
![screen shot of Fleet setup experience window](../website/assets/images/articles/install-software-preview-462x364@2x.png)
This window shows the status of the software installations as well as the script exectution. Once all steps have completed, the window can be closed and Setup Assistant will proceed as usual.
To replace the Fleet logo with your organization's logo, head to **Settings** > **Organization settings** > **Organization info**, add URLs to your logos in the **Organization avatar URL (for dark backgrounds)** and **Organization avatar URL (for light backgrounds)** fields, and select **Save**. See [configuration documentation](https://fleetdm.com/docs/configuration/yaml-files#org-info) for recommended logo sizes.
> The setup experience script always runs after setup experience software is installed. Currently, software that [automatically installs](https://fleetdm.com/guides/automatic-software-install-in-fleet) and scripts that [automatically run](https://fleetdm.com/guides/policy-automation-run-script) are also installed and run during Setup Assistant but won't appear in the window. Automatic software and scripts may run before or after setup the experience software/script. They aren't installed/run in any particular order.
### Install software
To configure software to be installed during setup experience:
1. Click on the "Controls" tab in the main navigation bar. Click on "Setup experience", and then on "4. Install software".
2. Click the "Add software" button. In the modal, select the software that you want to have installed during the setup experience. You can search the list of software by using the search bar in the modal. Click "Save" to save your selection and close the modal.
### Run script
To configure a script to run during setup experience:
1. Click on the "Controls" tab in the main navigation bar. Click on "Setup experience", and then on "5. Run script".
2. Click "Upload" and select a script (.sh file) from the file picker modal. Once the script is uploaded, you can use the buttons on the script in the web UI to download or delete the script.
### Configuring via REST API
Fleet also provides a REST API for managing setup experience software and scripts programmatically. Learn more about Fleet's [REST API](https://fleetdm.com/docs/rest-api/rest-api).