macOS Development Environment

Automated macOS system configuration and application deployment using Ansible. Streamlines migration from existing MacBook or fresh system setup with curated development tools, applications, and system preferences.
Explore the docs »

Report Bug

Table of Contents

1. About The Project
   • Built With
2. Quick Start
   • Prerequisites
   • Development Environment Settings
   • Basic Setup
3. Deployment & Operations
   • Full Installation Steps
   • Configuration Options
   • System Analysis Tools
   • Troubleshooting
   • Advanced Usage
4. Roadmap
5. Contributing
   • Top Contributors
6. License
7. Contact
8. Acknowledgments

1. About The Project

This repository demonstrates Infrastructure as Code practices for macOS system configuration using Ansible. It provides automated deployment of development tools, applications, system preferences, and configuration files, enabling consistent development environments across multiple machines or streamlined migration between systems.

Key Features:

• Selective Deployment: Choose which components to install/configure
• System Migration: Automated migration from existing MacBook to new system
• Development Environment: Rapid deployment of development tools and configurations
• Consistency: Maintain identical configurations across multiple machines
• 180+ Applications: Comprehensive package management via Homebrew

(back to top)

1.1. Built With

• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

2. Quick Start

Get up and running quickly with these basic steps. For detailed instructions, see Full Installation Steps.

(back to top)

2.1. Prerequisites

1. macOS Requirements

   • macOS 12.0+ (Monterey or later)
   • Administrator access
   • Internet connection

2. Ansible Installation

   # Install via Homebrew (recommended)
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew install ansible
   
   # Or install via pip
   pip3 install ansible

3. Homebrew Installation

   # Install Homebrew (if not already installed)
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

(back to top)

2.2. Development Environment Settings

Project Structure

ansible-macos/
├── ansible/
│   ├── inventory/
│   │   ├── group_vars/
│   │   │   ├── all.yml                    # Main configuration variables
│   │   │   ├── all-comprehensive.yml      # Extended configuration options
│   │   │   ├── enhanced-preferences.yml   # Advanced system preferences
│   │   │   └── minimal.yml               # Minimal installation profile
│   │   └── hosts.yml                     # Ansible inventory
│   └── playbooks/
│       ├── main.yml                      # Master orchestration playbook
│       ├── homebrew.yml                  # Package management
│       ├── dotfiles.yml                  # Shell configuration sync
│       ├── system-prefs.yml              # macOS system preferences
│       ├── enhanced-system-prefs.yml     # Advanced system configuration
│       └── deploy-priority.yml           # Priority deployment sequence
├── config/
│   └── dotfiles/                         # Shell configs, Git settings, SSH configs
├── scripts/
│   ├── deploy-config.sh                  # Interactive deployment script
│   ├── system_inventory.sh               # System analysis and discovery
│   ├── macos_software_audit.sh          # Software inventory generation
│   └── preference-management.sh          # System preference utilities
├── docs/
│   ├── Manual_Installation_Guide.md      # Non-automatable software guide
│   ├── macos-ssh-setup.md               # SSH configuration guide
│   └── ssh_host_key_verification.md     # SSH security documentation
└── setup.sh                             # Initial project setup

Configuration Profiles

The project includes multiple configuration profiles for different use cases:

Profile	Purpose	Applications	System Prefs	Use Case
minimal.yml	Essential tools only	~30 core apps	Basic settings	Quick setup, minimal footprint
all.yml	Standard deployment	~180 applications	Standard prefs	Full development environment
all-comprehensive.yml	Complete feature set	All applications	All preferences	Maximum functionality
enhanced-preferences.yml	Advanced customization	Standard apps	Advanced tweaks	Power user setup

(back to top)

2.3. Basic Setup

1. Clone and prepare

   git clone https://github.com/jonathan-d-nguyen/ansible-macos.git
   cd ansible-macos
   
   # Run initial setup
   ./setup.sh

2. Interactive deployment

   # Launch interactive deployment script
   ./scripts/deploy-config.sh

3. Quick deployment (all components)

   cd ansible
   ansible-playbook -i inventory/hosts.yml playbooks/main.yml

(back to top)

3. Deployment & Operations

(back to top)

3.1. Full Installation Steps

1. Repository Setup

   git clone https://github.com/jonathan-d-nguyen/ansible-macos.git
   cd ansible-macos
   ./setup.sh

2. Interactive Component Selection

   # Launch interactive deployment
   ./scripts/deploy-config.sh

   The script will prompt you to select components:

   • homebrew: Package manager and command-line tools (git, node, fzf, fd, powershell)
   • apps: GUI applications via Homebrew Cask (VS Code, Docker, Alfred, Obsidian, Slack, etc.)
   • system: macOS system preferences (Dock, Finder, keyboard settings)
   • dotfiles: Shell configurations (.zshrc, .gitconfig, .bash_profile, etc.)
   • keyboard-maestro: Macro automation import
   • alfred: Workflow and preference import

