:toc: macro :toclevels: 5 :figure-caption!:

= macOS Configuration

This project provides an opinionated default configuration built upon the link:https://alchemists.io/projects/mac_os[macOS] project. Should the configuration provided by this project not be to your liking, feel free to fork and customize for your specific needs.

toc::[]

== Features

Due to the amount of tooling used, the following features are broken down into subsections for easier navigation.

=== Homebrew Formulas

Installs the following link:https://brew.sh[formulas]:

• link:https://www.gnu.org/software/bash[Bash]
• link:http://bash-completion.alioth.debian.org[Bash Completion]
• link:https://github.com/sharkdp/bat[Bat]
• link:https://github.com/toy/blueutil[blueutil]
• link:https://github.com/cloudflare/cloudflared[cloudflared]
• link:https://github.com/schollz/croc[croc]
• link:https://crystal-lang.org[Crystal]
• link:http://ctags.sourceforge.net[CTags]
• link:https://difftastic.wilfred.me.uk[Difftastic]
• link:https://direnv.net[direnv]
• link:https://github.com/wagoodman/dive[Dive]
• link:https://github.com/muesli/duf[duf]
• link:https://github.com/bootandy/dust[Dust]
• link:http://duti.org[duti]
• link:https://eradman.com/entrproject[Entr]
• link:https://exiftool.org/index.html[ExifTool]
• link:https://github.com/sharkdp/fd[fd]
• link:https://github.com/tako8ki/frum[Frum]
• link:https://github.com/Schniz/fnm[Fast Node Manager]
• link:https://fx.wtf[fx]
• link:https://github.com/junegunn/fzf[FZF]
• link:https://git-scm.com[Git]
• link:https://github.com/dandavison/delta[Git Delta]
• link:https://github.com/newren/git-filter-repo[Git Filter Repo]
• link:https://www.gnupg.org[GPG]
• link:https://github.com/orf/gping[gping]
• link:http://www.graphicsmagick.org[Graphics Magick]
• link:https://www.graphviz.org[Graphviz]
• link:https://github.com/hadolint/hadolint[Haskell Dockerfile Linter]
• link:https://github.com/sharkdp/hexyl[hexyl]
• link:http://www.andre-simon.de/doku/highlight/en/highlight.php[Highlight]
• link:https://hisham.hm/htop[htop]
• link:https://github.com/reorx/httpstat[HTTP Stat]
• link:https://github.com/sharkdp/hyperfine[Hyperfine]
• link:https://imagemagick.org[ImageMagick]
• link:https://stedolan.github.io/jq[jq]
• link:https://lnav.org[lnav]
• link:https://github.com/CISOfy/lynis[Lynis]
• link:https://mailpit.axllent.org[Mailpit]
• link:https://github.com/mas-cli/mas[Mac App Store]
• link:https://jedisct1.github.io/minisign[Minisign]
• link:https://github.com/variadico/noti[Noti]
• link:https://github.com/hatoo/oha[Oha]
• link:https://www.openssh.com[OpenSSH]
• link:https://openssl.org[OpenSSL]
• link:https://osv.dev[Open Source Vulnerability Scanner]
• link:https://github.com/DarthSim/overmind[Overmind]
• link:https://pandoc.org[Pandoc]
• link:https://savannah.gnu.org/projects/parallel[Parallel]
• link:https://github.com/sharkdp/pastel[Pastel]
• link:https://sosedoff.github.io/pgweb[pgweb]
• link:https://www.zlib.net/pigz[Pigz]
• link:https://github.com/GPGTools/pinentry[Pinentry]
• link:https://github.com/dalance/procs[Procs]
• link:https://tiswww.case.edu/php/chet/readline/rltop.html[Readline]
• link:https://github.com/BurntSushi/ripgrep[ripgrep]
• link:https://rsync.samba.org[rsync]
• link:https://github.com/koalaman/shellcheck[ShellCheck]
• link:https://www.joedog.org/siege-home[Siege]
• link:https://github.com/karol-broda/snitch[Snitch]
• link:https://www.tarsnap.com[Tarsnap]
• link:https://www.terraform.io[Terraform]
• link:https://github.com/ggreer/the_silver_searcher[The Silver Surfer]
• link:https://github.com/tmux/tmux/wiki[tmux]
• link:https://github.com/XAMPPRocky/tokei[Tokie]
• link:https://vale.sh[Vale]
• link:https://valkey.io[Valkey]
• link:https://github.com/sachaos/viddy[Viddy]
• link:https://www.vim.org[Vim]
• link:https://github.com/libvips/libvips[Vips]
• link:https://github.com/vi/websocat[Websocat]
• link:https://developers.yubico.com/yubikey-manager[YubiKey Manager CLI]
• link:https://github.com/ajeetdsouza/zoxide[Zoxide]

