Build a Custom MacOS Dock

[mosermat]

Hey Jamf Nation!

Do you need to create a custom MacOS Dock for your users?

I created a guide for the Jamf community, complete with scripts and packages, to help you do that.

After struggling to find a current, working solution I decided to build one myself. Since it took some time to make, I thought I'd share it with others that are looking to do the same thing. Hope it's helpful!

GitHub Repo with Full Guide Here: https://github.com/bluemoosegoose/Build-a-Custom-MacOS-Dock

Some info about it:

This Guide allows you to craft a custom MacOS dock for your environment, written specifically for Jamf Pro Admins.

Verified working on Monterey 12.3.1 and should be backwards compatible.

The custom dock will be built once, on first login, for any user that logs in to the Mac.

After the dock has been built once, it will not run again automatically, which is the intended behavior because we want our users to have our custom dock during onboarding and then give them the ability to make changes.

If you want to re-run the custom dock again, this is possible and can be scoped to a policy or placed in Self-Service. 

In my environment I have the Custom Dock to install on an Enrollment Trigger during onboarding. Then I also have it available in Self-Service for Users to run again anytime they want.

-----

Huge shoutout to @ryan_ball  for inspiring me to create this based on his DockBuilder Project. Dockbuilder is no longer working as of Monterey but you can read more about it here: https://community.jamf.com/t5/jamf-pro/i-built-dockbuilder-for-you/m-p/151356/thread-id/140394 . I used it for a few years with good success but it is no longer being supported or working in MacOS Monterey. I used the principles from his scripting and tried to expand upon it to create my current project. My project also utilizes his Launchd Package Creator Tool, which still works great. Thanks!

[busdjamf]

This is great! Thank you! I just started running into this issue on Monterey.

[mosermat]

Hey @busdjamf you're welcome! I'm not sure if you tried to run with this yet but I just realized I made a mistake and previously uploaded the wrong "BuildtheDock.sh" to github. I fixed it updated the readme a few minutes ago so you should be good to go now. If you run into any issues let me know!

[busdjamf]

Hi @mosermat - I seem to be good. I don't think I downloaded and started using it until after you had already posted the updates. So far I haven't had any problems after hundreds of deployments on both Big Sur and Monterey. It works great and is easy to set up and customize. It still works great on the latest versions (11.7 and 12.6).

Thanks again for creating such a handy tool!

[mosermat]

Nice! Thanks for the feedback and I'm glad it's working for you!

[MacPapi]

Thank you so much for this.

I had been wanting to fix my broken Dockutil script for a long time so I appreciate you sharing this with all of us.

Here are a couple of notes that might help others deploying to systems with macOS Ventura.

System Preferences is now System Settings and the path to Safari has changed slightly.

*see below

#################################################################################
# The following are small tweaks to the script for laptops with macOS 13(Ventura) installed 
#################################################################################

#################################################################################
# For Safari, use the following path for Safari instead of the usual or you 
# will end up with a Safari icon that contains a small shortcut icon overlayed 
# on top of the Safari icon in the dock :) 
# Shout out to @Robban in the macadmins Slack for this fix.
#################################################################################

$DOCKUTIL_BINARY --add '/System/Cryptexes/App/System/Applications/Safari.app' --allhomes --no-restart

#################################################################################
# System Preferences is now called System Settings
# If you want to add it to the dock, use the following path for System settings:
#################################################################################

$DOCKUTIL_BINARY --add '/System/Applications/System Settings.app' --allhomes --no-restart

[j0nathan_r0gers]

How would you do an "IF Ventura // Else ..."?

MacOSMajorVersion=$(sw_vers -productVersion | cut -d '.' -f 1)
MacOSMinorVersion=$(sw_vers -productVersion | cut -d '.' -f 2)
MacOSPatchVersion=$(sw_vers -productVersion | cut -d '.' -f 3)

if [[ $MacOSMajorVersion -eq 13 && $MacOSMinorVersion -lt 0 ]]; then
$DOCKUTIL_BINARY --add '/System/Applications/System Settings.app' --allhomes --no-restart

else

$DOCKUTIL_BINARY --add '/System/Applications/System Preferences.app' --allhomes --no-restart

fi

[MacPapi]

That's one way, but I read somewhere (and I forget now where but will try and get link later) that using the build number is much better.

Current build number for Ventura is 22 (from the full build number, 22C65, for macOS Ventura 13.1)

Here's the if/else statement I used:

#######################################################################################
BuildVersion=$(sw_vers -buildVersion | cut -c1-2)

