MacBook Setup Guide

This is a detailed step-by-step guide to help you setup a new MacBook Pro. Before we start, please take note of the following items:

It is assumed you are using the latest model of MacBook Pro (at least after 2016).
It is also assumed that you have installed the latest version of MacOS (at least 10.12 Sierra).
This guide is tailor-made for a developer or software engineer's personal laptop.
- In other words, we would install the required tools for personal development. However, we would not focus on tools that are organization-specific.
This guide is also customized for certain region (Asia/Singapore) & languages (English and Mandarin).

Background

At the time of writing, I am a Computer Engineering undergraduate at the National University of Singapore as well as a software development enthusiast.

One day, I received an email from Apple with the title "Important information about your MacBook Pro". It said that my MacBook has an issue that may result in data loss and failure of the drive (SSD). See this page for more information. Apple offered to provide a service program to fix this problem (by updating the driver firmware) free of charge. So I registered and sent the device to an Apple Authorized Service Provider - A.Lab.

I am aware that all data will be erased after the service. However, I am fine with that since almost all important data on my device have been backed up. Nonetheless, I still need an SOP (standard operating procedure) to setup (or re-setup) my MacBook after the service. Thus, I decided to document this process here.

Please notice this guide is opinionated. The following philosophical rules are enforced:

Be stingy: install the minimal set of tools you need. Whenever a new software is installed, a new potential vulnerability is introduced.
Be Apple's fan: use tools provided by Apple by default (opt to an external tool only when absolutely necessary). For example, we use iTerms 2 rather than the default terminal. However, we would stick with the default bash and never use zsh.

Steps

Create a new user account on MacOS:
- This should be done when you turn on your device for the first time;
- Set this account as an administer;
- The full name field should be your full real name in English (use a single space to separate each word, first letter of which should be captialized);
- The account name field should be your first name in English (all lowercase, alphanumeric only);
- Do not leave the password blank;
- Do not leave the hint field blank as well.
If this is not the first time you turn on the device, and you want to change the name of your account:
- Log into the admin account;
- Open System Preferences -> Users & Groups;
- Click the lock icon and enter admin password;
- Click the plus icon to create a new account;
  - Follow the instructions in Step 1.
- Log out and then log into the account created just now;
- Delete the old account;
- Go to System Preferences -> Sharing, change your bluetooth name;
  - Decide whether you want to delete that account's home folder.
- Alternatively, see this guide from Apple for more details.
Now, you should have signed in with the "right" admin account. Go to System Preferences -> Users & Groups and:
- Make sure there is only one account (the one you are using now), except for at most one guest account;
- Change the profile picture of the current account.
Connect to your favorite WiFi network.
Everything is done with account part. Now, re-open System Preferences and:
- Go to Language & Region, change first of the week to Monday and tick the 24 hours;
  - You may want to change the language here. If so, restart the device after the change.
- Go to iCloud, log into your Apple iCloud account;
  - It is important to do this step here, since this will sync your personalized data to this device.
- Go to Dock, un-tick Show recently used applications;
- Go to Mission Control -> Hot Corners, set the right-bottom corner to trigger sleep;
- Go to Security & Privacy -> Firewall, turn on the firewall;
- Go to Display -> Night Shift, turn on and choose 01:00 - 07:00;
- Go to Keyboard -> Input Method, select Chinese Pinyin and English;
- Go to Date & Time -> Clock, tick to show date.
You may need to re-start the device now.
Open the Safari browser and:
- Verify the favourite items are synced correctly;
- Go to the following websites and sign in on this device for the fist time:
  - Google, Facebook, LinkedIn, GitHub, Outlook, Amazon, ...
  - You may need to have either your Phone, Google Authenticator or Authy with you for 2FA purpose.
- Open Safari Preferences:
  - Go to Privacy, tick no tracking scripts;
  - Go to Advanced, tick show development menu item.