=== Homebrew Casks

Installs the following link:https://brew.sh[casks]:

• link:https://www.alfredapp.com[Alfred]
• link:https://freemacsoft.net/appcleaner[App Cleaner]
• link:https://www.arduino.cc/en/software/[Arduino IDE]
• link:https://www.rogueamoeba.com/audiohijack[Audio Hijack]
• link:https://www.balena.io/etcher[Balena Etcher]
• link:https://bombich.com[Carbon Copy Cloner]
• link:https://getcleanshot.com[CleanShot]
• link:https://discord.com[Discord]
• link:https://software.charliemonroe.net/downie[Downie]
• link:https://www.getdoxie.com[Doxie]
• link:https://www.dropbox.com[Dropbox]
• link:https://element.io[Element]
• link:https://www.mozilla.com/en-US/firefox[Firefox]
• link:https://www.rogueamoeba.com/fission[Fission]
• link:https://focusrite.com[Focusrite Control]
• link:https://ghostty.org[Ghostly]
• link:https://www.google.com/chrome[Google Chrome]
• link:https://www.noodlesoft.com[Hazel]
• link:https://iina.io[IINA]
• link:http://imageoptim.pornel.net[ImageOptim]
• link:https://bjango.com/mac/istatmenus[iStat Menus]
• link:https://mitmproxy.org[mitmproxy]
• link:https://netnewswire.com[NewNewsWire]
• link:https://ngrok.com[Ngrok]
• link:https://numi.app[Numi]
• link:https://obsidian.md[Obsidian]
• link:https://www.openoffice.org[OpenOffice]
• link:https://orbstack.dev[OrbStack]
• link:https://kagi.com/orion[Orion]
• link:https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project[OWASP Zed Attack Proxy (ZAP)]
• link:https://www.pgadmin.org[pgAdmin]
• link:https://superhighfives.com/pika[Pika]
• link:https://getpixelsnap.com[PixelSnap]
• link:https://protonvpn.com[ProtonVPN]
• link:https://paw.cloud[Rapid API]
• link:https://www.raspberrypi.com/software/[Raspberry Pi Imager]
• link:https://manytricks.com/resolutionator[Resolutionator]
• link:https://flyingmeat.com/retrobatch[Retrobatch]
• link:https://revpdf.com[RevPDF]
• link:https://signal.org[Signal]
• link:https://skim-app.sourceforge.io[Skim]
• link:https://www.sonos.com[Sonos]
• link:https://www.sublimetext.com[Sublime Text]
• link:https://panic.com/transmit[Transmit]
• link:https://twist.com[Twist]
• link:https://www.sparklabs.com/viscosity[Viscosity]
• link:https://vivaldi.com[Vivaldi]
• link:https://zed.dev[Zed]

=== App Store

Installs link:https://www.apple.com/app-store[App Store] applications as managed by the link:https://github.com/mas-cli/mas[Mac App Store] CLI which assumes you've purchased the applications listed below:

• link:https://secure.flyingmeat.com/acorn[Acorn]
• link:https://bitwarden.com[Bitwarden]
• link:https://ccmenu.org[CCMenu]
• link:https://sindresorhus.com/system-color-picker[Color Picker]
• link:https://daisydiskapp.com[DaisyDisk]
• link:https://www.apple.com/mac/garageband[GarageBand]
• link:https://handmirror.app[Hand Mirror]
• link:https://www.apple.com/imovie[iMovie]
• link:https://firecore.com/infuse[Infuse]
• link:https://manytricks.com/keycodes[Key Codes]
• link:https://manytricks.com/keymou[Keymou]
• link:https://www.apple.com/keynote[Keynote]
• link:https://apps.apple.com/us/app/amazon-kindle/id302584613[Kindle]
• link:http://limechat.net/mac[LimeChat]
• link:https://marked2app.com[Marked 2]
• link:http://getmedis.com[Medis]
• link:https://www.markvapps.com/metadatics[Metadatics]
• link:https://mindnode.com[MindNode]
• link:https://manytricks.com/namemangler[Name Mangler]
• link:https://www.apple.com/numbers[Numbers]
• link:https://www.omnigroup.com/omnifocus[OmniFocus]
• link:https://www.apple.com/pages[Pages]
• link:https://krillapps.com/patterns[Patterns]
• link:https://software.charliemonroe.net/permute[Permute]
• link:https://apps.apple.com/gb/app/sequence-diagram/id1195426709[Sequence Diagram]
• link:https://shapesapp.com[Shapes]
• link:https://slack.com[Slack]
• link:https://www.adriangranados.com[WiFi Explorer]

