Posts

Setting up a Macbook for Software Development

I recently bought a Macbook Pro and had to spend the afternoon setting it up for local web development. I figured I'd jot down the steps and save someone some time!

Install Homebrew

If you develop on a Mac, Homebrew is most likely going to be your default package manager. Unless you have a good reason to use a different tool, Homebrew is what you need. It's very simple to install, and it will even prompt you to install XCode command line tools, which you'll definitely want to install (the equivalent of xcode-select --install). Here's your all-in-one command (also documented on Homebrew's website):

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

Configure Git

Next up, you'll want to configure the Git client, which was installed in the prior step. You can find all these instructions here on Github's website, but hopefully this can act as an abridged version for you.

Step 1: Generate an SSH key

I prefer using SSH to authenticate with Github and I highly recommend it. To generate a key, I'll normally just run ssh-keygen and then enter a custom keypath. It will likely be something close to /Users/<yourusername>/.ssh/github_rsa where github_rsa is our arbitrary name for the key we will use. It will generate a private key called github_rsa and a public key called github_rsa.pub (which you will add to your Github profile).

Step 2: Add your public SSH key to Github

Remember, you're adding your public key because through public key cryptography, Github can verify your private key with just a matching public key.

Go to Settings > SSH and GPG Keys and add your new public key (github_rsa.pub).

Step 3: Add your private key to the SSH Agent

First, run eval "$(ssh-agent -s)" to start the SSH agent.

Important: if you're on macOS Sierra 10.12.2 or above, you'll need to take one intermediate step to make sure the keychain is updated each time you open your terminal.

If it doesn't already exist, create a file at ~/.ssh/config (you can use touch ~/.ssh/config). Now, open that file up and add the following:

Host *.github.com
  AddKeysToAgent yes
  UseKeychain yes # Omit this line if you didn't add a passphrase to your key 
  IdentityFile ~/.ssh/github_rsa # or whatever you decided to name your private key

Now, add your private key to it with the following command, replacing the path according to your computer:

ssh-add /Users/<yourusername>/.ssh/github_rsa

# If you selected UseKeychain above, you'll run this command *instead*
ssh-add --apple-use-keychain /Users/<yourusername>/.ssh/github_rsa

Step 4: Setup your global git config

You'll generally want to add your name and email to your global git config for purposes of identifying your user for git commits. You can do it with 2 commands:

git config --global user.name "Zach Gollwitzer"
git config --global user.email your.email@email.com

And then run git config --list to see all your settings.

Step 5: Clone your first repo

You're all set! You can now clone any repo you want:

git clone git@github.com:some-github-profile/some-repository.git

Install VSCode

You can install whatever text editor / IDE you want, but this post will focus on VSCode. Go ahead and download VSCode here.

Setup command line shortcut

Once downloaded, open up the app, run CMD + p, and type >shell command. Click the option to install the command to your PATH variable.

You should now be able to run the command code /some/path/to/repository to open an entire folder in VSCode.

Add your user settings

If you're coming from another computer, you'll probably have a bunch of setting in the settings.json file, which controls your VSCode experience. To access this file, hit CMD + p and then type, >Preferences: Open User Settings (JSON). If you don't have one, here are some decent defaults that I use myself (I have the Prettier extension installed):

{
  "workbench.startupEditor": "none",
  "workbench.colorTheme": "Panda Syntax",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
}

Setup .zshrc

Quick note: I have linked to several tutorials on Bash, which is very similar to ZSH and most concepts will overlap. The reason we're using ZSH here is because it's the Mac default.

Another quick note: In your Homebrew setup above, a file called .zprofile was created, which is very similar to .zshrc except it runs on login while .zshrc runs on new shell creations. It is okay to have both.

You may not need it immediately, but it's always good to setup your .zshrc file so you can modify things like the PATH variable in the future. If you need a refresher on all this, I wrote a detailed post about the PATH variable.

Go ahead and create it with the touch ~/.zshrc command.

Once created, open it up in Vim with vim ~/.zshrc and you can add some defaults to it. Here's what I usually put in my .zshrc on a fresh computer. You can customize it a lot further than this and I usually end up exporting all sorts of shortcuts and environment variables from this file for convenience.

# Path shown in terminal will only show current directory
export PS1="%1d $ "

# Path modifications
export PATH=$PATH:$HOME/bin

# Aliases
alias ll='ls -la'

Once the file is saved, run source ~/.zshrc to apply the changes. You only need to do this once as it will apply on startup of the terminal next time.

Install JavaScript stuff

If you program in a language other than JavaScript, you'll likely skip this entire section and install different types of packages. But for you JavaScript devs, here's the checklist:

Install NVM Node.js Version manager

To write any sort of JavaScript, you'll need Node.js installed, and I prefer doing so through nvm which allows me to quickly switch between Node versions and set a preferred version (rather than downloading all of them separately and setting up manual path aliases). Here are the NVM docs, but really, all you need are the following commands:

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

# Pasting this entire command will add nvm to your PATH variable in .zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

# Verify installation
command -v nvm

Now, install your preferred Node version and set it as your default.

# A shortcut to download the LTS version
nvm install --lts

# List installed versions
nvm ls

# Set "the latest LTS version" as your default Node version for new shells
nvm alias default lts/*

Install Yarn

This is optional, but I prefer yarn over npm as it is much faster. Install it with the following command:

# Install Yarn
npm install -g yarn

# Check that it is installed 
yarn -v

Install Docker

Sure, it eats up computer resources, but let's be real, Docker is a must-have (great local databases and much more). I recommend installing both Docker Desktop and the VSCode plugin:

  1. Docker Desktop download
  2. Docker VSCode plugin