MacOS setup

This has been verified to function correctly on MacOS 13.2.1. The approach is primarily based on the instructions provided by @danielnachun.

Step 1

Backup your current Shell configuration file

cp ~/.zshrc ~/zshrc.backup

Step 2

Download and install iTerm2 as your terminal emulator.

Step 3

Open iTerm2, install Homebrew:

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

After completing the installation, you will be prompted with two commands. Run those commands to add brew to your system path.

Step 4 (Optional)

Install special fonts to render unicode icons on the terminal:

brew tap homebrew/cask-fonts
brew install --cask font-meslo-lg-nerd-font

and terminal color theme at https://github.com/tinted-theming/base16-iterm2/blob/main/itermcolors/base16-one-light-256.itermcolors

These steps are in preparation for configuration to be installed at Step 5.

Step 5 (Optional, use caution)

Configure the system using a one-liner command,

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

This will take a while to complete.

Note: you might see errors in this step, particularly if you did not start from scratch. For example if you already have installed some software, there will be a conflict and an error report stating that the software already exists and thus cannot be reinstalled. Please read the log files carefully to look for any error messages, and decide case by case if those messages can be safely ignored. If you see what you believe crucial errors please raise an issue on our Lab Wiki repository on GitHub. Since the above command essentially just runs https://raw.githubusercontent.com/gaow/dotfiles/master/run_once_install-packages.sh.tmpl, so if the automated call fails, you can run the rest of the commands there to finish the setup.

Close your terminal and login again. At this point, you might see messed-up fonts with ? on your terminal. In that case, please manually open the terminal setting and choose the font you just installed, the MesloLGL Nerd Font, as terminal font.

If you see error messages related to missing R packages, please ignore them for now because Steps 6 and 7 should resolve the problem. Other than that, if there are still other issues that you cannot solve after some research, or you don’t like the new terminal style, you can always revert to your previous terminal configuration by recovering from your zshrc backup copy, eg:

cp ~/.zshrc ~/zshrc.chezmoi.io
cp ~/zshrc.backup ~/.zshrc
source ~/.zshrc

Step 6

Install micromamba and the Script of Scripts (SoS) suite by following these instructions. Please note that even if you have completed Step 5 which installed R using brew, our approach here will additionally installs R alongside of the SoS suite using micromamba. When this software environment is activated, you will by default be using R installed in this step. 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.

Step 7 (only necessary if you have done Step 5)

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"