Introduction

This repository is a resource to help me setup and maintain my Mac. It takes the effort out of installing everything manually, but still requires manual setup of each app given starting from scratch. Everything needed to install my preferred setup of macOS is detailed here. Please see the Before Installing section before moving forward with these dotfiles.

Note

The default setup of these dotfiles are highly focused on web development, but can be customized otherwise for your specific stacks.

Setup

These instructions are for setting up new Mac devices. It is a highly optimized and configured setup specifically tailored to myself. It works through 5 main scripts that generate a system that is configured to the highest possibility without manual intervention. However, a lot of manual setup is required to get to a working state. Most of the manual setup I'm referring to is just logging into applications. All of my config is either stored in the cloud or through syncing capabilities of the applications themselves.

Post setup will mainly involve doing necessary setup including starting all the new applications, allowing applications to be run through MacOS security, signing in, and moving some things around to your liking. This will mainly be documented in the ./docs/app-specific-setup and the ./docs/macos-defaults.md.

The install will also require you to type in your system password at different points in the install to move forward with the necessary installation.

Setup Notes

• Neovim config is included in ./.config/nvim/ however I recommend that you start fresh with the LazyVim default configuration and add from my config when you want necessary features. The LazyVim instructions are found here.
• When installing the brew bundle the tailscale, zoom, and timemachineeditor packages all require passwords regardless of pre sudo configuration.
• Inside the .mac.sh script there is a default to use TouchID on sudo. This won't work on a desktop Mac unless you have the TouchID keyboard.

Create a separate volume to test install (optional)

After you've set up your new Mac you may want to wipe and clean install your old Mac. Follow Installing macOS on a separate APFS volume - Apple Support to do that. Don't forget to backup before messing with Disk Utility.

Backup your data

If you choose to not do a separate volume definitely create a backup before completing the install.

What's inside

A lot of stuff. Seriously, a lot of stuff. Check them out in the file browser above and see what components may mesh up with you. Fork it, remove what you don't use, and build on what you do use.

Components

There's a few special files in the hierarchy.

• .config/: Anything in .config/ will get added to your $PATH and be made available everywhere. This contains specific tooling configuration that will also be available once the Brewfile has completed bundling.

• .ssh/: Houses our SSH config as well as our 1Password Agent for logging in with 1Password for created SSH keys.

• docs/: Any defaults not able to be configured with our dotfiles is listed in this folder as well as other Mac apps.

• docker/compose: Contains collection compose files over some time that I keep as a reference and to run compose files out of using Orbstack.

• icons/: This contains icons that are used for the main applications that are added to the Dock array.

• scripts/tools.sh: Important tooling necessary for web development and terminal efficiency. This step also executes our Brewfile. To note Corepack is enabled by default. If you aren't familiar with Corepack see the Node.js documentation. It includes optional global packages, but we are not using those in favor of run scripts.

• scripts/dots.sh: The dotfile run script. This is where we install and configure all the apps we use.

• scripts/mac.sh: mac.sh is a simple script that installs some sane macOS defaults, and so on. Some of the settings aren't able to be set through this method, look to the macos-defaults.md file for more settings to be set manually. Tweak this script, and occasionally run ./scripts/mac.sh from the dotfiles source directory from time to time to keep your environment fresh and up-to-date. A great resource to look at for considering some defaults for your own dotfiles is MacOS Defaults.

• scripts/ssh.sh: Creates an SSH key for the new machine. Otherwise login through the Github CLI to begin using git.

• Optional script - scripts/fonts.sh: Installs and configures all Google fonts. It is a large install, but helpful for designing.

• Optional script - scripts/apps.sh: This adds the necessary applications to be persistent in the Dock. Intentionally not included in the dots script because not all persistent apps are included in the Homebrew bundle installation. You can edit this to add your persistent apps and run post installation of all necessary apps.

These can be run post install using:

sh ~/.dotfiles/scripts/fonts.sh
sh ~/.dotfiles/scripts/apps.sh

Before Installing

If you want to start with your own dotfiles from this setup, it's pretty easy to do so. First of all you'll need to fork this repo. After that you can tweak it the way you want.

1. Go to the .mac file and adjust the system and network name to your preferred system name.

2. Check out the Brewfile file and adjust the apps you want to install for your machine. Use their search page to check if the app you want to install is available. There is also some Mac App Store specific apps included in this Brewfile which require you to be signed in to an Apple Account.

3. Go to .config/git/.gitconfig and update your preferred git configuration.

Install

After backing up your Mac you may now follow these install instructions to setup a new one.

1. Update macOS to the latest version through system preferences (if not updated already)

2. Clone this repo to ~/.dotfiles with:

   git clone --recursive https://github.com/frankievalentine/dotfiles.git ~/.dotfiles

   💡 PLEASE GO THROUGH 'BEFORE INSTALLING' SECTION ABOVE AFTER CLONING. You could choose a different location than ~/.dotfiles (not recommended). If you do change the location please be sure to update the dots.sh script to the correct folder location.

3. Remove the .git folder from the dotfiles ~/.dotfiles clone to begin your own version control repository.

      rm -rf ~/.dotfiles/.git

4. Create a new .git repository

      git init ~/.dotfiles

5. Install Homebrew & Command Line Tools. We want to download the Command Line Tools directly from Apple Developer.

      # Homebrew
      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   💡 Make sure to run the commands Homebrew provides after install.

6. Install GNU stow using Homebrew.

      brew install stow

7. Symlink the .dotfiles repo to your home folder using GNU stow.

      cd ~/.dotfiles
      stow --adopt .

8. Run the installation with:

      sh ./scripts/dots.sh

9. Add headline oh my zsh theme, remove oh my zsh generated .zshrc

      mv ~/.dotfiles/.oh-my-zsh/themes/headline.zsh-theme ~/.oh-my-zsh/themes
      rm .zshrc
      mv .zshrc-pre-oh-my-zsh .zshrc
      source .zshrc

Your Mac is now ready to use!

Bugs

I want this to work for everyone. That said, I do use this as my dotfiles, so there's a good chance I may break something if I forget to make a check for a dependency.

If you're brand-new to the project and run into any blockers, please open an issue on this repository and I'd love to get it fixed for you!

---

Enjoy!