{"id":13469056,"url":"https://github.com/geerlingguy/mac-dev-playbook","last_synced_at":"2025-05-12T20:48:23.050Z","repository":{"id":14070125,"uuid":"16773572","full_name":"geerlingguy/mac-dev-playbook","owner":"geerlingguy","description":"Mac setup and configuration via Ansible.","archived":false,"fork":false,"pushed_at":"2025-04-19T20:46:36.000Z","size":278,"stargazers_count":6404,"open_issues_count":8,"forks_count":1850,"subscribers_count":159,"default_branch":"master","last_synced_at":"2025-04-23T17:50:36.033Z","etag":null,"topics":["ansible","automation","developer","homebrew","mac","macos","playbook","setup"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geerlingguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null},"funding":{"github":"geerlingguy","patreon":"geerlingguy"}},"created_at":"2014-02-12T16:29:15.000Z","updated_at":"2025-04-23T16:08:02.000Z","dependencies_parsed_at":"2023-02-19T01:01:37.839Z","dependency_job_id":"a7504e84-5381-402c-9a5e-6d9a2dc0d861","html_url":"https://github.com/geerlingguy/mac-dev-playbook","commit_stats":{"total_commits":287,"total_committers":23,"mean_commits":"12.478260869565217","dds":"0.32752613240418116","last_synced_commit":"347ea7ac92f3f997bade5773a43273dc18ce6892"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fmac-dev-playbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fmac-dev-playbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fmac-dev-playbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fmac-dev-playbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geerlingguy","download_url":"https://codeload.github.com/geerlingguy/mac-dev-playbook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253819857,"owners_count":21969433,"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","automation","developer","homebrew","mac","macos","playbook","setup"],"created_at":"2024-07-31T15:01:25.329Z","updated_at":"2025-05-12T20:48:23.029Z","avatar_url":"https://github.com/geerlingguy.png","language":"Shell","funding_links":["https://github.com/sponsors/geerlingguy","https://patreon.com/geerlingguy"],"categories":["Shell","Kubernetes Tools, Frameworks, and Projects","Playbooks","Others","HarmonyOS","setup","automation"],"sub_categories":["Interfaces","Windows Manager"],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/geerlingguy/mac-dev-playbook/master/files/Mac-Dev-Playbook-Logo.png\" width=\"250\" height=\"156\" alt=\"Mac Dev Playbook Logo\" /\u003e\n\n# Mac Development Ansible Playbook\n\n[![CI][badge-gh-actions]][link-gh-actions]\n\nThis playbook installs and configures most of the software I use on my Mac for web and software development. Some things in macOS are slightly difficult to automate, so I still have a few manual installation steps, but at least it's all documented here.\n\n## Installation\n\n  1. Ensure Apple's command line tools are installed (`xcode-select --install` to launch the installer).\n  2. [Install Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html):\n\n     1. Run the following command to add Python 3 to your $PATH: `export PATH=\"$HOME/Library/Python/3.9/bin:/opt/homebrew/bin:$PATH\"`\n     2. Upgrade Pip: `sudo pip3 install --upgrade pip`\n     3. Install Ansible: `pip3 install ansible`\n\n  3. Clone or download this repository to your local drive.\n  4. Run `ansible-galaxy install -r requirements.yml` inside this directory to install required Ansible roles.\n  5. Run `ansible-playbook main.yml --ask-become-pass` inside this directory. Enter your macOS account password when prompted for the 'BECOME' password.\n\n\u003e Note: If some Homebrew commands fail, you might need to agree to Xcode's license or fix some other Brew issue. Run `brew doctor` to see if this is the case.\n\n### Use with a remote Mac\n\nYou can use this playbook to manage other Macs as well; the playbook doesn't even need to be run from a Mac at all! If you want to manage a remote Mac, either another Mac on your network, or a hosted Mac like the ones from [MacStadium](https://www.macstadium.com), you just need to make sure you can connect to it with SSH:\n\n  1. (On the Mac you want to connect to:) Go to System Preferences \u003e Sharing.\n  2. Enable 'Remote Login'.\n\n\u003e You can also enable remote login on the command line:\n\u003e\n\u003e     sudo systemsetup -setremotelogin on\n\nThen edit the `inventory` file in this repository and change the line that starts with `127.0.0.1` to:\n\n```\n[ip address or hostname of mac]  ansible_user=[mac ssh username]\n```\n\nIf you need to supply an SSH password (if you don't use SSH keys), make sure to pass the `--ask-pass` parameter to the `ansible-playbook` command.\n\n### Running a specific set of tagged tasks\n\nYou can filter which part of the provisioning process to run by specifying a set of tags using `ansible-playbook`'s `--tags` flag. The tags available are `dotfiles`, `homebrew`, `mas`, `extra-packages` and `osx`.\n\n    ansible-playbook main.yml -K --tags \"dotfiles,homebrew\"\n\n## Overriding Defaults\n\nNot everyone's development environment and preferred software configuration is the same.\n\nYou can override any of the defaults configured in `default.config.yml` by creating a `config.yml` file and setting the overrides in that file. For example, you can customize the installed packages and apps with something like:\n\n```yaml\nhomebrew_installed_packages:\n  - git\n  - go\n\nmas_installed_apps:\n  - { id: 443987910, name: \"1Password\" }\n  - { id: 498486288, name: \"Quick Resizer\" }\n  - { id: 557168941, name: \"Tweetbot\" }\n  - { id: 497799835, name: \"Xcode\" }\n\ncomposer_packages:\n  - name: hirak/prestissimo\n  - name: drush/drush\n    version: '^8.1'\n\ngem_packages:\n  - name: bundler\n    state: latest\n\nnpm_packages:\n  - name: webpack\n\npip_packages:\n  - name: mkdocs\n\nconfigure_dock: true\ndockitems_remove:\n  - Launchpad\n  - TV\ndockitems_persist:\n  - name: \"Sublime Text\"\n    path: \"/Applications/Sublime Text.app/\"\n    pos: 5\n```\n\nAny variable can be overridden in `config.yml`; see the supporting roles' documentation for a complete list of available variables.\n\n## Included Applications / Configuration (Default)\n\nApplications (installed with Homebrew Cask):\n\n  - [ChromeDriver](https://sites.google.com/chromium.org/driver/)\n  - [Docker](https://www.docker.com/)\n  - [Dropbox](https://www.dropbox.com/)\n  - [Firefox](https://www.mozilla.org/en-US/firefox/new/)\n  - [Google Chrome](https://www.google.com/chrome/)\n  - [Handbrake](https://handbrake.fr/)\n  - [Homebrew](http://brew.sh/)\n  - [LICEcap](http://www.cockos.com/licecap/)\n  - [nvALT](http://brettterpstra.com/projects/nvalt/)\n  - [Sequel Ace](https://sequel-ace.com) (MySQL client)\n  - [Slack](https://slack.com/)\n  - [Sublime Text](https://www.sublimetext.com/)\n  - [Transmit](https://panic.com/transmit/) (S/FTP client)\n\nPackages (installed with Homebrew):\n\n  - autoconf\n  - bash-completion\n  - doxygen\n  - gettext\n  - gifsicle\n  - git\n  - gh\n  - go\n  - gpg\n  - httpie\n  - iperf\n  - libevent\n  - sqlite\n  - nmap\n  - node\n  - nvm\n  - php\n  - ssh-copy-id\n  - readline\n  - openssl\n  - pv\n  - wget\n  - wrk\n  - zsh-history-substring-search\n\nMy [dotfiles](https://github.com/geerlingguy/dotfiles) are also installed into the current user's home directory, including the `.osx` dotfile for configuring many aspects of macOS for better performance and ease of use. You can disable dotfiles management by setting `configure_dotfiles: no` in your configuration.\n\nFinally, there are a few other preferences and settings added on for various apps and services.\n\n## Full / From-scratch setup guide\n\nSince I've used this playbook to set up something like 20 different Macs, I decided to write up a full 100% from-scratch install for my own reference (everyone's particular install will be slightly different).\n\nYou can see my full from-scratch setup document here: [full-mac-setup.md](full-mac-setup.md).\n\n## Testing the Playbook\n\nMany people have asked me if I often wipe my entire workstation and start from scratch just to test changes to the playbook. Nope! This project is [continuously tested on GitHub Actions' macOS infrastructure](https://github.com/geerlingguy/mac-dev-playbook/actions?query=workflow%3ACI).\n\nYou can also run macOS itself inside a VM, for at least some of the required testing (App Store apps and some proprietary software might not install properly). I currently recommend:\n\n  - [UTM](https://mac.getutm.app)\n  - [Tart](https://github.com/cirruslabs/tart)\n\n## Ansible for DevOps\n\nCheck out [Ansible for DevOps](https://www.ansiblefordevops.com/), which teaches you how to automate almost anything with Ansible.\n\n## Author\n\nThis project was created by [Jeff Geerling](https://www.jeffgeerling.com/) (originally inspired by [MWGriffin/ansible-playbooks](https://github.com/MWGriffin/ansible-playbooks)).\n\n[badge-gh-actions]: https://github.com/geerlingguy/mac-dev-playbook/actions/workflows/ci.yml/badge.svg\n[link-gh-actions]: https://github.com/geerlingguy/mac-dev-playbook/actions/workflows/ci.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeerlingguy%2Fmac-dev-playbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeerlingguy%2Fmac-dev-playbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeerlingguy%2Fmac-dev-playbook/lists"}