- Install the following plugin for Safari browser:
  - AdBlock for Safari, Octotree (see here), ...
  - Add a Personal Access Token for Octotree.
- Re-open the Safari browser after that.
Open Finder -> Preferences and:
- Go to General and select <account name> when opening a new Finder window;
- Go to Sidebar and tick <account name>;
- Go to Advanced and tick show all extensions, remove items in trask after 30 days and show folders on the top.
Open Others -> Terminal and run xcode-select install.
Open Others -> Terminal and install Homebrew (the package manager) and Homebrew Cask:

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

Switch the default terminal to bash and disable ZSH warning message:

chsh -s /bin/bash
export BASH_SILENCE_DEPRECATION_WARNING=1

Install iTerm 2 using Homebrew brew install iterm2:
- Drag iTerm 2 to the Dock for convenience;
- Close the terminal and open iTerm 2 instead;
- Open iTerm 2 -> Preferences:
  - Go to General -> Closing, tick Quit when all windows are closed;
  - Go to Profiles -> Default and:
    - Go to Colors -> Color Presets, select Solarized Dark;
    - Go to Text, select Blinking cursor and change font size to 13;
      - We suggest to use Meslo LG for Powerline - Regular (download from here).
    - Go to Window, change Transparency and Blur to an an appropriate value.
- Go to Shell -> Broadcast Input and select Show Background Pattern Indicator;
- Make iTerm 2 to be the default terminal;
- Set the tab complete to be case-insensitive echo 'set completion-ignore-case on' >> ~/.inputrc;
- Make sure your bash shell is colorful echo 'export CLICOLOR=1' >> ~/.bash_profile;
- Make sure your Vim is colorful as well curl -fsSL https://raw.githubusercontent.com/yunpengn/MacBook/master/.vimrc -o ~/.vimrc;
Configure your local SSH client:
- Create a new SSH key ssh-keygen -t rsa -b 4096 -C "your_email@example.com".
- See your public key by cat ~/.ssh/id_rsa.pub;
- Create a file at ~/.ssh/config and add commonly used server configurations inside, in the following format:

Host *
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_rsa

Host <server-name>
    HostName <ip_address_or_domain_name>
    IdentityFile ~/.ssh/id_rsa
    User yunpengn

Install Google Chrome using Homebrew brew install google-chrome:
- Drag Chrome to the Dock for convenience;
- Install the following plugin for Chrome:
  - AdBlock, Octotree, ...
- Open Chrome -> Preferences and:
  - Show Home button and set homepage to https://www.google.com.sg/;
  - Use web service to detect spelling errors;
  - Send No Tracking requests;
  - Enable Developer Mode for extensions.
Install Sublime Text using Homebrew brew install sublime-text:
- Drag Sublime to the Dock for convenience;
- Go to Tools -> Install Package Control.
Install Cyberduck using Homebrew brew install cyberduck:
- Add the commonly used SSH servers;
- You can install Filezilla instead.
Create a Projects folder by mkdir ~/Projects.
- Later, you can clone your repositories to here.
Configure your local git by:
- Setup the name by git config --global user.name "<value>".
- Setup the email by git config --global user.email "<value>".
- Always push tags along to remote repositories by git config --global push.followTags true.
Install the following applications based on your needs:
- Onedrive, QQ, WeChat, ...

Java Development Environment

Install the latest version of Oracle JDK by brew install oracle-jdk.
- We don't use an older version of Java because we prefer latest features. However, it is permitted to use the LTS version if the latest one is not;
- We don't use OpenJDK because previous experiences show that it could cause issues such as missing certificate.
Install IntelliJ IDEA Ultimate by JetBrains by brew install intellij-idea.

Node.js & ECMAScript Development Environment

Install the latest version of Node.js runtime by brew install node.
Install WebStorm by JetBrains by brew cask install webstorm.

Swift Development Environment

