harmon-ops

Various scripts, dotfiles, and automation for bootstrapping and maintaining my developer environment across macOS, Windows, and Linux machines.

E.g., it helps me bootstrap new computers with a developer environment customized to my liking with shell scripts, dotfiles, package managers, OS settings, IDE preferences, extensions, git customizations, shell aliases, cli packages, programming languages, Dockerfiles, etc. so that my machine is fully setup in a day instead of continually encountering all the numerous customizations that I have gotten used to and then have to gradually fix over weeks.

Homelab infrastructure (Terraform, Ansible, Docker Compose services) lives in the companion repo: harmon-infra

Chezmoi-managed dotfiles live in the companion repo: harmon-dotfiles (shell and git dotfiles are managed there; this repo no longer keeps duplicate copies)

Part of harmon-stack

This repo is part of harmon-stack — my personal stack of homelab, dev-tooling, and automation repos that work together.

Repo	What it is
harmon-init	Copier template that bootstraps & standardizes new repos (CI/CD, devcontainers, AI steering, tooling).
harmon-devkit	Reusable boilerplates & code templates, standalone scripts, and AI assets (skills, prompts, agents).
harmon-dotfiles	Shell & app dotfiles, managed declaratively with chezmoi.
harmon-ops (this repo)	Personal machine bootstrapping, package management & dev-environment setup across macOS/Windows/Linux.
harmon-infra	Homelab infrastructure as code — Terraform, Ansible, and Docker Compose services.

Project Usage

Requirements

• Homebrew
• Python
• Taskfile

Bootstrap

Install required software to run other project installers and task runners

task bootstrap

Install

Install required dependencies

task install

Task Runner

Taskfile.yaml

Testing

Validate

task validate

Security

task security

Linting, Formatting, Conventions, Style Guidelines, etc

• .pre-commit-config.yaml
• .shellcheckrc
• .ansible-lint-ignore

Todo File

todo.md

dotfiles

Uses Chezmoi as a declarative source of truth for my dotfiles — stored in the companion harmon-dotfiles repo. Shell and git dotfiles (.zshrc, .bashrc, .aliases, .functions, .var, .gitconfig, .gitignore_global) are managed there and are no longer duplicated in this repo; os/shell/ retains only utility scripts and the legacy setupShells.sh. Mackup backs up both shell dotfiles and Mac app preferences to iCloud.

flowchart LR
    subgraph Mac["Mac Dev Machine"]
        Home["Home Directory (~)"]
    end

    subgraph Chezmoi["Chezmoi (Source of Truth)"]
        ChezmoiState["Chezmoi Source State"]
        HarmonDotfilesRepo["harmon-dotfiles Git Repo"]
    end

    subgraph Mackup["Mackup (Backup System)"]
        MackupBackup["Mackup Backup Folder"]
        iCloud["iCloud Drive"]
    end

    ChezmoiState -->|applies dotfiles to| Home
    HarmonDotfilesRepo -->|stores| ChezmoiState

    Home -->|backs up dotfiles| MackupBackup
    Home -->|backs up mac app preferences| MackupBackup
    MackupBackup -->|syncs to| iCloud

Loading

Editing dotfiles (chezmoi workflow)

The chezmoi source is the source of truth. How you edit depends on whether a file is a chezmoi template:

• Templated dotfiles (*.tmpl in the source — e.g. .zshrc, .bashrc, .zprofile, .dotfiles/.functions, .dotfiles/.var): edit the source, not the live file. Run chezmoi edit ~/.zshrc then chezmoi apply. chezmoi re-add deliberately skips templates, so hand-edits to the live file are not captured and would be lost on the next chezmoi apply.
• Non-template dotfiles (e.g. .gitconfig, .aliases, starship.toml): you can edit the live file directly; chezmoi re-add captures it back into the source.
• Auto-commit/push: ~/.config/chezmoi/chezmoi.toml sets git.autoCommit and git.autoPush, so chezmoi re-add/edit commit and push to the harmon-dotfiles remote automatically. (This file is local per-machine, not in the repo.)
• ~/.ssh is intentionally excluded via .chezmoiignore in the source — harmon-dotfiles is public, so SSH config (hostnames/internal IPs) must never be committed there. SSH config stays local-only on each machine.

