Developer Workspace Setup (macOS)

A reproducible setup guide for configuring a macOS development workstation quickly and consistently.

Table of Contents

1. Overview
2. System Prerequisites
3. Quick Start (TL;DR)
4. Step-by-Step Installation
   • 4.1 Install Homebrew
   • 4.2 Taps
   • 4.3 Command Line Tools
   • 4.4 GUI Applications
   • 4.5 Browsers
   • 4.6 Fonts
   • 4.7 Docker
   • 4.8 Terminal & Productivity
5. GitHub SSH Setup
6. Post-Install Verification
7. Updating & Maintenance
8. Uninstallation
9. Repository Structure

---

1. Overview

This repository standardizes how we bootstrap a macOS development environment: package management, terminal tools, GUI apps, SSH access, and helpful utilities.

You can either:

• Run a series of manual commands (recommended first time)
• Evolve this into an automated script (future improvement)

---

2. System Prerequisites

Make sure:

• You are on a reasonably up-to-date macOS (Ventura or later recommended).
• You have administrative privileges.
• Xcode Command Line Tools are installed (often auto-triggered by Homebrew).

To install Xcode Command Line Tools explicitly:

xcode-select --install

---

3. Quick Start (TL;DR)

If you trust the included app lists (cli-apps.txt, apps.txt), from the repo root run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew tap homebrew/cask-versions
brew tap homebrew/cask-fonts
xargs brew install < cli-apps.txt
xargs brew install --cask < apps.txt
brew install --cask docker raycast iterm2 alt-tab firefox-developer-edition

Then set up SSH (see Section 5).

---

4. Step-by-Step Installation

4.1 Install Homebrew

Homebrew is the package manager we rely on.

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

After install, follow any on-screen instructions to:

• Add brew to your shell profile (.zprofile, .zshrc, or .bash_profile)
• Test with: brew doctor

4.2 Taps

Add additional repositories for extended packages:

brew tap homebrew/cask-versions
brew tap homebrew/cask-fonts

4.3 Command Line Tools

I've kept a curated list in cli-apps.txt.

git
wget
curl
ffmpeg

etc. Install them using :

xargs brew install < cli-apps.txt

(You can re-run safely; Homebrew skips already-installed formulas.)

4.4 GUI Applications

List GUI apps you want in apps.txt. Example:

visual-studio-code
postman
slack
notion
loom
obsidian
rectangle
discord

Install:

xargs brew install --cask < apps.txt

4.5 Browsers

Developer-specific browsers:

brew install --cask firefox-developer-edition
# Add others as needed:
# brew install --cask google-chrome

4.6 Fonts

Useful programming fonts (examples):

brew install --cask font-fira-code

4.7 Docker

brew install --cask docker

4.8 Terminal & Productivity

brew install --cask iterm2
brew install --cask alt-tab
brew install --cask raycast

Optional tweaks:

• iTerm2: Set up profile, color scheme (e.g. One Dark), configure hotkeys.
• Raycast: Log in, sync extensions.
• AltTab: Adjust Delay = 0, enable "Show window previews".

---

5. GitHub SSH Setup

1. Generate a new SSH key:

   ssh-keygen -t ed25519 -C "your_email@example.com"

2. Ensure the agent is running:

   eval "$(ssh-agent -s)"

3. Add key to agent:

   ssh-add ~/.ssh/id_ed25519

4. Copy the public key:

   pbcopy < ~/.ssh/id_ed25519.pub

5. Add it to GitHub:
   • Go to: GitHub → Settings → SSH and GPG keys → New SSH key
6. Test:

   ssh -T git@github.com

Official references:

• Generate key: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
• Add key: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

---

6. Post-Install Verification

Run:

brew doctor
brew list --versions | head
which git
git --version
node -v
python --version
docker --version

Confirm CLI tools are accessible and GUI apps appear in /Applications (or linked).

7. Updating & Maintenance

• Update formulas:

  brew update
  brew upgrade
  brew cleanup

• Outdated:

  brew outdated

• Security (check):

  brew audit --strict

10. Uninstallation

Uninstall a single formula/cask:

brew uninstall <name>
brew uninstall --cask <cask-name>

Remove Homebrew entirely (last resort):

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

Manually inspect any lingering directories in:

• /usr/local
• /opt/homebrew (Apple Silicon)

---

11. Repository Structure

workspace-setups/
├── README.md
├── cli-apps.txt        # Plain list of Homebrew formulas
├── apps.txt            # Plain list of GUI cask apps
├── scripts/
│   ├── bootstrap.sh    # (future) Automates steps
│   └── verify.sh       # (future) Post-install checks
└── NOTES.md            # (optional) Scratchpad for team preferences

Appendix: Manual Commands (Raw)

For reference (original sequence):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install iterm2
brew install alt-tab
xargs brew install < cli-apps.txt
xargs brew install < apps.txt
brew install --cask docker
brew install raycast
brew tap homebrew/cask-versions
brew tap homebrew/cask-fonts
brew install homebrew/cask-versions/firefox-developer-edition

---

License / Usage

Internal use. Adapt as needed for personal setups.

---