Mac Setup

Bash shell

On Mac OS, you already have a bash shell installed! However, depending on your OS version, you may have a different default shell (e.g., zsh).

To check your default shell, open a terminal and type echo $SHELL. If the output reads /bin/bash, you are all set!

If the output is something else (e.g., /bin/zsh), we strongly recommend changing your default shell to bash for this course. To do so,

Run:
```
chsh -s /bin/bash
```
Enter your password when prompted.
Close and re-open the terminal.
Run echo $SHELL again to confirm it now shows /bin/bash.

All instructions in the course will assume you are using bash.

Note: After the course, you can switch back to your original shell using chsh -s /bin/zsh (or whatever your original shell was).

Homebrew

Install the Homebrew package manager: open a terminal window, type this command, then press Enter:

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

Git

You may already have it! Open a terminal and type git --version.

If this prints something like git version X.XX.X, git is already installed! If so, skip to the next section on “Git configuration”.

If git is not installed, then you might get a pop-up window prompting you to install the Xcode Command Line Tools, which we will not do: click “Cancel”. We will install git with Homebrew instead.

In the terminal, run:

brew install git

(If you already installed git through the Xcode Command Line Tools, don’t worry, that is fine.)

Verify the installation by running git --version: this time you should see something like git version X.XX.X.

Git configuration

If you have never used Git on your computer, you may have to configure it. The following instructions assume you have already created a GitHub account following the main Setup page.

Type the following commands in a terminal.

Notes:

For user.email, use the email associated with your GitHub account.
user.name can be any name you want to use to author your commits, but we recommend using the display name on your GitHub profile.

git config --global user.name "Jane Doe"  # Set the author name for your commits
git config --global user.email "janedoe@example.com"  # Set the email linked to your commits
git config --global core.autocrlf input  # Automatically standardize line endings when committing
git config --global init.defaultBranch main  # Make new repos use "main" as the default branch name
git config --global pull.rebase false  # Make "git pull" combine changes using merge by default

Tip: You can check your Git configuration at any time with: git config --list

Create an SSH key for GitHub

When following the GitHub docs in the steps below, make sure to select the Mac instructions at the top of the page.

To authenticate to GitHub from the command line, you will use an SSH key pair, which is more secure than using your GitHub account password directly.