=== Applications

Installs the following, basic, macOS applications which are not located in the App Store:

• link:https://www.docker.com[Docker]
• link:https://icemenubar.app[Ice]
• link:https://moneywell.app[MoneyWell]
• link:https://manytricks.com/moom[Moom]
• link:https://github.com/theory/pgenv[pgenv]
• link:https://tana.inc[Tana]

=== Application Extensions

Installs the following extensions to existing applications:

• link:https://github.com/tpope/vim-bundler[Vim Bundler]
• link:https://github.com/tpope/vim-commentary[Vim Commentary]
• link:https://github.com/tpope/vim-fugitive[Vim Fugitive]
• link:https://github.com/airblade/vim-gitgutter[Vim Git Gutter]
• link:https://github.com/tpope/vim-pathogen[Vim Pathogen]
• link:https://github.com/tpope/vim-projectionist[Vim Projectionist]
• link:https://github.com/tpope/vim-rails[Vim Rails]
• link:https://github.com/vim-ruby/vim-ruby[Vim Ruby]
• link:https://github.com/AndrewRadev/splitjoin.vim[Vim Splitjoin]
• link:https://github.com/kana/vim-textobj-user[Vim Text Object User]
• link:https://github.com/tpope/vim-unimpaired[Vim Unimpaired]

=== Node Packages

Installs the following link:https://nodejs.org[Node] link:https://www.npmjs.com[packages]:

None are used at the moment.

=== Ruby Gems

Installs the following link:https://www.ruby-lang.org[Ruby] link:https://rubygems.org[gems]:

• link:https://github.com/amazing-print/amazing_print[Amazing Print]
• link:https://asciidoctor.org[ASCII Doctor]
• link:https://github.com/evanphx/benchmark-ips[Benchmark IPS]
• link:https://github.com/jmmastey/bundler-stats[Bundler Stats]
• link:https://github.com/mattbrictson/bundleup[BundleUp]
• link:https://alchemists.io/projects/caliber[Caliber]
• link:https://alchemists.io/projects/gemsmith[Gemsmith]
• link:https://alchemists.io/projects/git-lint[Git Lint]
• link:https://hanamirb.org[Hanami]
• link:https://alchemists.io/projects/hanamismith[Hanamismith]
• link:https://alchemists.io/projects/irb-kit[IRB Kit]
• link:https://github.com/jaredbeck/libyear-bundler[Libyear (Bundler)]
• link:https://alchemists.io/projects/pennyworth[Pennyworth]
• link:https://github.com/joonty/pessimize[Pessimize]
• link:https://alchemists.io/projects/pragmater[Pragmater]
• link:https://github.com/troessner/reek[Reek]
• link:https://github.com/AlexB52/retest[Retest]
• link:https://rspec.info[RSpec]
• link:https://alchemists.io/projects/rubysmith[Rubysmith]
• link:https://solargraph.org/guides[Solargraph]
• link:https://alchemists.io/projects/sublime_text_kit[Sublime Text Kit]
• link:https://github.com/red-data-tools/YouPlot[YouPlot]

=== Rust Crates

Installs the following link:https://www.rust-lang.org[Rust] link:https://crates.io[crates]:

• link:https://github.com/nabijaczleweli/cargo-update[Cargo Update]
• link:https://dotenv-linter.github.io[Dotenv Linter]
• link:https://eza.rocks[Eza]
• link:https://jless.io[jless]
• link:https://github.com/chmln/sd[sd]

== Requirements

. Apple Silicon hardware. . link:https://alchemists.io/projects/mac_os[macOS] . link:https://developer.apple.com/xcode[Xcode]

== Setup

To install, run:

[source,bash]

