Getting StartedUpdated July 3, 2026

macOS workstation bootstrap

getting-startedmacosonboardingworkstations

<div class="getting-started-hero" markdown="1"> <h1><span class="platform-icon platform-macos"></span>macOS Workstation Bootstrap</h1> <h2>Provision a secure, fast, and fully-audited macOS developer environment for Epic on Azure.</h2> <p>Best for: native macOS users needing rapid iteration and full local tooling.</p> </div> <ul class="platform-links"> <li><a class="platform-link" href="../bootstrap/">All workstation options</a></li> <li><a class="platform-link" href="macos/">macOS</a></li> <li><a class="platform-link" href="windows/">Windows (WSL2)</a></li> <li><a class="platform-link" href="windows-vdi/">Windows VDI</a></li> <li><a class="platform-link" href="saw/">SAW</a></li> </ul>

At a glance

Aspect	Summary
Purpose	Primary developer workstation (fast iteration)
Provisioning	One-line audited bootstrap script (Homebrew)
Estimated time	15–20 min fresh; 5–10 min update
Core tooling	Git, gh, Terraform, Ansible, Azure CLI, Packer (optional)
When to choose	Need fastest iteration + native macOS tooling

Prerequisites

Steps

(Optional) Review the script for changes (recommended on first run or updates).
Execute the one-line bootstrap (or downloaded reviewed copy).
Allow Homebrew installations / Xcode CLT prompts to complete.
Re-open your terminal (ensures shell profile updates are applied).
Run verification commands below.

One-line execution

curl -fsSL https://github.com/optum-omnichannel/ansible_playbooks/raw/develop/bootstrap_mac.sh | bash

Review then execute (safer)

curl -o bootstrap_mac.sh https://github.com/optum-omnichannel/ansible_playbooks/raw/develop/bootstrap_mac.sh
less bootstrap_mac.sh
bash bootstrap_mac.sh

What the script performs

System compatibility checks (CPU / OS version)
Installs or updates Homebrew & taps
Installs core tooling (Git, gh, Ansible, Terraform, Azure CLI, Packer)
Configures shell (zsh) profiles, PATH ordering, idempotent aliases
Trusts corporate certificates (see Root CA and Internal Policy CA)
Generates SSH key (if absent) with recommended key type
Runs post-install validation (versions & auth checks)

Estimated time: Fresh install 15–20 minutes (network dependent), update 5–10 minutes.

Verification

Run the following commands and confirm each returns a version (no errors):

```bash
ansible --version | head -1
az version --output json | jq -r '."azure-cli"'
terraform version | head -1
gh --version | head -1
packer version
```

Compare against minimum versions table below.

```bash title="Azure authentication"
# Interactive login (browser-based)
az login --tenant optum.com
az account show --output table
```

If you use device code auth (headless):
```bash
az login --use-device-code --tenant optum.com
```

Minimum tool versions

Tool	Minimum
Git	2.39
Terraform	1.5
Ansible	2.14
Python	3.10
GitHub CLI	2.0
Packer	1.9
Azure CLI	2.54

Troubleshooting

| Symptom | Likely cause | Resolution |
|---------|--------------|-----------|
| Command not found after install | New PATH not sourced | Open new terminal or `exec zsh`. |
| `terraform` TLS errors | Missing corporate root CA trust | Re-run script; confirm certificate include present. |
| `az login` hangs | Network / proxy misconfiguration | Validate proxy env vars; test `curl https://management.azure.com`. |
| Homebrew rate limiting | Corporate network egress throttling | Retry in 5–10 minutes; use VPN if required. |

Rollback and cleanup

Action	Command	Note
Remove a tool	`brew uninstall <formula>`	Leaves config files in ~/ retained
Revert PATH changes	Comment lines in `~/.zshrc` added by bootstrap	Idempotent
Regenerate SSH key	`ssh-keygen -t ed25519 -C "<email>"`	Backup old key if still in use

Security notes

  ```bash
  security find-certificate -a -c "OptumRoot" -Z | grep SHA-256 -A1
  # Compare against published fingerprint list
  ```