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]

Do you have an example script on how this would look? I would love to only have one script for dock's, instead of two that are dependent on whichever smart group the computer is...depending on which macOS they are using.

[San_Kay]

Where would you place this part in the script plus the suggestion bellow with the build number of macOS? Thanks!

[mosermat]

I just recently ran through my guide doing this buildout from scratch in a new environment and can confirm all is working on Ventura 13.4.1 (C). I updated the "BuildtheDock.sh" on github to reflect the Ventura path locations as you called out here. I didn't go so far as to add the scripts below for multiple OS versions since I haven't tested them but I appreciate that work. Thanks for the collaboration!

[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.

[stavo707]

Did you ever find a solution to this? Running into the same error/issue. It runs post enrollment but the dock doesn't change ever after log out or restart.

[mosermat]

Hey @stavo707,

@Sven_S mentioned getting this Script result: currentuser-variable = ***username*** on line 19 of the log he posted above, within "BuildtheDock_ReLoad LaunchAgent.sh". The expected result here should be the logged-in user's actual username, not "***username***" which is also why the endnotes steps 4 and 5 don't work (it can't find the real username directory).

Can you test and let me know if you're sure the policy is being triggered while the user is logged on?

Something else to try: on your Mac open Terminal and run this command, which will print the logged-in user: 

(/bin/ls -la /dev/console | /usr/bin/cut -d ' ' -f 4)

[stavo707]

Hey @mosermat 

So I have the trigger set to enrollment (for new machines). When the user gets to the desktop after signing in, all the policies start to run and when the dock policy runs it gives the same error that @Sven_S gets. 

[Sven_S]

Hey mosermat,

I've obfuscated the logged-in user's actual username. It could've said: Script result: currentuser-variable = doe.jane

[Sven_S]

Hi stavo707,

I'm using "Setup-Your-Mac" from Dan Snelson and run Build-Custom-Dock als a policy with a custom trigger from within that setup routine. I didn't work on the issue any longer because running the policy with a custom trigger and no after enrollment fixed it for me.

[tdenton]

@mosermat 

I have this working but the dock doesnt get built for a user when they login only the second time they login. Any idea?

[kwoodard]

I have two policies in Jamf. 1 installs everything on startup. 2 runs the script at "once per user" login. Seems to work on the first boot after initial setup.

[tdenton]

Also is there way to set the dock back to default should this be required.

[kwoodard]

Delete all the associated files on the end-point, including the plist that either you created or the script above created that tells the LaunchAgent if it needs to run or not. Reboot and profit.

[MPHEGGELO]

Works if the DockUtility is installed prior

[TS6845]

what about this approach... using the application and custom settings config... 
copy all this into it https://github.com/Jamf-Custom-Profile-Schemas/ProfileManifestsMirror/blob/main/manifests/ManifestsA...

Applications and Custom Settings option > External Applications > +Add and choose Custom Schema as the Source.Then enter the Profile Domain from the Title attribute text in this case, com.apple.dock and select + Add Schema. Now paste in the raw content of the JSON template, select Upload on the bottom left then Save on the bottom right.

i cannot take credit.. i found a google shared doc

https://docs.google.com/document/d/13Lvl5ffqKGsBkIfUq4IEopZhGO3AKUtPTiU2Xsf4Uqg/edit