3. Manual Deployment (Advanced)

   cd ansible
   
   # Deploy specific components
   ansible-playbook -i inventory/hosts.yml --tags "homebrew,dotfiles" playbooks/main.yml
   
   # Deploy with specific profile
   ansible-playbook -i inventory/hosts.yml -e @inventory/group_vars/minimal.yml playbooks/main.yml
   
   # Deploy everything
   ansible-playbook -i inventory/hosts.yml playbooks/main.yml

4. Verification

   # Check installed packages
   brew list
   
   # Verify system preferences
   defaults read com.apple.dock
   
   # Test dotfiles
   source ~/.zshrc

(back to top)

3.2. Configuration Options

Main Configuration: ansible/inventory/group_vars/all.yml

# Core packages
homebrew_packages:
  - git
  - node
  - fzf
  - fd
  - powershell
  - jsonnet

# GUI applications
homebrew_casks:
  # Development Tools
  - visual-studio-code
  - docker
  - iterm2
  - github-desktop
  - fork

  # Productivity
  - alfred
  - keyboard-maestro
  - obsidian
  - rectangle

# System preferences
system_preferences:
  - { domain: "com.apple.dock", key: "autohide", type: "bool", value: true }
  - { domain: "com.apple.dock", key: "tilesize", type: "int", value: 48 }
  - {
      domain: "com.apple.finder",
      key: "AppleShowAllExtensions",
      type: "bool",
      value: true,
    }

# Dotfiles to sync
dotfiles:
  - src: ".zshrc"
    dest: "~/.zshrc"
  - src: ".gitconfig"
    dest: "~/.gitconfig"

Feature Toggles

Control deployment scope in main.yml:

vars:
  install_homebrew: true
  install_apps: true
  configure_system: true
  sync_dotfiles: true
  import_keyboard_maestro: false
  import_alfred: false

(back to top)

3.3. System Analysis Tools

1. Generate Software Inventory

   # Create inventory of currently installed software
   ./scripts/macos_software_audit.sh
   
   # Generate system configuration inventory
   ./scripts/system_inventory.sh

2. Export Current Dotfiles

   # Export current shell configurations for version control
   ./scripts/export-dotfiles.sh

3. System Preference Discovery

   # Discover current system preferences
   ./scripts/discover-preferences.sh

(back to top)

3.4. Troubleshooting

1. Common Issues

   # Homebrew permission errors
   sudo chown -R $(whoami) /opt/homebrew
   
   # System preferences not applied
   # Log out and back in, or restart
   
   # SSH key issues
   ssh-add -K ~/.ssh/id_rsa

2. Debug Mode

   # Run with verbose output
   ansible-playbook -i inventory/hosts.yml -vvv playbooks/main.yml

3. Reset to Defaults

   • System preferences: Reset via System Preferences app
   • Homebrew packages: brew uninstall <package>
   • Applications: Drag to Trash or use App Cleaner

(back to top)

3.5. Advanced Usage

1. Custom Playbook Development

   # Create custom playbook for specific workflows
   ansible-playbook -i inventory/hosts.yml playbooks/your-custom-playbook.yml

2. Profile-Based Deployment

   # Use different configuration profiles
   ansible-playbook -i inventory/hosts.yml -e @inventory/group_vars/minimal.yml playbooks/main.yml

3. Adding New Applications

   Edit ansible/inventory/group_vars/all.yml:

   homebrew_casks:
     - existing-app
     - your-new-app # Add new applications here

4. Custom System Preferences

   system_preferences:
     - {
         domain: "com.apple.yourapp",
         key: "setting",
         type: "bool",
         value: true,
       }

(back to top)

4. Roadmap

• Enhanced Documentation

  • Video walkthrough of deployment process
  • Troubleshooting guide expansion
  • Performance optimization guide

• Extended Platform Support

  • Linux compatibility layer
  • Windows WSL support consideration
  • Cross-platform dotfile management

• Advanced Features

  • mas-cli integration for Mac App Store applications
  • Custom download scripts for non-Homebrew applications
  • Ansible Vault integration for sensitive configurations
  • Role-based deployment (developer, designer, manager profiles)

• Core Infrastructure

  • Selective component deployment
  • Interactive deployment script
  • Multiple configuration profiles
  • System analysis and inventory tools
  • Comprehensive application coverage (180+ apps)
  • Dotfile synchronization
  • System preference automation

• Documentation & Guides

  • Manual installation guide for non-automatable software
  • SSH setup and security documentation
  • System preference management utilities

See the open issues for a full list of proposed features (and known issues).

(back to top)

5. Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Test changes on clean system or VM
4. Update documentation as needed
5. Commit your Changes (git commit -m 'Add some AmazingFeature')
6. Push to the Branch (git push origin feature/AmazingFeature)
7. Open a Pull Request

Testing Guidelines

• Test on clean macOS installation when possible
• Verify idempotency (running twice should be safe)
• Document any new requirements or dependencies

(back to top)

5.1. Top contributors:

(back to top)

6. License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

7. Contact

Jonathan Nguyen - jonathan@jdnguyen.tech

Project Link: https://github.com/jonathan-d-nguyen/ansible-macos

(back to top)

8. Acknowledgments

• Awesome README Template
• Ansible Community - For the automation framework
• Homebrew - For simplified macOS package management
• macOS Community - For system preference documentation and best practices

(back to top)