commit d26627f0adca02c50b86ffea5b76d18c82a4ff60
parent c8fd51a2713420d8707f84cabf866ece33203377
Author: Chris Roberts <chris.roberts@learningunix.net>
Date: Wed, 20 May 2026 05:18:09 -0500
added readme
Diffstat:
| A | README.md | | | 122 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 122 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,122 @@
+# Macbook QA Workstation Provisioning
+
+Ansible playbook that sets up a MacBook Pro for QA work. Installs and configures:
+
+- **Xcode Command Line Tools**
+- **Homebrew** (package manager)
+- **Google Chrome**
+- **iTerm2**
+- **Powerlevel10k** (Zsh theme)
+
+Supports both Apple Silicon (M-series) and Intel Macs.
+
+---
+
+## Prerequisites
+
+### 1. Install Ansible
+
+Ansible does not ship with macOS. Install it via pip:
+
+```bash
+pip3 install ansible
+```
+
+Verify it worked:
+
+```bash
+ansible --version
+```
+
+> If `pip3` is not found, install it first:
+> ```bash
+> sudo easy_install pip
+> ```
+> Or install Python from [python.org](https://www.python.org/downloads/macos/) and use its bundled pip.
+
+### 2. Install the required Ansible collection
+
+```bash
+ansible-galaxy collection install -r requirements.yml
+```
+
+---
+
+## Running the Playbook
+
+### Dry run (no changes made)
+
+Always do this first to see what Ansible plans to do:
+
+```bash
+ansible-playbook -i inventory/local.ini site.yml --check --diff
+```
+
+### Apply
+
+```bash
+ansible-playbook -i inventory/local.ini site.yml
+```
+
+> **Note on Xcode Command Line Tools:** On a fresh Mac, macOS will pop up a GUI dialog asking you to click "Install". The playbook will wait up to 5 minutes for that step to complete before continuing.
+
+> **Note on Powerlevel10k:** After the playbook finishes, run `p10k configure` in a new terminal to set up your prompt style.
+
+---
+
+## Customization
+
+### Add Homebrew packages
+
+Edit `group_vars/all.yml` and add to the `homebrew_packages` list:
+
+```yaml
+homebrew_packages:
+ - git
+ - wget
+ - curl
+ - jq
+ - your-package-here
+```
+
+### Add Homebrew casks (GUI apps)
+
+Add to the `homebrew_casks` list in the same file:
+
+```yaml
+homebrew_casks:
+ - slack
+ - postman
+```
+
+### iTerm2 preferences
+
+To deploy a shared iTerm2 config, export your preferences from iTerm2:
+
+**iTerm2 → Settings → General → Preferences → "Export preferences to a custom folder"**
+
+Copy the exported `com.googlecode.iterm2.plist` into:
+
+```
+roles/iterm2/files/com.googlecode.iterm2.plist
+```
+
+The playbook will pick it up automatically on the next run.
+
+> **Warning:** iTerm2 prefs can contain stored SSH passwords or profile credentials. This file is listed in `.gitignore` — do not force-add it to git.
+
+### Powerlevel10k config
+
+To share a pre-baked prompt config, copy your `~/.p10k.zsh` into:
+
+```
+roles/powerlevel10k/files/.p10k.zsh
+```
+
+The playbook will deploy it to `~` on the target machine.
+
+---
+
+## Re-running
+
+The playbook is fully idempotent — running it again on an already-provisioned Mac produces zero changes.
