Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/mac_os

Shell scripts for automated macOS machine setup.
https://github.com/bkuhlmann/mac_os

homebrew macos-setup

Last synced: 9 days ago
JSON representation

Shell scripts for automated macOS machine setup.

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



:mac_os_defaults_link: link:https://macos-defaults.com[macOS Defaults]



= macOS



Shell scripts for automated macOS machine setup.



This project is a framework for automating the setup of a macOS machine. In order to illustrate the

potential of what this project can do, please see the companion

link:https://alchemists.io/projects/mac_os-config[macOS Config] project for details. The _macOS

Config_ project is an opinionated configuration which meets the needs of my development environment

but is also meant to serve as an example and guide for building your own personalized setup. Here is

how the two projects are meant to be used:



* *macOS* (this project) - The foundational framework for building custom macOS machine setups.

* *link:https://alchemists.io/projects/mac_os-config[macOS Configuration]* - The layer on top of

  this _macOS_ project which defines a custom machine implementation. The project is meant to be

  forked for as many custom machine setups as needed.



toc::[]



== Features



* Provides a command line interface, written in Bash, with no additional dependencies for

  installation and management of a macOS machine.

* Supports macOS boot disk creation for fresh install of operating system.

* Installs link:https://developer.apple.com/xcode[Xcode Command Line Tools].

* Installs link:http://brew.sh[Homebrew] formulas and casks.

* Installs link:http://www.apple.com/macosx/whats-new/app-store.html[App Store] software.

* Installs non-App Store software applications.

* Installs software application extensions.

* Installs dotfiles.

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

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

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

* Applies {mac_os_defaults_link}.

* Configures installed software.

* Supports restoration of machine backups.



== Requirements



. link:https://www.apple.com/macos/macos-sequoia[macOS 15.0.0 (Sequoia)]

. link:https://developer.apple.com/xcode[Xcode]



== Setup



To install, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/mac_os.git

cd mac_os

git checkout 19.0.0

----



== Usage



Run the following:



[source,bash]

----

bin/run

----



You will be presented with the following options (listed in order of

use):



....

Boot:

   B:  Create boot disk.

Install:

   b:  Apply basic settings.

   t:  Install development tools.

  hf:  Install Homebrew Formulas.

  hc:  Install Homebrew Casks.

   m:  Install Mac App Store software.

   a:  Install application software.

   x:  Install application software extensions.

  df:  Install dotfiles.

  np:  Install Node packages.

  rg:  Install Ruby gems.

  rc:  Install Rust crates.

   d:  Apply default settings.

  cs:  Configure installed software.

   i:  Install everything (i.e. executes all install options in order listed).

Restore:

   R:  Restore settings from backup.

Manage:

   c:  Check status of managed software.

   C:  Caffeinate machine.

  ua:  Uninstall application software.

  ux:  Uninstall application software extension.

  ra:  Reinstall application software.

  rx:  Reinstall application software extension.

   w:  Clean work (temp) directory.

   q:  Quit/Exit.

....



Choose option `i` to run a full install or select a specific option to run a single action. Each

option is designed to be re-run if necessary. This can also be handy for performing upgrades,

re-running a missing/failed install, etc.



The option prompt can be skipped by passing the desired option directly to the `bin/run` script. For

example, executing `bin/run i` will execute the full install process.



The machine should be rebooted after all install tasks have completed to ensure all settings have

been loaded.



It is recommended that the `mac_os` project directory not be deleted and kept on the local machine

in order to manage installed software and benefit from future upgrades.



=== Boot Disk



When attempting to create a boot disk via `bin/run B`, you’ll be presented with the following

documentation (provided here for reference):



....

macOS Boot Disk Setup

  1. Insert a USB drive (8GB or higher).

  2. Use Disk Utility to format as "Mac OS Extended (Journaled)".

  3. Use Disk Utility to set the schema, if available, as "GUID Partition Map".

  4. Use Disk Utility to label as "Untitled".

  5. Run this script to install the OS and create a bootable USB drive.