If a chezmoi re-add ever fails because a trailing-whitespace/end-of-file pre-commit hook rewrote the source, the live file has whitespace the hook strips — reconcile with chezmoi apply <file>.

OS config for bootstrapping new machines with a developer environment - os/

Setup a Mac

1. Follow os/mac/CHECKLIST-MAC.md
2. Run os/mac/setupMac.sh

Updating a Mac

Run os/mac/updateMac.sh (directly, via Raycast, or with caffeinate -disu zsh -x ./updateMac.sh) to update Homebrew, the Mac App Store, mackup, chezmoi dotfiles, and Python. It is idempotent and attempts every step even if one fails.

• Logging is automatic. Every run is captured under ~/.log/updateMac/, regardless of how it's launched — no tee pipe needed. ~/.log/updateMac/latest.log always points at the most recent run, and only the 30 most recent run logs are kept.
• Check the last run at a glance: cat ~/.log/updateMac/status.txt shows SUCCESS/FAILED, timestamp, elapsed time, the failed steps, and the log path. The script exits non-zero and the closing notification flags failures.
• What trips the FAILED alarm: genuine breakage — Homebrew formula upgrades, mackup, chezmoi, Python. Routinely-flaky steps only warn so they don't mask real problems: mas upgrade (unreliable on modern macOS) and Homebrew cask upgrades (upstream SHA/auto-update churn).
• Brewfile sync: dumps ~/Brewfile, copies it to machines/<hostname>/, and appends any newly installed packages to os/brew/BrewfileSuperset.
• chezmoi sync is non-destructive: it pulls the source repo and runs chezmoi re-add (never chezmoi apply/update, which would overwrite local edits), then warns if chezmoi status shows drift. See the chezmoi workflow under dotfiles.
• Scheduling is currently manual (run it yourself or via Raycast). The repo's crontab/*.crontab/com.evan.updateMac.plist point at stale paths and are not wired up.

Setup a Linux machine (Not well-developed)

1. Follow os/linux/CHECKLIST-LINUX.md
2. Run os/linux/setupLinux.sh

Setup a Windows machine

1. Follow os/win/CHECKLIST-WIN.md
2. Run os/win/setupWindows.ps1
3. For WSL2 Docker setup, see configs in os/win/wsl/ (Docker Engine, NVIDIA Container Toolkit, SSH, networking)

Shell Environments

On a Mac, zsh and dotfiles are backed up and restored with mackup command in setupMac.sh and updateMac.sh. My other global custom dotfiles like shell_vars and shell_aliases are stored in ~/.dotfiles and configured to be backed up and restored with mackup backup|restore.

Python

This is automatically run from setupMac.sh os/languages/python/setupPython.sh

JavaScript

This is automatically run from setupMac.sh os/languages/javaScript/setupJavaScript.sh

Java

os/languages/java/setupJava.sh (currently commented out in setupMac.sh)

Docker

Docker Compose services are managed in harmon-infra under services/. This repo only covers OS-level Docker setup (e.g., Docker Engine in WSL2 via os/win/wsl/).

Machines

Each machine that I configure is tracked in machines/ where I can track packages, Brewfiles, etc.

Current machines: EvansMacBookPro, mac-server, MacMini2014, MacMini2018, sharons-mac-mini, contraption, tars, unraidContraption, unraidMachina

Helpful Sources

• Homebrew
• mas
• mackup
• https://gist.github.com/MatthewMueller/e22d9840f9ea2fee4716

My Current Developer Environment

• Terminal
  • Ghostty
  • iTerm2 (alternate)
• Shell
  • Oh-my-zsh
  • Bash (alternate)
• Package Management
  • Homebrew
• IDE
  • VS Code
  • VS Code Insiders (alternate)
• Dotfiles
  • Mackup
  • Chezmoi
• Version management
  • mise
  • uv (Python)
• AI
  • Claude Code
  • Codex (alternate)
  • OpenCode (alternate)
• Git
  • Git
  • GitHub
  • GitHub Actions
  • Copier
  • gh cli
• Task Runner
  • go-task (Taskfile.yml)