Install Xcode (bundled with Swift, iOS & macOS SDK) from App Store.
Go to Xcode -> Preferences:
- Go to Accounts, sign into your Apple ID (bundled with Apple Developer account);
- Go to Navigation, select Uses Focused Editor as Navigation option.

Python Development Environment

Use the Python 3 built into MacOS, and do NOT install using HomeBrew or the installer from python.org.
- Python 2.7 has come to its end-of-life as of January 1, 2020. Never use Python 2 anymore unless necessary.
- Do NOT add alias to point python to python3, as this can be confusing. Instead, just use python3 and pip3.
Install PyCharm by JetBrains by brew install pycharm.
To use Pipenv for dependency management:
- Install Pipenv by brew install pipenv.
To use venv and pip for dependency management:
- Create a new virtual environment for your project by python3 -m venv .env/;
- Activate the virtual envrionment created by source .env/bin/activate;
- Install dependency inside the virtual environment by pip3 install -r requirements.txt.
Never use easy_install as it has been deprecated.

Go Development Environment

Install the latest version of Go by brew install go.
Install GoLand by JetBrains by brew install goland.
- Go to Preferences -> Plugins -> Installed, disable IDE Features Trainer.
- Go to Preferences -> Tools -> File Watchers, add go fmt.
Setup the necessary environment variables in ~/.bash_profile:

# Adds path variables for Go development.
export GOPATH="/Users/<account name>/gopath"
export PATH="/Users/<account name>/gopath/bin:$PATH"

MySQL Development Environment

Install the latest version of MySQL server by brew install mysql.
Start the MySQL instance at the background via brew services start mysql.
Secure the MySQL instance with mysql_secure_installation:
- We recommend to use the same password as MacOS login password;
- For local development, it is fine to not use the VALIDATE PASSWORD component;
- After that, you can login as root with mysql -u root -p (for password prompt).
Create a new MySQL user with the same username as MacOS account:
- We give all privileges to this account. However, we only allow login from localhost;
- Login as root with mysql -u root -p;
- Create a new user by CREATE USER '<username_here>'@'localhost' IDENTIFIED BY '<password_here>';;
- Grant all privileges by GRANT ALL PRIVILEGES ON *.* TO '<username_here>'@'localhost';;
- You can try to login now with mysql -p.
Install a MySQL client with GUI, Sequel Pro by brew cask install sequel-pro.

PostgreSQL Development Environment

Install the latest version of PostgreSQL server by brew install postgresql.
Start the MySQL instance at the background via brew services start postgresql.
This installation should help you create a superuser with the same username as MacOS account, but with no password. To change the password:
- First, connect to the database by psql template1, where template1 is the template database shipped with PostgreSQL;
- Change password by ALTER USER <username_here> PASSWORD 'new_password_here';;
- Now, remove the default database created by DROP DATABASE postgres;;
- Then, create a new database with the same name as MacOS account by CREATE DATABASE <username_here>;.
Install a PostgreSQL client with GUI, Postico by brew cask install postico.

Latex Writing Environment

Download MikTex from here.
- Different from most online guides, we do NOT use MacTex;
- Make a private installation so that MikTex is only accessible to the current user;
- Add the folder ~/bin/ to the current user's path variable.
Make sure the latest version of Sublime Text 3 has been installed on your laptop.
- There is no need to install any extra package(s) because LatexTools is shipped together with Sublime in the recent versions.
Create a build system for Latex by Tools -> Build System -> New Build System...:

{
    "shell_cmd": "pdflatex \"${file}\"",
    "selector": "text.tex.latex"
}

Optionally, you may want to install Skim for reverse search capability.

Virtual Machine Usage

VirtualBox is our only recommended solution for VM management on MacOS.
- Install from Homebrew by brew install --cask virtualbox.
Most times, you would need its extensions pack as well.
- Install from Homebrew by brew install --cask virtualbox-extension-pack.

Licence

GNU General Public Licence 3.0

yunpengn / MacBook