dotfiles

This repository serves two use cases:

1. Personalize GitHub Codespaces containers with my own dotfiles.
2. Bootstrap a MacBook, both for a new MacBook or to restore a MacBook. I use Strap to bootstrap a MacBook using this dotfiles repository.

If you want to create your own dotfiles repo, start with Mike McQuaid's dotfiles.

First use case: personalizing GitHub Codespaces containers

See Personalizing Codespaces for your account in the GitHub docs.

Second use case: bootstrap a MacBook

Bootstrapping a MacBook is a combination of automated and manual steps. My goal is to improve this workflow over time and eliminate manual steps whenever possible.

Bootstrapping a MacBook relies on the following cloud services:

• LastPass to synchronize passwords across devices.
• Google Chrome Sync to synchronize extensions and settings.
• VS Code Settings Sync to synchronize extensions and settings for VS Code.
• Tresorit to synchronize personal files.

Setup assistant

On new MacBooks or after a factory reset the first thing you see is the setup assistant:

1. Do not link your local user account to iCloud and prevent local user account password reset with your Apple ID via iCloud.
2. Turn on FileVault and write down the recovery key.
3. Do not turn on iCloud keychain.

Above choices mean that you take full responsibility for your MacBook.

Automated installation with Strap

Go to https://macos-strap.herokuapp.com/ and download a customized strap.sh. To download the customized strap.sh you need give Strap access to your GitHub account and authorize it as OAuth app. Strap will then customize the file that you are about to download with your GitHub username and pull your dotfiles from https://github.com/<username>/dotfiles.

For the GitHub authorizaton you need your GitHub password. If you keep it in a password manager like LastPass, your password might be difficult or impossible to type in manually. Use the web version of your password manager to copy the password or use Apple's universal clipboard to copy your GitHub password from a password manager on another Apple device and paste into your new machine.

Follow the instructions on https://macos-strap.herokuapp.com/ to bootstrap your MacBook. After running

bash ~/Downloads/strap.sh

for the first time, Homebrew is not yet in PATH. Run these two commands in your terminal to add Homebrew to PATH (use your own username!):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/thilo/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Run brew doctor to verify that Homebrew is working correctly. Then re-run

bash ~/Downloads/strap.sh

Re-running the automated installation

If the automated installation fails or if you make changes in your dotfiles repository, you can run Strap again to install new dependencies and to copy new dotfiles. Homebrew will skip anything that has been installed already. However, Strap does not remove obsolete symlinks in ~/.

Environment variables with secrets and other secrets

Since all your dotfiles are public, you cannot store secrets in them. You can create ~/.env and define environment variables with secrets. File ~/.zshrc will source this file. ~/.env has been added to .gitignore to prevent accidental commit of secrets.

Setting system preferences manually

Most system preferences that you would normally have to configure manually can be scripted. This is what script macos is for. In macOS Catalina there are settings that cannot be scripted and need to be configured manually:

Language & Region

Setting	Value	Comment
General → Advanced... → First day of the week	Monday	Scripted configuration of this setting is broken in macOS Catalina.

Security & Privacy

Setting	Value	Comment
General → Require password X after sleep or screensaver begins	immediately	Scripted configuration of this setting is broken in macOS Monterey.
Privacy		Review all privacy settings.

Users & Groups

Setting	Comment
Image	Choose preferred image.

Sharing

Set computer name.

How this works under the hood

Local GitHub repository

Strap clones this repository to ~/.dotfiles and symlinks any dotfile to ~/. If you change any dotfiles, you can diff the changes with Git in ~/.dotfiles and commit them.

Scripts

All scripts in the script folder need to be owner executable. Note that the owner executable flag is part of a GitHub commit and will be set when you clone this repository.

Brewfile

CLI tools and applications are installed with Homebrew or directly from the macOS App Store. Brewfile defines which tool or app is installed from which source.

You can think of .Brewfile as your package.json for system dependencies (this post came up with this analogy). Strap uses brew bundle to install dependencies from the taps configured in .Brewfile.

1. homebrew-core,
2. homebrew-cask,
3. homebrew-cask-versions (for visual-studio-code-insiders),
4. homebrew-cask-drivers (for focusrite-control), and
5. macOS App Store (via mas-cli).

Note that mas version 1.8.3 is broken on macOS 12.0.1 (Monterey). You need to install dependencies from the App Store manually.

Configuring macOS

On a new macOS system you normally have to make a number of manual configurations using the System Preferences app. Many of these manual configurations can be scripted. This is what script macos is for.

macOS comes with the defaults command-line utility with which you can change many system preferences. The challenge with defaults is that you need to figure out the domain and key arguments for each setting. Unfortunately, these are not documented well. Here are some pointers:

• A good starting point is Mathias Bynen's .macos configuration file.
• For any security and privacy related confiugrations this macOS Security and Privacy Guide is a great read.
• The defaults-write.com website contains a collection of command-line configurations.
• And last, but not least, if above docs do not have what you were looking for, you can try to reverse engineer the domains and keys required for the defaults command as described in this article.