In a terminal, check if you have existing SSH keys in the ~/.ssh directory. A public/private key pair typically has the filename format id_ALGORITHM and id_ALGORITHM.pub. If you have existing key files, use a different, custom name for your SSH key pair in step 2.
Generate a new SSH key and add it to the ssh-agent.
- Use the default file location for saving the key, unless you already have existing keys - in this case, replace just the id_ALGORITHM (e.g., id_ed25519) part of the file location with an informative keyname like id_ed25519_github
- Store your passphrase in a secure location, as you will need to use it for certain Git commands
Confirm your key pair was created by running the command:
```
ls -la ~/.ssh
```
You should see two files with your key name, one with .pub (the public key) and one without (the private key - do not share or copy this file!).
Add the SSH key to your GitHub account.
- Be careful when copying/pasting the public key to not accidentally add spaces or newlines
- Choose Authentication Key for the key type
Locally specify the SSH key to use when connecting to GitHub, so that the right "identity" is always used for local Git operations (useful when you have multiple keys).
1. Run the following command (if you used a custom key name, replace id_ed25519 with your private key's filename):
```
printf 'Host github.com\n  User git\n  IdentityFile ~/.ssh/id_ed25519\n  IdentitiesOnly yes\n' >> ~/.ssh/config
```
2. Then, check that the config was added:
```
cat ~/.ssh/config
```
  You should see something like:
```
Host github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
```

In this course, when using a Git command that prompts you for your passphrase, enter the passphrase you set for your private key in step 2.

VSCode

On this page, follow all steps in the following two sections only:
- Install VS Code on MacOS
  - To begin the download, click on the “Download Visual Studio Code” link
- Launch VS Code from the command line
  - Use the method “Configure the path with VS Code” to set up the code command in your terminal
You can skip all other sections on that page.
To confirm that everything worked, open a terminal and type code . (include the period). This should open the current directory in a VSCode window.

NOTE: The first time you run code . in a folder, you may see a popup asking "Do you trust the authors of the files in that folder?"

Select "Yes, I trust the authors", and if available, also check the box that says "Trust the authors of all files in the parent folder". This will enable full features and extensions in your VSCode workspace.

VSCode extensions

Open the Visual Studio Code application.
Open the Extension side panel by pressing Cmd+Shift+X. In the search bar at the top of this panel search for each of the following extensions and press Install for the first entry that appears.

Required extensions

Python Extension Pack (note: you will need to reload VSCode after installing this)
Jupyter
Docker
WSL (only if you're on Windows)

Setting up GitHub Copilot in VSCode

In any VSCode window, click the Copilot icon near the bottom right corner of the bottom status bar and select "Use AI Features", then follow the prompts to sign in using GitHub.

Copilot status bar

This will give you access to the Copilot Free plan in VSCode.

To open the Copilot chat, go to View > Chat.

Reference: https://code.visualstudio.com/docs/copilot/setup

Python

Open a new terminal and type the following command, then press Enter.
- If you are on an Apple Silicon Mac (upper left corner Apple menu -> About This Mac says something like Chip: Apple M1 (or M2, etc.)):
```
 curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
```
- Otherwise:
```
 curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
```
Run the installation script you just downloaded.
- If you are on an Apple Silicon Mac, run:
```
 bash Miniconda3-latest-MacOSX-arm64.sh
```
- Otherwise:
```
 bash Miniconda3-latest-MacOSX-x86_64.sh
```
- A license agreement will be displayed and the bottom of the terminal will read --More--. Press Enter or the space bar until you are prompted with Do you accept the license terms? [yes|no]. Type yes and then press Enter.
- The installer will show a default installation directory (e.g., /Users/$USER/miniconda3). Leave this default and press Enter.
- When you are asked Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no], type yes and press Enter.
- Exit the terminal once the installation has finished.
Re-open a terminal. Type which python into the terminal and check that it returns a path like: /Users/$USER/miniconda3/bin/python.
- If you do not see a path like this, try typing conda init, closing your terminal, and repeating this step. If your issue is still not resolved, skip the following step and contact an instructor on the #help-installation channel of the QLS612-BHS Slack.
Type the following to remove the installation script that was downloaded:
- If you are on an Apple Silicon Mac:
```
 rm ./Miniconda3-latest-MacOSX-arm64.sh
```
- Otherwise:
```
 rm ./Miniconda3-latest-MacOSX-x86_64.sh
```

Python packages

Open a terminal and type the following commands (press Enter after each):

conda config --append channels conda-forge  # add conda-forge as a source for packages (channel)
conda config --set channel_priority strict  # prioritize packages based on channel order
conda create -n qlsc612 -y python=3.12 flake8 jupyter nilearn scikit-learn pandas matplotlib seaborn bokeh statsmodels plotly wordcloud
conda activate qlsc612

This installation step (conda create) will take a couple minutes. The above commands create a new conda Python environment named qlsc612 with all the necessary packages installed for this course. The last line, conda activate qlsc612, will activate this Python environment (the default environment is base).

Once the commands have finished running, you should see (qlsc612) at the beginning of your shell prompt to indicate that the new environment is active.

Docker

Go to this page and press the button Docker Desktop for... corresponding to the chip of your machine (see the image below).
Open the Docker.dmg file that is downloaded and drag and drop the icon to the Applications folder.
Open the Docker application and enter your password. An icon will appear in the status bar in the top-left of the screen. Wait until it reads Docker Desktop is now up and running!
Open a new terminal and type docker run hello-world. If the installation worked, a brief introductory message should be printed to the screen.

The above step-by-step Docker instructions are distilled from here. If you have questions during the installation procedure please check that link for potential answers!

Install the `tree` command

tree is a helpful command for viewing directory structures, and is strongly recommended.

Open a terminal, and check if you have tree already installed by running tree --version.
- If you see a version number, you’re all set!
- If you see a message like tree: command not found, install it by running:
```
 brew install tree
```