andreas/mac_os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d9497a2ba47fba5e42744cf3a6892e7f8ed4efdc
mac_os/mac_os-config/README.adoc
Andreas Düren c94070723b Initial setup: mac_os installer with custom config 
Contains both components needed for Mac setup:
- mac_os/: Installer scripts (from bkuhlmann/mac_os)
- mac_os-config/: Custom app configuration

Configured apps:
- Homebrew formulas: atuin, bash, ffmpeg, mas, mole, node, rename, ykman
- Homebrew casks: chromium, deepl, element, nextcloud, nova, proton suite, signal, transmit
- App Store: Affinity suite, Bitwarden, Final Cut Pro, Invoice Ninja, iWork, PastePal, xSearch

Usage: cd mac_os && ./bin/run

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 08:33:22 -06:00

523 lines
20 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
:toc: macro
:toclevels: 5
:figure-caption!:
= macOS Configuration
This project provides a highly 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://github.com/github/git-sizer[Git Sizer]
* 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/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://ollama.com[Ollama]
* 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://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://github.com/koalaman/shellcheck[ShellCheck]
* link:https://www.joedog.org/siege-home[Siege]
* 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.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://www.mozilla.com/en-US/firefox[Firefox]
* link:https://www.rogueamoeba.com/fission[Fission]
* 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://www.iterm2.com[iTerm2]
* 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://cocoatech.com[Path Finder]
* 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://manytricks.com/resolutionator[Resolutionator]
* link:https://flyingmeat.com/retrobatch[Retrobatch]
* 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://trymeeter.com[Meeter]
* 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/app/apple-store/id1494948845[Paletter]
* 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://appmap.io[AppMap]
* 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://rubyonrails.org[Ruby on Rails]
* 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/ruby-syntax-tree/syntax_tree[Syntax Tree]
* 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://atuin.sh[Atuin]
* link:https://github.com/nabijaczleweli/cargo-update[Cargo Update]
* link:https://dotenv-linter.github.io[Dotenv Linter]
* link:https://eza.rocks[Eza]
* link:https://jj-vcs.github.io[Jujutsu]
* 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 30.0.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 Utilities → Startup Security Utility from the main menu.
.. Select _Reduced Security_.
.. Quit the utility 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 Preferences
** Apple ID
*** Login (if not already).
*** Update avatar.
*** Configure iCloud.
*** Enable Find My Mac.
** Bluetooth
*** Reconnect keyboard, mouse, and earbuds.
** Sound
*** Disable _Play sound on startup_.
*** Disable _Play user interface sound effects_.
** Screen Time
*** Disable entire feature.
** 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_.
** Accessibility
*** Hearing
**** Enable _Turn off background sounds when your Mac is not in use._
** Appearance
*** Use _Light_ theme.
** Apple Intelligence & Siri
*** Disable _Listen for_.
*** Disable _Keyboard shortcut_ (use Alfred instead).
** Privacy & Security
*** Enable _FileVault_.
** Wallpaper
*** Select custom image from _Documents_.
** Spotlight
*** Disable _Help Apple Improve Search_. link:https://obdev.at/blog/what-happens-on-your-device-stays-on-your-device-until-it-doesnt[Details].
** Screen Saver
*** Use _Message_ with custom text.
** Battery
*** Click _Options_ and enable _Prevent automatic sleeping on power adapter when the
display is off_.
** Lock Screen
*** Set _Start Screen Saver when inactive_ for 5 minutes.
*** 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 _Launchpad and Dock_ and uncheck _Turn Dock Hiding On/Off_.
**** Select _Mission Control_ and assign `CONTROL + OPTION + COMMAND + N` to _Show Notification
Center_.
**** Within _Mission Control_, assign `CONTROL + OPTION + COMMAND + W` to _Mission Control_.
**** 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.
* Carbon Copy Cloner
** Rename old backup, create new backup, and schedule frequency.
* 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.
=== 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]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.apple.newsyslog</string>
<key>ProgramArguments</key>
<array>
<string>/usr/sbin/newsyslog</string>
</array>
<key>LowPriorityIO</key>
<true/>
<key>Nice</key>
<integer>1</integer>
<key>StartCalendarInterval</key>
<dict>
<key>Minute</key>
<integer>30</integer>
</dict>
</dict>
</plist>
----
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.
_TIP_: 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].
Reference in New Issue View Git Blame Copy Permalink