git clone https://github.com/bkuhlmann/mac_os-config.git cd mac_os-config git checkout 31.1.0

== Usage

The following will walk you through the steps of installing/re-installing your machine.

=== Pre-Install

Ensure you have the following in place for your Silicon machine:

. Ensure a backup of your Apple, NAS, backup image, and Dropbox credentials are available. . Ensure a recent backup of your machine exists and works properly. . Ensure link:https://support.apple.com/en-us/HT208198[Startup Security Utility] is disabled. .. Turn off your machine. .. Start your machine by pressing and holding the POWER button until you see startup options being loaded. .. Select Options → Startup Security Utility from the main menu. .. Select Reduced Security. .. Quit options and restart the machine.

=== Install

. Create a link:https://alchemists.io/projects/mac_os/#_boot_disk[macOS Boot Disk] and follow instructions. . Ensure latest software updates are applied per link:https://alchemists.io/projects/mac_os/#_requirements[macOS Requirements]. . Ensure Xcode is installed per link:https://alchemists.io/projects/mac_os/#_requirements[macOS Requirements]. . Run link:https://alchemists.io/projects/mac_os#_usage[macOS Install] and follow all prompts.

=== Post-Install

The following are additional steps, not easily automated, that are worth completing after the install scripts have completed:

• System Settings ** Apple ID *** Login (if not already). *** Update avatar. *** Configure iCloud. *** Enable Find My Mac. ** General *** AirDrop & Handoff **** Disable AirPlay Receiver so you can run link:https://github.com/rack/rack[Rack] applications on Port 5000. *** AutoFill & Passwords **** Disable AutoFill Passwords and Passkeys. *** Login Items **** Ensure only Alfred is listed. *** Language and Region **** Set First day of week to Monday. **** Set Date format to YYYY-MM-DD. ** Appearance *** Use Light theme. ** Bluetooth *** Reconnect keyboard, mouse, and earbuds. ** Sound *** Disable Play sound on startup. *** Disable Play user interface sound effects. ** Apple Intelligence & Siri *** Disable Listen for. *** Disable Keyboard shortcut (use Alfred instead). ** Privacy & Security *** Enable FileVault. ** Wallpaper *** Select custom image from Documents. *** Screen Saver **** Start after 5 minutes. **** Use custom and select Message. ** Spotlight *** Disable Help Apple Improve Search. link:https://obdev.at/blog/what-happens-on-your-device-stays-on-your-device-until-it-doesnt[Details]. ** Lock Screen *** Set Show message when locked with custom text. ** Battery *** Click Options and enable Prevent automatic sleeping on power adapter when the display is off. ** Lock Screen *** Set Turn display off on battery when inactive for 2 minutes. *** Set Turn display off on power adapter when inactive for 10 minutes. *** Set Require password after screen saver begins or display is turned off for 5 minutes. *** Set Show message when locked. Example: <url> | <email> | <phone>. ** Touch ID & Password *** Rename fingerprint. *** Enable use of Touch ID for all settings. *** Enable use of Apple Watch. ** Users & Groups *** Update avatar image. *** Remove unused login items. *** Disable guest account. ** Internet Accounts *** Add all accounts. ** Wallet & Apple Pay *** Reenable all accounts and assign default card. ** Keyboard *** Set Key repeat rate to max level. *** Set Delay until repeat to short (max) level. *** Keyboard Shortcuts **** Select Dock and uncheck Turn Dock Hiding On/Off. **** Select Mission Control and assign CONTROL + OPTION + COMMAND + W to Mission Control. **** Select Mission Control and assign CONTROL + OPTION + COMMAND + N to Show Notification Center. **** Select Screenshots and uncheck all boxes. **** Select Spotlight and uncheck all boxes. ** Mouse *** Ensure tracking speed is on the 5th setting (i.e. 5th from right of Slow). ** Trackpad *** Ensure tracking speed is on the 5th setting (i.e. 5th from right of Slow). ** Printers & Scanners *** Add printer/scanner.
• iStat Menus ** Double click, within the Applications folder, to install as a system preference.
• Notifications ** Set Show previews when unlocked. ** Disable Allow notifications when the display is sleeping. ** Disable Allow notifications when the screen is locked. ** Disable Allow notifications when mirroring or sharing the display. ** Disable Show notifications on lock screen and Play sound for notification for all applications. ** Enable Allow notifications from iPhone but disable Play sounds for notifications from iPhone within this option.
• Carbon Copy Cloner ** Rename old backup, create new backup, and schedule frequency.

