juanedu/macbook-playbook

Install all your applications and configure everything the way you like it with one command

macbook-playbook

Install all your applications and configure everything the way you like it with one command.

Table of Contents

• Tested on
• Configuring machine
  • Install Developer Tools (xcode-select)
  • Clone repository
  • Create an Ansible Vault password
  • Encrypted files (using Ansible Vault)
  • Prepare machine to run the Ansible playbooks
  • Provision machine
  • Manual steps post make converge
    • Enable assistive access for Divvy
    • Enable assistive access for Terminal
    • Enable assistive access for Emacs
    • Set up Spotify Last.fm connect
• Roles
  • Installs
    • Desktop Applications
    • Text Editors
    • Communication
    • Configuration
    • Multimedia
    • Browser Plugins
    • Programming Languages
    • Virtualization, Provisioning, Containers and System Tools
    • Package Managers and Build Tools
    • Shell
    • Programming Utilities
    • Security
    • GNU Command Line Tools
    • Data Systems
    • Configuration, Monitoring and Debugging (tag: observability)
    • Document Processors and Plotting
    • Markup Tools
    • Command line tools
    • Miscellaneous
  • Configures
    • Passwordless sudo
    • Remaps Caps-Lock to Control
    • Puts SSH keys in place
    • Makes Google Chrome the default browser
• Author
• License

Tested on

I’ve been using macbook-playbook since 2013. I’ve used it on at least six MacBook Pros with different macOS versions. As of March 2021 I use it on both my current MacBook Pros, one with Catalina and the other with Big Sur installed.

Please open an issue if you’re trying this out and bump into anything.

Bootstrap machine (make bootstrap)

These are one-time steps that need to be done on machines that are running macbook-playbook for the first time.

Install Developer Tools (xcode-select)

Open the “Terminal” application, type git into the shell and follow the instructions to install the Apple Developer Tools.

Clone repository

Now your machine should have git and python3 installed.

git clone https://github.com/mpereira/macbook-playbook.git

Give Terminal/iTerm2/Emacs/etc. assistive access

Depending on your macOS version you will be queried or not for assistive access while make converge runs. This is required for example to remap caps lock to control.

In case that task fails, or if you want to do it beforehand just in case, go to “System Preferences > Security & Privacy > Privacy > Accessibility” and add the application running macbook-playbook (Terminal/iTerm2/Emacs/etc.) to the list.

Create an Ansible Vault password

This password will be used to encrypt and decrypt the files referenced in the Encrypted files section. Please make sure to use a strong password.

echo 'SomePassword123$' > .ansible_vault_password

Encrypted files (using Ansible Vault)

The following files currently checked into this git repository are encrypted with my personal Ansible Vault password. Unless you have my password, roles referencing these files will fail to run.

Description	File	Role
AWS CLI credentials	secrets/aws_credentials_file	awscli
BetterTouchTool license	secrets/better_touch_tool_license_file	better-touch-tool
DaisyDisk license	secrets/daisydisk_registration_key_file	daisydisk
Enviroment variables for dotfiles	secrets/mpereira_dotfiles_environment_yml_file	dotfiles
iStat Menus settings	secrets/istat_menus_settings_file	istat-menus
Prey API key	secrets/prey_api_key_yaml_file	prey
Private SSH key	secrets/mpereira_at_pluto_ssh_private_key	ssh-keys
s3cmd configuration	secrets/s3cmd_cfg_file	s3cmd

You have two choices: skip these roles, and/or overwrite the encrypted files with your own.

To overwrite them first run

make truncate-sensitive-files

And then you’ll be able to overwrite them with your own files (for example your own ~/.ssh/id_rsa) and then encrypt them with make encrypt.

To skip them, when you reach the provision machine step, make Ansible skip roles tagged with uses-secrets. You don’t need to run this now, the command below is just an example.

make converge ARGS='--skip-tags uses-secrets'

Prepare machine to run the Ansible playbooks

This will:

1. Set up passwordless sudo
2. Install a user Python3
3. Install Ansible
4. Set up the Git pre-commit hook that automatically encrypts secrets before Git commits

make bootstrap

Your machine should now be ready to be provisioned! You won’t need to run the above steps again.

Configure machine (make converge)

Now that the machine is bootstrapped, we can provision it.

Provision machine

This runs all non-disabled roles in =main.yml=.

make converge ARGS='--skip-tags disabled'

ansible-playbook arguments can be passed via the ARGS environment variable. For example, --tags can be passed so that only matching roles are run.

make converge ARGS='--tags google-chrome'

--skip-tags can also be passed to avoid running certain roles.

make converge ARGS='--skip-tags disabled,unity'

All role tags can be seen in =main.yml=.

Tasks may fail due to intermittent reasons like temporary server unavailability. When a task fails you can either disable its role via --skip-tags or use --start-at-task with the name value of some task to cause Ansible to start the playbook exactly there.

For example, if the “Install Emacs” task from the “build-emacs” role fails for what seems to be an intermittent issue, you can pick up provisioning from there so that previous tasks don’t have to re-run.