if [[ $BuildVersion -ge 22 ]]; then
        echo "OS Version is macOS Ventura 13.0 or newer, proceeding... Installing macOS Ventura version of Dock"
        # add the default items for all Ventura+ macs
    else 
        echo "OS Version is macOS Monterey 12.6 or older... Installing macOS default version of Dock"   
        # add the default dock items for all the rest        
fi
#######################################################################################

[kwoodard]

I have this setup to run "ongoing" as its a lab. I keep getting the following error..

Script result: currentuser-variable = (username)
Finished unloading launchagent Load failed: 5: Input/output error Try running `launchctl bootstrap` as root for richer errors. Finished loading launchagent

Seems to be on every Active Directory user, and on random local users. Any thoughts?

[mosermat]

Hey @kwoodard 

That error is coming from this script: BuildtheDock_ReLoad LaunchAgent.sh  on line 15 where it's trying to load the launch agent but gets an input/output error, probably because it can't find the LaunchAgent (plist file). For that file to exist you would have needed to create it via steps 9-17 in the GitHub directions. You can verify it exists or not by looking for it here:  "/Library/LaunchAgents/com.matt.buildadock.plist"

[kwoodard]

The file is there. What I did that is slightly different than your steps is I broke up the installation portion with the login part on a second policy. I did that so I wasn't constantly installing Docutil and the two other packages.

[Sven_S]

Hey @mosermat, 
I'm experiencing the same error as @kwoodard. I've also check the existence of the LaunchAgent "/Library/LaunchAgents/com.matt.buildadock.plist" which is present. 
I only use BuildTheDock once per Computer as recurring Check-In and named the policy "zBuild Bustom Dock" which results in it being the last policy run after enrolling computers. We have local accounts and use Jamf Connect - no Active Directory users like @kwoodard.

I check the logs and last time it worked was on 30.12.2022. All clients enrolled this year failed with the same error.

This is the log with the error in section 19:

1. Executing Policy zBuild Custom Dock
2. Downloading buildadockagent2.pkg...
3. Downloading https://euc1-jcds.services.jamfcloud.com//download*address/*/buildadockagent2.pkg?token=**token**…
4. Verifying package integrity...
5. Installing buildadockagent2.pkg...
6. Successfully installed buildadockagent2.pkg.
7. Downloading BuildtheDock2.sh.pkg...
8. Downloading https://euc1-jcds.services.jamfcloud.com//download*address**/*/BuildtheDock2.sh.pkg?token=**token**…
9. Verifying package integrity...
10. Installing BuildtheDock2.sh.pkg...
11. Successfully installed BuildtheDock2.sh.pkg.
12. Downloading dockutil-3.0.2.pkg...
13. Downloading https://euc1-jcds.services.jamfcloud.com//download/**address**/*/dockutil-3.0.2.pkg?token=**token**…
14. Verifying package integrity...
15. Installing dockutil-3.0.2.pkg...
16. Successfully installed dockutil-3.0.2.pkg.
17. Running script BuildtheDock_ReLoad LaunchAgent.sh...
18. Script exit code: 0
19. Script result: currentuser-variable = ***username***
    Finished unloading launchagent
    Load failed: 5: Input/output error
    Try running `launchctl bootstrap` as root for richer errors.
    Finished loading launchagent
20. Running Recon...
21. Retrieving inventory preferences from https://***tenant-name***.jamfcloud.com/…
22. Locating accounts...
23. Searching path: /System/Applications
24. Locating package receipts...
25. Locating software updates...
26. Locating plugins...
27. Locating printers...
28. Searching path: /Applications
29. Locating hardware information (macOS 12.6.2)...

Regarding to the Readme https://github.com/bluemoosegoose/Build-a-Custom-MacOS-Dock the last two steps are not successfull:

1. Watch dockutil binary get installed here: /usr/local/bin/dockutil
2. Watch the "BuildtheDock.sh" file get installed here: /Library/Scripts/BuildtheDock.sh
3. Watch the .plist file get installed here: /Library/LaunchAgents/com.matt.buildadock.plist
4. Watch dockscrap.txt file get installed here : /Users/$currentuser/dockscrap.txt
5. Check the log at: /Users/$currentuser/docklog.txt
   

I think i will start with rebuilding LauchAgent.

Update:
Rebuilding the LaunchAgent didn't fix it. But restarting the client before running the policy helped. I only use the policy after enrollment once. When I deactivated the Policy, did a restart after an enrollment and activated the policy again afterwards it worked without any problems.
Now I still need to figure out what is causing this issue. I'm open for suggestions.