MacOS setup

This setup has been tested on macOS Ventura 13.2.1 and Apple M2 Chip. The approach is primarily based on the instructions provided by @danielnachun and tested by @XuanLu.

Step 1

Backup your current Shell configuration file

cp ~/.zshrc ~/zshrc.backup

OPTIONAL:

For those already installed iTerm but NOT via Homebrew

You would want to install iTerm from Homebrew. Uninstall it before you proceed:

  1. Delete the iTerm2 Application
  • Open Finder.
  • Navigate to the Applications folder.
  • Find iTerm2 and drag it to the Trash.
  1. Remove Associated Files

Open a terminal and run the following commands to remove iTerm2’s associated files and directories:

rm -rf ~/Library/Application\ Support/iTerm2
rm -rf ~/Library/Preferences/com.googlecode.iterm2.plist
rm -rf ~/Library/Caches/com.googlecode.iterm2
rm -rf ~/Library/Saved\ Application\ State/com.googlecode.iterm2.savedState
rm -rf ~/Library/Logs/iTerm2

Finally, you may want to empty your trash before you proceed.

For those who already installed Micromamba or Homebrew, but not through our system

  1. Uninstall Micromamba
rm -rf ~/micromamba
  1. Uninstall Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
  1. Remove Associated Configuration Files
rm -rf ~/.bashrc ~/.bash_profile ~/.zshrc ~/.zprofile ~/.mambarc ~/.micromamba
  1. Remove Caches and Logs
rm -rf ~/Library/Caches/Homebrew
rm -rf /Library/Caches/Homebrew
rm -rf /usr/local/Homebrew
  1. Clean Up Remaining Directories
rm -rf /usr/local/var/homebrew
rm -rf /usr/local/etc/bash_completion.d/brew
rm -rf /usr/local/share/doc/homebrew
rm -rf /usr/local/share/man/man1/brew.1
rm -rf /usr/local/share/zsh/site-functions/_brew

Restart your Terminal, and you should be ready to go.

Step 2

Install Homebrew

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

You may be prompted to run these two lines:

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/ra/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"

Run them as directed to add Homebrew to your PATH.

Step 3

Install iTerm2 using Homebrew

brew install --cask iterm2

Step 4 (Optional, but required if you are running Step 5)

Install special fonts to render unicode icons on the terminal:

brew install --cask font-meslo-lg-nerd-font

and download terminal color theme at: https://github.com/tinted-theming/base16-iterm2/blob/main/itermcolors/base16-one-light-256.itermcolors *After download, go to your iTerm2 settings –> profiles –> colors –> color presets –> select import –> import the downloaded .itermcolors file. Be sure the file is named properly (i.e., Apple may automatically add .txt to the file name, delete .txt)

Also in profiles, select text –> font –> choose one of the Meslo Nerd Font you’ve downloaded.

Step 5 (Optional, use with caution)

Configure the system using a one-liner command,

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply danielnachun

If prompted, select all-overwrite.

This should install micromamba and the Script of Scripts (SoS) suite by one run. It will take a while. Please note that it is recommended to use R managed by micromamba but you are also welcome to remove it via micromamba uninstall, if you strongly prefers to work with your existing R program.

TESTING NOTE (XuanLu):

If you receive message such as wd:source: no such file or directory: /Users/ra/.local/share/zinit/snippets/OMZP ::wd/wd.sh after you finish running the one-liner command and reinitiate Terminal, navigate to you home folder (open Finder, Command + Shift + H), unlock hidden files (Command + Shift + .), open the .zshrc file, find zinit snippet OMZP::wd, and comment it out.

Step 6

Finish configuring R in the micromamba environment that you installed, for example:

micromamba activate <your_environment>
micromamba install r-pacman -y
R --slave -e "remotes::install_github('jalvesaq/colorout')"

where <your_environment> is placeholder for the micromamba environment you built above for the SoS suite in Step 6.

Some comments on MacOS initialization

  1. The Mac Magic Mouse may feel either too sensitive or sluggish by default. You should tweak it in Settings by configuring the tracking speed. Otherwise, you can use Mac Touchpad or a regular PC mouse.

Docker on Mac

We use Docker a lot running various software that are hard to install. SoS also provides an interface to run Docker images.

Install Docker and colima

In Step 5, Docker should have already been installed. If not, you can install it via

brew install docker

It is strongly recommended using colima to run docker. To install:

brew install colima

Then start Colima with defaults: ​

colima start

​ After colima started (the above command completed executing), you can use docker command on macOS after colima start with no additional setup. ​

Run Docker containers

​ Here a demonstration to use Colima to create and run a Docker container from the gaow/bioinfo` image on MacOS: ​

  1. Start Colima if it’s not already running: ​ 
    colima start --cpu 6 --memory 8 --runtime docker

    ​

  2. Create a container from the image and start it: ​ 
    docker run -it --name gaow_demo gaow/bioinfo /bin/bash

On MacOS with Apple Silicon (M) CPU chips,

docker run -it --platform linux/amd64 --name gaow_demo gaow/bioinfo /bin/bash

​ This will automatically download the image the first time you use it, then start a container from the image — which was called gaow_demo in the command above — in interactive mode with a bash shell environment. You can now run commands inside the container. ​

  1. When done, type exit to exit the container shell. The container will stop but still exist. ​
  2. To reenter the container that you quitted: ​ 
    docker start -ai gaow_demo

    ​

  3. To close the container: ​ 
    docker rm gaow_demo

Singularity on Mac

Singularity is an alternative to Docker as a container platform to run various software in a portable and reproducible way. SoS also provides and interface to run Singularity images.

To install Singularity please follow these steps on Apple Silicon Chip.

To run Singularity images, assuming you have previously installed colima (see section above “Docker on Mac”), you can first create a virtual machine using:

limactl start template://apptainer-rootful --set='.cpus = 8 | .memory = "16GiB" | .disk = "20GiB"'

where you can adjust the .cpus, .memory and .disk arguments based on specification of your computer.

Then you can run a singularity image — for example bioinfo.sif — using:

limactl shell apptainer-rootful apptainer exec bioinfo.sif [command you would like to run]

Notice that the SoS workflow system will use singularity exec to run Singularity images by default. To accommodate this, you can create an “alias” for singularity by editing your ~/.zshrc file adding the following line:

alias singularity="limactl shell apptainer-rootful apptainer"