dock
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
- Example Playbook
- Development
- Testing
- 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 bydockutil
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 usewayofdev.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
:warning: 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
Role is used to automate use of "dockutil" โ command line tool for managing dock items. You can add, remove and re-arrange Dock items.
ansible-galaxy install wayofdev/ansible-role-dock