ryangball/dockbuilder

A LaunchAgent and .app to build a user's Dock upon login and/or on demand.

DockBuilder

A LaunchAgent and .app to build a user's Dock upon login and/or on demand.

DockBuilder allows for the building of a user's Dock based on an organization's needs. DockBuilder eliminates the need for a user template which only allows for a static Dock for all users, and template manipulation can cause issues in newer versions of macOS. DockBuilder not only allows for easy creation of a new user's Dock out of the box, but also has the potential to dynamically set up a different Dock for users based on some criteria; like AD groups for example (you'd have to modify the source based on your criteria).

Features

• Builds a Dock based on pre-defined defaults
• Includes a framework for building unique Docks for certain users based on some criteria (including an example)
• Logs to ~/Library/Logs/DockBuilder.log (by default)
• Does not start until the Dock.app is loaded upon login
• Only builds a Dock for user's who's Dock is younger than 300 seconds (to minimize re-building a pre-existing user's Dock after the installation of DockBuilder)
• Option to hide the Dock and display a message to the user while the Dock is being built

Requirements for Building

• Platypus: A developer tool that creates native Mac applications from command line scripts such as shell scripts or Python, Perl, Ruby, Tcl, JavaScript and PHP programs.
  • You must install the command line tool associated with Platypus. Open Platypus, in the Menu Bar choose "Platypus" > "Preferences" and click the "Install" button to install the Platypus command line tool.
• jamfHelper: jamfHelper is used to display the message when the Dock is being built (if you choose to use that feature). CocoaDialog could also be leveraged pretty easily for environments without Jamf Pro. AppleScript could also be used, but you can't create an AppleScript dialog void of buttons.

Note: Dockutil is also required, but included in the resulting .pkg and releases.

Build Project

To build new versions you can simply run the build.sh script and specify a version number for both the .app and .pkg. The resulting .pkg will include the LaunchAgent and .app as well as necessary preinstall/postinstall scripts. If you do not include a version number as a parameter then version 1.0 will be assigned as the default.

# Clone the repo and traverse into the created directory
git clone https://github.com/ryangball/DockBuilder.git
cd DockBuilder

# At this point you'd customize the variables in the build.sh script

# Build the .pkg
./build.sh 1.5

Customize DockBuilder

Within the build.sh script, you can modify the top-most variables to create a custom DockBuilder .app and .pkg.

Some things to keep in mind:

1. Within both the breadcrumb and log variables, you'll notice the $HOME environmental variable. You should leave this in there as both should be in the user's home folder.
2. Within the defaultItemsToAdd array (and alternateItemsToAdd_1 if you use it), you need to follow the same pattern that I used in the example. When specifying view options for the persistent-others Dock items, you need to separate the Dock item and options with a comma (",") as per the example.
3. After modifying the variables in build.sh, please test for full functionality before deploying.
4. If you want to set up a unique Dock for certain users you must populate the alternateItemsToAdd_1 ion build.sh and modify this logic in dockbuilder.sh) to include the users or criteria to build the alternate Dock.
5. If you want to exclude specific existing users from the initial breadcrumb creation so that they will get a new Dock created, you must populate the skipInitialBreadcrumbUsers variable in build.sh.

Testing

To test DockBuilder, install the .pkg, then unload/load/start the LaunchAgent.

# Delete the breadcrumb for the user if it exists
find ~/Library/Preferences -name com.github.ryangball.dockbuilder.breadcrumb.plist -delete

# Unload the LaunchAgent
launchctl unload /Library/LaunchAgents/com.github.ryangball.dockbuilder.plist

# Load the LaunchAgent
launchctl load /Library/LaunchAgents/com.github.ryangball.dockbuilder.plist

# Start the LaunchAgent (if necessary)
launchctl start com.github.ryangball.dockbuilder

# Tail the log to see what is occurring
tail -f ~/Library/Logs/DockBuilder.log

Re-create a User's Dock

Upon DockBuilder's execution, a breadcrumb is placed into the user's home folder by default: ~/Library/Preferences/com.github.ryangball.dockbuilder.breadcrumb.plist

In the event that this breadcrumb exists for a user, DockBuilder will exit without any action. To re-create a user's Dock, open terminal as the user and run the following to remove the breadcrumb:

rm ~/Library/Preferences/com.github.ryangball.dockbuilder.breadcrumb.plist

Then you can simply run the /Applications/Utilities/DockBuilder.app or unload/load the LaunchAgent as per the Testing section above.

Dockutil

Dockutil is included in the resulting .pkg and is licensed under the Apache 2.0 license. Dockutil is automatically downloaded from the releases section when using the build.sh script, or included if you download one of the DockBuilder Releases.

dockbuilder's Issues

Allow different Dock items for a specific user

Allow for building a different Dock for a specific user.

Source

Initialise the Dock on 1st run

Hello!
I am deploying the package via JAFM Pro and I would like, if possible, as soon as DockBuilder is installed and runs, the Dock is modified as well for the currently logged in user.
Right now after JAMF installs the DockBuilder.pkg, nothing happens to the user's Dock.
I have to remove the breadcrumb, restart the machine and only then the Dock is modified.

Thank you for your time and consideration.

Kind Regards
Remus

Add a Loop for Mojave and Catalina

Hello Since Catalina moved System Preferences to /system, can you please add a loop to check if its 10.14 or below to add System Preferences from Applications otherwise add it from /system/Applications.

Thanks

Breadcrumbs not working in macOS Catalina

After building a DockBuilder package and installing it on a system running 10.15.1, DockBuilder doesn't create a breadcrumb file or log in the user profile -- thus it runs every time a user logs in and rebuilds their Dock. Changing $HOME/ in the build script to ~/ doesn't seem to make a difference.

Dock Tiles for Apple Apps not populating 10.15.2

After building a package and confirming the layest version of dockutil was included, I installed through JAMF and DockBuilder ran as expected. However, none of the Apple app icons populate. I've confirmed this in a VM running 10.15.2 as well as a freshly installed 10.15.2 OS on a 16" MBP. I've tested with a local user and a mobile managed user. The issue persists.

The same .pkg behaves correctly under macOS 10.14.6

Apple Silicon support?

I've been successfully using DockBuilder on M1-powered machines under Big Sur, provided that Rosetta is installed. It appears that Monterey now displays a dialog box when DockBuilder runs and warns that its type of application will be deprecated in a future macOS release. Accepting the dialog proceeds to allow DockBuilder to run successfully, but long-term, native Apple Silicon support will be necessary (and short term, I need to find a way to prevent that dialog box from appearing if possible).

EDIT: Digging a bit deeper the OS warning might actually be about Python, not application architecture. From what I understand Apple is deprecating built-in Python and directing developers who use it to include it in their projects directly.

Exclude users from postinstall breadcrumb creation.

Create mechanism to ignore users from the postinstall check that creates breadcrumbs for users who already existed.

Source

Dock Orientation

How to change dock orientation. Always show up on left