macOS Boot Disk Usage:

  1. Insert the USB drive, created above, into the machine to be upgraded.

  2. Reboot the machine.

  3. Press and hold the POWER key before the Apple logo appears.

  4. Select the USB boot disk from the menu.

  5. Use Disk Utility to delete and/or erase the hard drive including associated partitions.

  6. Use Disk Utility to create a single "APFS" drive.

  7. Install the new operating system.



macOS Boot Disk Recovery:

  1. Start/restart the machine.

  2. Press and hold the POWER key before the Apple logo appears.

  3. Wait for the macOS installer to load from the recovery partition.

  4. Use the dialog options to launch Disk Utility, reinstall the system, etc.

....



=== Customization



All executable scripts can be found in the `bin` folder:



* `bin/apply_basic_settings` (optional, customizable): Applies basic and initial settings for

  setting up a machine.

* `bin/apply_default_settings` (optional, customizable): Applies {mac_os_defaults_link}.

* `bin/configure_software` (optional, customizable): Configures installed software as part of the

  post install process.

* `bin/create_boot_disk` (optional): Creates a macOS boot disk.

* `bin/install_app_store` (optional, customizable): Installs macOS, GUI-based, App Store

  applications.

* `bin/install_applications` (optional, customizable): Installs macOS, GUI-based, non-App Store

  applications.

* `bin/install_dev_tools` (required): Installs macOS development tools required by Homebrew.

* `bin/install_dotfiles` (optional, customizable): Installs personal dotfiles so the system is

  tailored to your workflow.

* `bin/install_extensions` (optional, customizable): Installs macOS application extensions and

  add-ons.

* `bin/install_homebrew_casks` (optional, customizable): Installs Homebrew Formulas.

* `bin/install_homebrew_formulas` (optional, customizable): Installs Homebrew Casks.

* `bin/install_node_packages` (optional, customizable): Installs Node packages.

* `bin/install_ruby_gems` (optional, customizable): Installs Ruby gems.

* `bin/install_rust_crates` (optional, customizable): Installs Rust crates.

* `bin/restore_backup` (optional, customizable): Restores system/application settings from backup

  image.

* `bin/run` (required): The main script and interface for macOS setup.



The `lib` folder provides the base framework for installing, re-installing, and uninstalling

software. Everything provided via the link:https://alchemists.io/projects/mac_os-config[macOS

Config] project is built upon the functions found in the `lib` folder. See the

link:https://alchemists.io/projects/mac_os-config[macOS Config] project for further details.



* `lib/settings.sh`: Defines global settings for software applications, extensions, etc.



=== Troubleshooting



* *Pi-hole*: When using link:https://pi-hole.net[Pi-hole], you might need to temporarily disable

  prior to upgrading as you might experience various errors with Apple not being able to detect an

  internet connection which prevents the installer from working.

* *Recovery Mode*: When using the boot disk and the installer fails in some catastrophic manner,

  reboot the machine into recovery mode -- pass:[POWER] (Silicon) or

  pass:[COMMAND] + pass:[r] (Intel) buttons -- to download and install the

  last operating system used. Alternatively, you can also use pass:[COMMAND] +

  pass:[OPTION] + pass:[r] (Intel) to attempt to download the latest operating

  system.

* *NVRAM/PRAM Reset*: When using the boot disk, you might experience a situation where you see a

  black screen with a white circle and diagonal line running through it. This means macOS lost or

  can't find the boot disk for some reason. To correct this, shut down and boot up the system again

  while holding down pass:[OPTION] + pass:[COMMAND] + pass:[r] +

  pass:[p] (Intel) keys simultaneously. You might want to wait for the system boot sound

  to happen a few times before releasing the keys. This will clear the system NVRAM/PRAM. At this

  point you can shut down and restart the system following the boot disk instructions (the boot disk

  will be recognized now).

* *System Management Controller (SMC) Reset*: Sometimes it can help to reset the SMC to improve

  system speed. To fix, follow these steps:

** Shut down your Mac.

** Hold down pass:[CONTROL] + pass:[OPTION] on the left side of the keyboard

   and pass:[SHIFT] on the right side of the keyboard.

** After seven seconds, hold down the Power button as well.

** Release all keys after another seven seconds.

** Turn on your Mac.



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/mac_os.git

cd mac_os

----



== 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/versions[Versions]



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



== Credits



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