make converge ARGS='--skip-tags disabled --start-at-task "Install Emacs"'

Check the official Ansible documentation for more details.

Manual steps post make converge

These are steps that are currently not automated because:

• it would be difficult
• it would be impossible
• or I just didn’t have the time

Change keyboard layout to U.S. international

1. System Preferences -> Keyboard -> Input Sources
2. Click +
3. Select “English” on left column
4. Select “U.S. International - PC” on right column
5. Click “Add”
6. Remove other keyboard layouts from the left column

iStat Menus

1. Import license from roles/istat-menus/files/iStat Menus Settings.ismp

PDF Expert

1. Register license

Sound Control

1. Check “Check for updates automatically”
2. Register license
3. Preferences > Priority Devices > Output and Input
   • Check “Switch to device when” “Device is attached”
   • Reorder devices in priority list

BetterTouchTool

1. Register license

Terminal

Preferences > Profiles > Pro > Font

Set to Hack Regular 18 pt.

System Preferences > Security & Privacy > Privacy > Accessibility

• BetterTouchTool.app
• Dropbox
• Emacs.app
• Persephone.app
• RescueTime
• VLC

System Preferences > Keyboard > Shortcuts > Mission Control

Uncheck:

• Mission Control
• Move left a space
• Move right a space
• Switch to desktop 1

Roles

Installs

Desktop Applications

• Android File Transfer
• BitBar
• Cursorcerer
• DaisyDisk
• Dash
• Divvy
• Dropbox
• Elgato Dock
• f.lux
• Firefox
• Google Chrome
• Google Photos
• Grammarly
• iStat Menus
• LICEcap
• Maccy
• PDF Expert
• Persephone
• RescueTime
• Skype
• Slack
• Sound Control
• Spotify
• Steam
• Teensy Loader
• ToggleDarkMode
• Unity
• Unity Hub
• VLC
• XQuartz
• YNAB (disabled by default, I use the online version and the application binary isn’t available anymore)

Text Editors

• Emacs 27.1
• Emacs 28.0.50
• MacVim
• Neovim
• Vim (disabled by default until I figure out why it isn’t compiling on macOS Big Sur with LLVM 12)
• VSCode

Configuration

• dotemacs
• dotfiles

Programming Languages

• Clojure
• GNU Octave
• Go
• Haskell
• Java (AdoptOpenJDK)
• Lua
• LuaJIT
• Node.js
• PureScript (disabled by default until I figure out why stack install purescript is currently failing)
• Python 3
• R
• Ruby
• Rust

Multimedia

• Beets
• FFmpeg
• gifsicle
• ImageMagick
• mpc
• mpd
• mpdscribble
• mpg123
• mplayer
• shpotify
• TagLib

Fonts

• Consolas
• Hack

Browser Plugins

• Firefox Adblock Plus

Virtualization, Provisioning, Containers and System Tools

• Docker
• krew
• kubectl
• kubectl-tree
• OpenZFS (disabled by default until it works on macOS Big Sur)
• Terraform
• Vagrant
• Vagrant vagrant-vbguest plugin
• VirtualBox

Package Managers and Build Tools

• bundler
• CMake
• GraalVM
• Homebrew
• leiningen
• MacPorts
• Make
• Maven
• pulp
• Yarn

Shell

• Babashka
• Bash
• fish
• fish-foreign-env
• iTerm
• tmux
• tmuxinator
• Zsh

Programming Utilities

• Black
• clojure-lsp
• Ctags
• YAPF
• zprint
• yq
• shfmt
• node-cljfmt
• gron
• ktlint
• Prettier
• Pyre
• rust-analyzer
• ShellCheck

Data Systems

• Apache Hadoop (disabled by default, it conflicts with the yarn JavaScript package manager)

Configuration, Monitoring and Debugging

• Apache JMeter
• Glances
• htop
• ngrep
• vtop

Document Processors and Plotting

• gnuplot
• MacTeX

Markup Tools

• Grip
• Hugo
• Markdown
• Pandoc
• wkhtmltopdf

Command line tools

• AWS CLI
• defaultbrowser
• delta
• delta
• git
• fd
• jq
• p7zip
• parallel
• pgsanity
• pngpaste
• ripgrep
• s3cmd (disabled by default, I use the AWS CLI)
• scc
• tealdeer
• terminal-notifier
• tree
• websocat
• wrk
• xz

Security

• Prey
• GnuPG
• vault

GNU Command Line Tools

• binutils
• coreutils
• diffutils
• ed
• findutils
• gawk
• gnu-indent
• gnu-sed
• gnu-tar
• gnu-which
• gnutls
• grep
• gzip
• screen
• watch
• wdiff
• wget

Miscellaneous

• Mutagen
• FontForge
• Qt 5 (disabled by default)
• WordNet

Configures

Makes Google Chrome the default browser

Passwordless sudo

Puts SSH keys in place

Remaps Caps-Lock to Control

Author

Murilo Pereira

License

MIT