Ansible Role: macOS Dock Automation

Role is used to automate use of dockutil – command line tool for managing Dock items. You can add, remove and re-arrange Dock items.

If you like/use this role, please consider starring it. Thanks!

🗂 Table of contents

• Benefits of this role
• Requirements
• Role Variables
  • Structure
  • Adding
  • Adding with Replace
  • Adding folders
  • Removing
  • Moving
• Example Playbook
• Development
• Testing
  • on localhost
  • over SSH
• Dependencies
• Compatibility
• License
• Author Information
• Credits and Resources
• Contributors
• Sponsors

⭐️ Benefits of this role:

• This version supports latest 3.x dockutil
• Items are added, positioned and removed in single command run instead of loops
• Latest macOS Monterey support
• Can erase all items contained in Dock with one setting
• No need for ansible handlers and sudo rights to do killall to restart Dock, as it is handled by dockutil by itself!
• Supports all dockutil options, like: --add, --remove, --move, --replacing, --position, --after, --before, --section, --allhomes, --sort, --display, --view

📑 Requirements

• Homebrew: Requires homebrew already installed (you can use wayofdev.homebrew to install it on your macOS).
• Up-to-date version of ansible. During maintenance/development, we stick to ansible versions and will use new features if they are available (and update meta/main.yml for the minimum version).
• Compatible OS. See compatibility table.
• Role has dependencies on third-party roles on different operating systems. See requirements.yml and dependencies section.

🔧 Role Variables

Section shows all possible variants of adding, moving, replacing and removing of applications, spacers, folders. Available variables are listed below, along with example values (see defaults/main.yml):

→ Structure

Group controls installation of dockutil, and allows to select custom tap:

# Should we try to install dockutil?
dock_dockutil_install: <true | false> # (default: true) Install dockutil using homebrew.

# Path to custom or official tap of dockutil
dock_dockutil_tap: lotyp/formulae/dockutil # By default, 3.x tap is used

Role allows to wipe macOS dock completely:

# Removes all contents from dock including "others" section with Downloads folder.
# Prefer this option on new installations together with configured "dockitems".
dock_dockitems_erase_all: <true | false> # Whether to attempt to erase all items in Dock including Downloads folder! (default: false)

Variable structure to add, move, or remove items in Dock:

dock_dockitems:
  - label: <label> # Used in search for existing items or names new apps"
    action: <add | remove | move>
    path: <label | app bundle id | path | url> # Example: /System/Applications/TextEdit.app
    replacing: <label | app bundle id | path | url> # Label or app bundle id of item to replace. Replaces the item with the given dock label or adds the item to the end if item to replace is not found"
    position: <[+/-]index_number | beginning | end | middle> # Inserts the item at a fixed position: can be position by index number or keyword"
    after: <label | application bundle id> # Inserts the item immediately after the given dock label or at the end if the item is not found
    before: <label | application bundle id> # Inserts the item immediately before the given dock label or at the end if the item is not found
    section: <apps | others> # Specifies whether the item should be added to the apps or others section
    display: <folder | stack> # Folder display option when adding a folder
    sort: <name | dateadded | datemodified | datecreated | kind> # Folder sort option when adding a folder
    type: <spacer | small-spacer | flex-spacer> # Specify a custom tile type for adding spacers
    allhomes: <true | false> # Whether to attempt to locate all home directories and perform the operation on each of them (default: false)

→ Adding

Adds TextEdit.app to the end of the current user's Dock:

dock_dockitems:
  - label: TextEdit
    action: add
    path: /System/Applications/TextEdit.app

Adds Time Machine.app in the middle of Dock:

dock_dockitems:
  - label: Time Machine
    action: add
    path: /System/Applications/Time Machine.app
    position: middle

Adds TextEdit.app after the item Time Machine.app in every user's Dock on that machine:

dock_dockitems:
  - label: TextEdit
    action: add
    path: /System/Applications/TextEdit.app
    after: Time Machine
    allhomes: true # optional parameter

→ Adding with Replace

Replaces Time Machine.app with Mail.app in the current user's Dock

dock_dockitems:
  - label: Mail
    action: add
    path: /System/Applications/Mail.app
    replacing: Time Machine

→ Adding folders

Adds Downloads folder to others section of Dock menu. On click will open preview in grid mode.

dock_dockitems:
  - label: Downloads
    action: add
    path: ~/Downloads
    view: grid
    display: folder
    allhomes: true # optional parameter

→ Removing

Removes TextEdit in every user's Dock on that machine:

dock_dockitems:
  - label: TextEdit
    action: remove
    allhomes: true # optional parameter

Removes all spacer tiles:

dock_dockitems:
  - label: spacer-tiles
    action: remove

→ Moving

Moves System Preferences to the second slot on every user's dock on that machine:

dock_dockitems:
  - label: System Preferences
    action: move
    position: end # <[+/-]index_number | beginning | end | middle>
    allhomes: true # optional parameter

📗 Example Playbook

---
- hosts: all

  # is needed when running over SSH
  environment:
    - PATH: "/usr/local/bin:/usr/local/sbin:/opt/homebrew/bin:{{ ansible_env.PATH }}"

  vars:
    dock_dockitems_erase_all: true
    dock_dockitems:
      - label: Messages
        action: add
        path: /System/Applications/Messages.app

      - label: Safari
        action: add
        path: /Applications/Safari.app

      - label: Sublime Text
        action: add
        path: /Applications/Sublime Text.app
        position: 3

  roles:
    - wayofdev.homebrew
    - wayofdev.dock

⚙️ Development

To install dependencies and start development you can check contents of our Makefile

Install poetry using poetry-bin and all dev python dependencies:

$ make install

Install only python dependencies, assuming that you already have poetry:

$ make install-deps

Install all git hooks:

$ make hooks

Lint all role files:

$ make lint

🧪 Testing

You can check Makefile to get full list of commands for remote and local testing. For local testing you can use these comands to test whole role or separate tasks:

→ on localhost

⚠️ Notice: By defaut all tests are running against your local machine!

# run molecule tests on localhost
$ poetry run molecule test --scenario-name defaults-restored-on-localhost -- -vvv

# or with make command
$ make m-local

# choose which tags will be included
$ export TASK_TAGS="dock-validate,dock-install"; make m-local

→ over SSH

# run molecule scenarios against remote machines over SSH
# this will need VM setup and configuration
$ poetry run molecule test --scenario-name defaults-restored-over-ssh -- -vvv

$ make m-remote

# tags also can be passed
$ export TASK_TAGS="dock-validate,dock-install"
$ make m-remote

📦 Dependencies

Installation handled by Makefile and requirements are defined in requirements.yml

• wayofdev.homebrew - soft dependency, required if Homebrew isn't installed yet
• ansible.community.general

🧩 Compatibility

This role has been tested on these systems:

system / container	tag
macos	monterey
macos	big-sur

🤝 License

🙆🏼‍♂️ Author Information

This role was created in 2022 by lotyp / wayofdev.

🧱 Credits and Resources

Inspired by:

• original role created by @geerlingguy as a part of ansible-collection-mac.
• dockutil

🫡 Contributors

🤑 Sponsors

Role development and testing was done on Parallels Desktop Pro Edition, thanks to Parallels