=== Keyboard Shortcuts

Several applications provide global hotkey support. These are the associations I use (which are also captured in the +restore.bom+ as well):

• COMMAND (x2): Siri (open)
• COMMAND + SPACE: Alfred/Spotlight (open)
• link:https://alchemists.io/articles/clean_shot/#_shortcuts[CleanShot]
• CONTROL + OPTION + COMMAND + c: Pika (copy color)
• CONTROL + OPTION + COMMAND + d: Alfred Define (use OPTION to open Dictionary)
• CONTROL + OPTION + COMMAND + h: Alfred Highlight Syntax
• CONTROL + OPTION + COMMAND + k: Keymou (cursor highlight show/hide)
• CONTROL + OPTION + COMMAND + m: Moom (toggle)
• CONTROL + OPTION + SHIFT + m: Moom (open custom actions)
• CONTROL + OPTION + COMMAND + n: Notification Center (show/hide)
• CONTROL + OPTION + COMMAND + o: Alfred Open URL in default browser
• link:https://alchemists.io/articles/pixel_snap/#_shortcuts[PixelSnap]
• CONTROL + OPTION + COMMAND + r: Resolutionator (selector)
• CONTROL + OPTION + COMMAND + t: Alfred Large Type
• CONTROL + OPTION + COMMAND + w: Mission Control
• CONTROL + OPTION + COMMAND + ←: Keymou (move cursor left)
• CONTROL + OPTION + COMMAND + ↑: Keymou (move cursor up)
• CONTROL + OPTION + COMMAND + →: Keymou (move cursor right)
• CONTROL + OPTION + COMMAND + ↓: Keymou (move cursor down)
• CONTROL + OPTION + COMMAND + ENTER: Keymou (move cursor by division)
• CONTROL + OPTION + SPACE: OmniFocus (quick entry)
• OPTION + SPACE: Alfred (open)

💡 See additional link:https://saurabhs.org/macos-tips[tips] for details.

=== Newsyslog

Native to macOS, link:https://www.freebsd.org/cgi/man.cgi?newsyslog.conf(5)[newsyslog] can be used to configure system-wide log rotation across multiple projects. It’s a good recommendation to set this up so that disk space is carefully maintained. Here’s how to configure it for your system, start by creating a configuration for your projects in the +/etc/newsyslog.d+ directory. In my case, I use the following configurations:

• +/etc/newsyslog.d/alchemists.conf+

....

logfilename [owner:group] mode count size when flags

/Users/bkuhlmann/Dropbox/Development/Work/**/log/*.log 644 2 5120 * GJN ....

• +/etc/newsyslog.d/homebrew.conf+

....

logfilename [owner:group] mode count size when flags

/usr/local/var/log/**/*.log 644 2 5120 * GJN ....

These configurations ensure that logs are rotated every 5MB (5120KB). In order to test that these configurations are valid, run:

.... sudo newsyslog -nvv ....

If you don’t see any errors in the output, then your configuration settings are correct.

The last thing to do is to add a launch configuration to ensure the log rotations happen at regularly scheduled intervals. To do this create the following file: +$HOME/Library/LaunchAgents/com.apple.newsyslog.plist+. It should have the following content:

[source,xml]

Label com.apple.newsyslog ProgramArguments /usr/sbin/newsyslog LowPriorityIO Nice 1 StartCalendarInterval Minute 30 ----

That’s it. System-wide log rotation is setup for your projects.

=== Customization

While this project’s configuration is opinionated and tailored for my setup, you can easily fork this project and customize it for your environment. Start by editing the files found in the +bin+ and +lib+ directories. Check out the link:https://alchemists.io/projects/mac_os/#_customization[macOS Customization Documentation] for further details.

💡 The installer determines which applications/extensions to install as defined in the +settings.sh+ script. Applications defined with the "APP_NAME" suffix and extensions defined with the "EXTENSION_PATH" suffix inform the installer what to care about. Removing/commenting out these applications/extensions within the +settings.sh+ file will cause the installer to skip these applications/extensions.

== Development

To contribute, run:

[source,bash]

git clone https://github.com/bkuhlmann/mac_os-config.git cd mac_os-config

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/mac_os-config/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].