macOS Development Environment Setup

Ansible-based automation for setting up a macOS development environment. This repository has been converted from bash scripts to Ansible playbooks for better maintainability and idempotency.

Setup

After starting up a new or reformatted Mac, you may want to transfer your SSH keys and API keys to the new machine. While transferring a zipped ~/.ssh directory via AirDrop is acceptable, creating new SSH keys and adding them to GitHub and cloud services is the preferred method.

Prerequisites

Install Xcode Command Line Tools (includes make and git):

xcode-select --install

This opens a dialog to install the command line tools.

Quick Start

The easiest way to set up your environment:

make install  # Installs Homebrew and Ansible
make run      # Runs Ansible playbooks

Optional:

make gitssh      # Creates new SSH keys and adds them to GitHub
make gitgpg      # Creates new GPG keys and adds them to GitHub
make extensions  # Downloads and extracts browser extensions

Manual Setup (Alternative)

If you prefer to run commands manually:

1. Install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Install Ansible:

brew install ansible

1. Run the playbooks:

ansible-playbook ansible/main.yml -i "localhost,"
ansible-playbook ansible/macos.yml -i "localhost,"

1. Set global Git configs:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Or use the Makefile command (requires .env file with GITHUB_USERNAME and GITHUB_EMAIL):

1. Set up SSH keys for GitHub:

• Create a public SSH key & add it to SSH agent
• Log in to GitHub and add the newly created key

Or use the Makefile command:

make gitssh

Post-Installation Steps

After running the Ansible playbooks, complete these manual steps:

• Install iTerm2 profile: Import configs/iterm2-profile.json
• Import Rectangle configs: Import configs/RectangleConfig.json
• Run Cursor Makefile commands:
  • make cursor-import-extensions
  • make cursor-import-keybindings
• Add browser extensions to Ungoogled Chromium (use make extensions to download and extract extensions)

Makefile Commands

Run make help to see all available commands, or refer to the list below:

help                           list make commands
install                        install homebrew and apps
setup-homebrew                 install homebrew
setup-apps                     install apps
check                          run playbooks in check mode
run                            run playbooks normally
extensions-download            download browser extension CRX files
extensions-extract             extract CRX files to unpacked extensions
extensions                     download and extract browser extensions
cursor-export-extensions       [cursor] export extensions
cursor-import-extensions       [cursor] import extensions
cursor-show-keybindings        [cursor] show keybindings
cursor-export-keybindings      [cursor] export keybindings
cursor-import-keybindings      [cursor] import keybindings
cursor                         [cursor] run import commands
gitsetup                       [git] setup git global configs
gitssh                         [git] setup git ssh
gitgpg                         [git] setup git gpg

Repository Structure

• ansible/ - Ansible playbooks for automated setup
  • main.yml - Main playbook (packages, shell config, Python environment)
  • macos.yml - macOS-specific system settings
• configs/ - Configuration files for various applications
  • .gitconfig - Git configuration
  • cursor-extensions.txt - Cursor IDE extensions list
  • cursor-keybindings.json - Cursor IDE keybindings
  • iterm2-profile.json - iTerm2 profile
  • RectangleConfig.json - Rectangle window manager config
• scripts/ - Helper scripts
  • setup-github-ssh.sh - SSH key setup script
  • setup-github-gpg.sh - GPG setup script
  • Other utility scripts
• archive/ - Legacy bash scripts (deprecated, kept for reference)
• docs/ - Documentation and notes

TODO

• Fix uv setup
• Add global uv to .zshrc (see uv documentation)

References

• Using Ansible to automate software installation on my Mac | Opensource.com
• How to export iTerm2 Profiles
• macos - How to turn off all animations on OS X - Ask Different
• Install iTerm2 profile