{"id":21664390,"url":"https://github.com/wayofdev/ansible-role-dock","last_synced_at":"2025-04-12T00:16:22.194Z","repository":{"id":37018657,"uuid":"488268531","full_name":"wayofdev/ansible-role-dock","owner":"wayofdev","description":"Role is used to automate use of dockutil – command line tool for managing dock items. You can add, remove and re-arrange Dock items.","archived":false,"fork":false,"pushed_at":"2023-09-04T19:03:26.000Z","size":353,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T00:16:14.601Z","etag":null,"topics":["ansible","ansible-role","automation","dock","dockutil","mac","macos","mdm","provisioning"],"latest_commit_sha":null,"homepage":"https://wayof.dev","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wayofdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"wayofdev"}},"created_at":"2022-05-03T15:41:44.000Z","updated_at":"2023-12-16T20:02:16.000Z","dependencies_parsed_at":"2024-11-25T10:38:27.360Z","dependency_job_id":null,"html_url":"https://github.com/wayofdev/ansible-role-dock","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayofdev%2Fansible-role-dock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayofdev%2Fansible-role-dock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayofdev%2Fansible-role-dock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayofdev%2Fansible-role-dock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wayofdev","download_url":"https://codeload.github.com/wayofdev/ansible-role-dock/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248497818,"owners_count":21113984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-role","automation","dock","dockutil","mac","macos","mdm","provisioning"],"created_at":"2024-11-25T10:37:22.939Z","updated_at":"2025-04-12T00:16:22.147Z","avatar_url":"https://github.com/wayofdev.png","language":"Makefile","funding_links":["https://github.com/sponsors/wayofdev"],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg width=\"456\" src=\"https://raw.githubusercontent.com/wayofdev/ansible-role-dock/master/assets/logo.gh-light-mode-only.png#gh-light-mode-only\"\u003e\n\u003cimg width=\"456\" src=\"https://raw.githubusercontent.com/wayofdev/ansible-role-dock/master/assets/logo.gh-dark-mode-only.png#gh-dark-mode-only\"\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://actions-badge.atrox.dev/wayofdev/ansible-role-dock/goto\"\u003e\u003cimg alt=\"Build Status\" src=\"https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fwayofdev%2Fansible-role-dock%2Fbadge\u0026style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://galaxy.ansible.com/wayofdev/dock\"\u003e\u003cimg alt=\"Ansible Role\" src=\"https://img.shields.io/ansible/role/59499?style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/wayofdev/ansible-role-dock/tags\"\u003e\u003cimg src=\"https://img.shields.io/github/v/tag/wayofdev/ansible-role-dock?sort=semver\u0026style=flat-square\" alt=\"Latest Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://galaxy.ansible.com/wayofdev/dock\"\u003e\u003cimg alt=\"Ansible Quality Score\" src=\"https://img.shields.io/ansible/quality/59499?style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://galaxy.ansible.com/wayofdev/dock\"\u003e\u003cimg alt=\"Ansible Role\" src=\"https://img.shields.io/ansible/role/d/59499?style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/wayofdev/ansible-role-dock.svg?style=flat-square\u0026color=blue\" alt=\"Software License\"/\u003e\u003c/a\u003e\n\u003ca href=\"#\"\u003e\u003cimg alt=\"Commits since latest release\" src=\"https://img.shields.io/github/commits-since/wayofdev/ansible-role-dock/latest?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n# Ansible Role: macOS Dock Automation\n\nRole is used to automate use of [dockutil](https://github.com/kcrawford/dockutil) – command line tool for managing Dock items. You can add, remove and re-arrange Dock items.\n\nIf you **like/use** this role, please consider **starring** it. Thanks!\n\n\u003cbr\u003e\n\n## 🗂 Table of contents\n\n* [Benefits of this role](#-benefits-of-this-role)\n* [Requirements](#-requirements)\n* [Role Variables](#-role-variables)\n  * [Structure](#-structure)\n  * [Adding](#-adding)\n  * [Adding with Replace](#-adding-with-replace)\n  * [Adding folders](#-adding-folders)\n  * [Removing](#-removing)\n  * [Moving](#-moving)\n* [Example Playbook](#-example-playbook)\n* [Development](#-development)\n* [Testing](#-testing)\n  * [on localhost](#-on-localhost)\n  * [over SSH](#-over-ssh)\n* [Dependencies](#-dependencies)\n* [Compatibility](#-compatibility)\n* [License](#-license)\n* [Author Information](#-author-information)\n* [Credits and Resources](#-credits-and-resources)\n* [Contributors](#-contributors)\n* [Sponsors](#-sponsors)\n\n\u003cbr\u003e\n\n## ⭐️ Benefits of this role:\n\n* This version supports latest 3.x [dockutil](https://github.com/kcrawford/dockutil)\n* Items are added, positioned and removed in single command run instead of loops\n* Latest macOS Monterey support\n* Can erase all items contained in Dock with one setting\n* No need for ansible handlers and sudo rights to do `killall` to restart Dock, as it is handled by `dockutil` by itself!\n* Supports all `dockutil` options, like:\n`--add, --remove, --move, --replacing, --position, --after, --before, --section, --allhomes, --sort, --display, --view`\n\n\u003cbr\u003e\n\n## 📑 Requirements\n\n  - **Homebrew**: Requires `homebrew` already installed (you can use `wayofdev.homebrew` to install it on your macOS).\n  - 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).\n- Compatible OS. See [compatibility](#-compatibility) table.\n- Role has dependencies on third-party roles on different operating systems. See `requirements.yml` and [dependencies](#-dependencies) section.\n\n\u003cbr\u003e\n\n## 🔧 Role Variables\n\nSection 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`):\n\n\u003cbr\u003e\n\n### → Structure\n\nGroup controls installation of dockutil, and allows to select custom tap:\n\n```yaml\n# Should we try to install dockutil?\ndock_dockutil_install: \u003ctrue | false\u003e # (default: true) Install dockutil using homebrew.\n\n# Path to custom or official tap of dockutil\ndock_dockutil_tap: lotyp/formulae/dockutil # By default, 3.x tap is used\n```\n\nRole allows to wipe macOS dock completely:\n\n```yaml\n# Removes all contents from dock including \"others\" section with Downloads folder.\n# Prefer this option on new installations together with configured \"dockitems\".\ndock_dockitems_erase_all: \u003ctrue | false\u003e # Whether to attempt to erase all items in Dock including Downloads folder! (default: false)\n```\n\nVariable structure to add, move, or remove items in Dock:\n\n```yaml\ndock_dockitems:\n  - label: \u003clabel\u003e # Used in search for existing items or names new apps\"\n    action: \u003cadd | remove | move\u003e\n    path: \u003clabel | app bundle id | path | url\u003e # Example: /System/Applications/TextEdit.app\n    replacing: \u003clabel | app bundle id | path | url\u003e # 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\"\n    position: \u003c[+/-]index_number | beginning | end | middle\u003e # Inserts the item at a fixed position: can be position by index number or keyword\"\n    after: \u003clabel | application bundle id\u003e # Inserts the item immediately after the given dock label or at the end if the item is not found\n    before: \u003clabel | application bundle id\u003e # Inserts the item immediately before the given dock label or at the end if the item is not found\n    section: \u003capps | others\u003e # Specifies whether the item should be added to the apps or others section\n    display: \u003cfolder | stack\u003e # Folder display option when adding a folder\n    sort: \u003cname | dateadded | datemodified | datecreated | kind\u003e # Folder sort option when adding a folder\n    type: \u003cspacer | small-spacer | flex-spacer\u003e # Specify a custom tile type for adding spacers\n    allhomes: \u003ctrue | false\u003e # Whether to attempt to locate all home directories and perform the operation on each of them (default: false)\n```\n\n\u003cbr\u003e\n\n### → Adding\n\n**Adds** `TextEdit.app` to the end of the current user's Dock:\n\n```yaml\ndock_dockitems:\n  - label: TextEdit\n    action: add\n    path: /System/Applications/TextEdit.app\n```\n\n**Adds** `Time Machine.app` in the middle of Dock:\n\n```yaml\ndock_dockitems:\n  - label: Time Machine\n    action: add\n    path: /System/Applications/Time Machine.app\n    position: middle\n```\n\n**Adds** `TextEdit.app` after the item `Time Machine.app` in every user's Dock on that machine:\n\n```yaml\ndock_dockitems:\n  - label: TextEdit\n    action: add\n    path: /System/Applications/TextEdit.app\n    after: Time Machine\n    allhomes: true # optional parameter\n```\n\n\u003cbr\u003e\n\n### → Adding with Replace\n\n**Replaces** `Time Machine.app` with `Mail.app` in the current user's Dock\n\n```yaml\ndock_dockitems:\n  - label: Mail\n    action: add\n    path: /System/Applications/Mail.app\n    replacing: Time Machine\n```\n\n\u003cbr\u003e\n\n### → Adding folders\n\n**Adds** `Downloads` folder to `others` section of Dock menu. On click will open preview in grid mode.\n\n```yaml\ndock_dockitems:\n  - label: Downloads\n    action: add\n    path: ~/Downloads\n    view: grid\n    display: folder\n    allhomes: true # optional parameter\n```\n\n\u003cbr\u003e\n\n### → Removing\n\n**Removes** `TextEdit` in every user's Dock on that machine:\n\n```yaml\ndock_dockitems:\n  - label: TextEdit\n    action: remove\n    allhomes: true # optional parameter\n```\n\n**Removes** all spacer tiles:\n\n```yaml\ndock_dockitems:\n  - label: spacer-tiles\n    action: remove\n```\n\n\u003cbr\u003e\n\n### → Moving\n\n**Moves** `System Preferences` to the second slot on every user's dock on that machine:\n\n```yaml\ndock_dockitems:\n  - label: System Preferences\n    action: move\n    position: end # \u003c[+/-]index_number | beginning | end | middle\u003e\n    allhomes: true # optional parameter\n```\n\n\u003cbr\u003e\n\n## 📗 Example Playbook\n\n```yaml\n---\n- hosts: all\n\n  # is needed when running over SSH\n  environment:\n    - PATH: \"/usr/local/bin:/usr/local/sbin:/opt/homebrew/bin:{{ ansible_env.PATH }}\"\n\n  vars:\n    dock_dockitems_erase_all: true\n    dock_dockitems:\n      - label: Messages\n        action: add\n        path: /System/Applications/Messages.app\n\n      - label: Safari\n        action: add\n        path: /Applications/Safari.app\n\n      - label: Sublime Text\n        action: add\n        path: /Applications/Sublime Text.app\n        position: 3\n\n  roles:\n    - wayofdev.homebrew\n    - wayofdev.dock\n```\n\n\u003cbr\u003e\n\n## ⚙️ Development\n\nTo install dependencies and start development you can check contents of our `Makefile`\n\n**Install** [poetry](https://github.com/python-poetry/poetry) using [poetry-bin](https://github.com/gi0baro/poetry-bin) and all dev python dependencies:\n\n```bash\n$ make install\n```\n\n**Install** only python dependencies, assuming that you already have poetry:\n\n```bash\n$ make install-deps\n```\n\n**Install** all git hooks:\n\n```bash\n$ make hooks\n```\n\n**Lint** all role files:\n\n```bash\n$ make lint\n```\n\n\u003cbr\u003e\n\n## 🧪 Testing\n\nYou 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:\n\n### → on localhost\n\n\u003e :warning: **Notice**: By defaut all tests are running against your local machine!\n\n```bash\n# run molecule tests on localhost\n$ poetry run molecule test --scenario-name defaults-restored-on-localhost -- -vvv\n\n# or with make command\n$ make m-local\n\n# choose which tags will be included\n$ export TASK_TAGS=\"dock-validate,dock-install\"; make m-local\n```\n\n\u003cbr\u003e\n\n### → over SSH\n\n```bash\n# run molecule scenarios against remote machines over SSH\n# this will need VM setup and configuration\n$ poetry run molecule test --scenario-name defaults-restored-over-ssh -- -vvv\n\n$ make m-remote\n\n# tags also can be passed\n$ export TASK_TAGS=\"dock-validate,dock-install\"\n$ make m-remote\n```\n\n\u003cbr\u003e\n\n## 📦 Dependencies\n\nInstallation handled by `Makefile` and requirements are defined in `requirements.yml`\n\n  - [wayofdev.homebrew](https://github.com/wayofdev/ansible-role-homebrew) - soft dependency, required if Homebrew isn't installed yet\n  - [ansible.community.general](https://docs.ansible.com/ansible/latest/collections/community/general/index.html)\n\n\u003cbr\u003e\n\n## 🧩 Compatibility\n\nThis role has been tested on these systems:\n\n| system / container | tag      |\n| :----------------- | -------- |\n| macos              | monterey |\n| macos              | big-sur  |\n\n\u003cbr\u003e\n\n## 🤝 License\n\n[![Licence](https://img.shields.io/github/license/wayofdev/ansible-role-dock?style=for-the-badge\u0026color=blue)](./LICENSE)\n\n\u003cbr\u003e\n\n## 🙆🏼‍♂️ Author Information\n\nThis role was created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev).\n\n\u003cbr\u003e\n\n## 🧱 Credits and Resources\n\n**Inspired by:**\n\n* original role created by [@geerlingguy](https://github.com/geerlingguy) as a part of [ansible-collection-mac](https://github.com/geerlingguy/ansible-collection-mac).\n* [dockutil](https://github.com/kcrawford/dockutil)\n\n\u003cbr\u003e\n\n## 🫡 Contributors\n\n\u003cimg align=\"left\" src=\"https://img.shields.io/github/contributors-anon/wayofdev/ansible-role-dock?style=for-the-badge\"/\u003e\n\n\u003ca href=\"https://github.com/wayofdev/ansible-role-dock/graphs/contributors\"\u003e\n  \u003cimg src=\"https://opencollective.com/wod/contributors.svg?width=890\u0026button=false\"\u003e\n\u003c/a\u003e\n\n\u003cbr\u003e\n\n## 🤑 Sponsors\n\nRole development and testing was done on [Parallels Desktop Pro Edition](https://www.parallels.com/products/desktop/pro/), thanks to [Parallels](https://www.parallels.com/eu/)\n\n\u003cdiv\u003e\n\u003ca href=\"https://www.parallels.com/products/desktop/pro/\"\u003e\n\u003cimg width=\"180\" src=\"assets/pr-full-color-on-white.jpeg#gh-light-mode-only\"\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayofdev%2Fansible-role-dock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwayofdev%2Fansible-role-dock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayofdev%2Fansible-role-dock/lists"}