Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wayofdev/ansible-role-dock

Role is used to automate use of dockutil – command line tool for managing dock items. You can add, remove and re-arrange Dock items.
https://github.com/wayofdev/ansible-role-dock

ansible ansible-role automation dock dockutil mac macos mdm provisioning

Last synced: about 2 months ago
JSON representation

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

Awesome Lists containing this project

README 

        























Build Status

Ansible Role

Latest Version

Ansible Quality Score

Ansible Role

Software License

Commits since latest release








# Ansible Role: macOS Dock Automation



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



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







## 🗂 Table of contents



* [Benefits of this role](#-benefits-of-this-role)

* [Requirements](#-requirements)

* [Role Variables](#-role-variables)

  * [Structure](#-structure)

  * [Adding](#-adding)

  * [Adding with Replace](#-adding-with-replace)

  * [Adding folders](#-adding-folders)

  * [Removing](#-removing)

  * [Moving](#-moving)

* [Example Playbook](#-example-playbook)

* [Development](#-development)

* [Testing](#-testing)

  * [on localhost](#-on-localhost)

  * [over SSH](#-over-ssh)

* [Dependencies](#-dependencies)

* [Compatibility](#-compatibility)

* [License](#-license)

* [Author Information](#-author-information)

* [Credits and Resources](#-credits-and-resources)

* [Contributors](#-contributors)

* [Sponsors](#-sponsors)







## ⭐️ Benefits of this role:



* This version supports latest 3.x [dockutil](https://github.com/kcrawford/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](#-compatibility) table.

- Role has dependencies on third-party roles on different operating systems. See `requirements.yml` and [dependencies](#-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:



```yaml

# Should we try to install dockutil?

dock_dockutil_install:  # (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:



```yaml

# 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:  # Whether to attempt to erase all items in Dock including Downloads folder! (default: false)

```



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



```yaml

dock_dockitems:

  - label:  # Used in search for existing items or names new apps"

    action: 

    path:  # Example: /System/Applications/TextEdit.app

    replacing:  # 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:  # Inserts the item immediately after the given dock label or at the end if the item is not found

    before:  # Inserts the item immediately before the given dock label or at the end if the item is not found

    section:  # Specifies whether the item should be added to the apps or others section

    display:  # Folder display option when adding a folder

    sort:  # Folder sort option when adding a folder

    type:  # Specify a custom tile type for adding spacers

    allhomes:  # 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:



```yaml

dock_dockitems:

  - label: TextEdit

    action: add

    path: /System/Applications/TextEdit.app

```



**Adds** `Time Machine.app` in the middle of Dock:



```yaml

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:



```yaml

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



```yaml

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.



```yaml

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:



```yaml

dock_dockitems:

  - label: TextEdit

    action: remove

    allhomes: true # optional parameter

```



**Removes** all spacer tiles:



```yaml

dock_dockitems:

  - label: spacer-tiles

    action: remove

```







### → Moving



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



```yaml

dock_dockitems:

  - label: System Preferences

    action: move

    position: end # <[+/-]index_number | beginning | end | middle>

    allhomes: true # optional parameter

```







## 📗 Example Playbook



```yaml

---

- 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](https://github.com/python-poetry/poetry) using [poetry-bin](https://github.com/gi0baro/poetry-bin) and all dev python dependencies:



```bash

$ make install

```



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



```bash

$ make install-deps

```



**Install** all git hooks:



```bash

$ make hooks

```



**Lint** all role files:



```bash

$ 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!



```bash

# 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



```bash

# 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](https://github.com/wayofdev/ansible-role-homebrew) - soft dependency, required if Homebrew isn't installed yet

  - [ansible.community.general](https://docs.ansible.com/ansible/latest/collections/community/general/index.html)







## 🧩 Compatibility



This role has been tested on these systems:



| system / container | tag      |

| :----------------- | -------- |

| macos              | monterey |

| macos              | big-sur  |







## 🤝 License



[![Licence](https://img.shields.io/github/license/wayofdev/ansible-role-dock?style=for-the-badge&color=blue)](./LICENSE)







## 🙆🏼‍♂️ Author Information



This role was created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev).







## 🧱 Credits and Resources



**Inspired by:**



* original role created by [@geerlingguy](https://github.com/geerlingguy) as a part of [ansible-collection-mac](https://github.com/geerlingguy/ansible-collection-mac).

* [dockutil](https://github.com/kcrawford/dockutil)







## 🫡 Contributors








  








## 🤑 Sponsors



Role 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/)