Skip to content

Apple's M1 & M2 Setup

Jump to bottom
Sean Craig edited this page Nov 13, 2024 · 28 revisions

Mac M1 and M2 (Apple Silicon) Installation

<< Back

How to verify that you have an Apple Silicon processor:

  1. Click the Apple icon in the top-left of the screen
  2. Click 'About This Mac'
  3. Look for the 'Chip' section at the top of the list
    1. Apple Silicon processors will begin with 'Apple'; as of 8/2024, these a variant of 'Apple M1', 'Apple M2', 'Apple M3', or 'Apple M4'

Frequently Asked Question:

  1. I am running into errors! Where can I go for help?

See the Installation Workarounds section for common or previously relevant workarounds that may help. Additionally, join the #bid_appeals_mac_support channel in Slack (or ask your scrum master to add you). You can search that channel to see if your issue has been previously discussed or post what step you are having a problem on and what you've done so far.

Important

Ensure command line tools are installed via Self Service Portal prior to starting

If the command line tools are already installed, make sure you update it to the latest version by going to the System Settings Application -> General Settings -> Software Updates

Follow these instructions as closely as possible. If a folder is specified for running terminal commands, ensure you are in that directory prior to running the command(s). If you can't complete a step, ask for help in the #bid_appeals_mac_support channel of the Benefits Integrated Delivery (BID) Slack workspace.

Clone these Repos

  1. Create a ~/dev/appeals/ directory

  2. Clone the following repo using git clone into this directory

  3. Optional for setting up a machine, though you may work with these in the future

  4. If you cannot clone the above, you might need to do this setup

Homebrew Installation

  1. Install homebrew from self-service portal

Docker Installation

Note: We do not use Docker Desktop due to licensing. We recommend using Colima to run the docker service.

  1. Open terminal and run:
    1. brew install docker docker-compose colima
    2. mkdir -p ~/.docker/cli-plugins
    3. ln -sfn /opt/homebrew/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Install UTM and VACOLS VM

  1. Download UTM from this link
  2. Right click UTM.app and select “install with privilege management” then open the UTM.app
  3. Download the Vacols VM from this link
  4. After the file downloads, right click on it in “Finder” and select “Show Package Contents” and delete the view.plist file if it exists
  5. Right click on the application and select “Open With > UTM.app (default)”
  6. Select the “Play” button when it pops up in UTM
  7. Leave this running in the background. If you close the window, you can open it back up by repeating steps 5-7

Chromedriver, PDFtk Server, and wkhtmltox Installation

Note: You may need to restart your machine in between installing each of the packages.

  1. Open terminal and run
    • brew install --cask chromedriver
  2. Once it successfully installs, run command
    • chromedriver –version
  3. There will be a pop up. Before clicking “OK,” navigate to System Settings > Privacy & Security
  4. Scroll down to the security section and it will say “chromedriver was blocked from use because it is not from an identified developer”
  5. Select “Allow Anyway”
  6. Also in the Security section click on Developer Tools and add Terminal to the list of applications
  7. Select “Yes” from pop up
  8. Reopen terminal and once again run chromedriver –version
  9. Select “Open”
  10. Restart your computer
  11. Download and install from this link. When you receive a security warning, follow steps 3-6 for PDFtk server. Note: You if you run into to issues you may need to restart you computer
  12. Restart your computer
  13. Download this file and move through the prompts. When you receive a security warning, follow steps 3-6 for wkhtmltox

Oracle “instantclient” Files

  1. Download these DMG files
  2. After downloading, double click on one of the folders and follow the instructions in INSTALL_IC_README.txt to copy the libraries

Postgres Download

  1. Download and install from this link

Modify your .zshrc File

  1. Run command open ~/.zshrc
  2. Add the following lines, ensuring that you have a newline at the end of the file:
# Add homebrew binaries to the PATH
export PATH=/opt/homebrew/bin:${PATH}

# Add Postgres environment variables for CaseFlow
export POSTGRES_HOST=localhost
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
export NLS_LANG=AMERICAN_AMERICA.UTF8
export FREEDESKTOP_MIME_TYPES_PATH=/opt/homebrew/share/mime/packages/freedesktop.org.xml

# InstantClient directory for ruby-oci8 gem
export OCI_DIR=$HOME/Downloads/instantclient_23_3

# Provide path to docker daemon in case there are issues finding it in the terminal
export DOCKER_HOST="unix://$HOME/.colima/docker.sock"
  1. Save file
  2. Go to your active terminal and enter source ~/.zshrc, or exit and open a new terminal

Verify/update database gem version(s) in the Gemfile:

  1. In the Caseflow root directory, open the file Gemfile
  2. Verify/update the PG gem to 1.5.7: gem "pg", "~> 1.5.7"
  3. Verify/update the ruby-oci8 gem to 2.2.14: gem "ruby-oci8", "~> 2.2.14"

Installing Dependencies

Either run the following commands in order, or copy/paste them into a script in your home directory and execute it:

#!/bin/bash

# cleanup old directories; new installations may not have any of these, but it does not hurt to run them
rm -rf ~/homebrew
rm -rf ~/.asdf
rm -rf ~/.docker
rm -rf ~/.nodenv
rm -rf ~/.nvmrc
rm -rf ~/.nvm
rm -rf ~/.rbenv
rm -rf ~/.gem
rm -rf ~/.pyenv

# apple command line utils, if not already installed
xcode-select --install

# install brew applications
brew install coreutils curl gpg gawk asdf pyenv libpq yarn -f

# configure asdf in .zshrc file
echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

# add nodejs as asdf package mgr and install node
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf install nodejs 16.16.0

# add ruby as asdf package mgr and install ruby
asdf plugin add ruby  https://github.com/asdf-vm/asdf-ruby.git
asdf install ruby 2.7.3

# add python to asdf and install
asdf plugin add python https://github.com/asdf-community/asdf-python
asdf install python 3.10.7

# source .zshrc file to activate asdf
. ~/.zshrc

# change to caseflow dir
cd ~/dev/appeals/caseflow

# set node and ruby versions in caseflow directory
asdf local nodejs 16.16.0
asdf local ruby 2.7.3
asdf local python 3.10.7
node -v
ruby -v
python --version

# set up the Makefile
ln -s Makefile.example Makefile

# install gems that require a little more work that bundle install will provide
gem install bundler:2.4.22
gem install msgpack -v 1.4.2 -- --with-cflags="-Wno-error=implicit-function-declaration -Wno-error=incompatible-function-pointer-types"
gem install debase -v 0.2.4.1 -- --with-cflags="-Wno-error=implicit-function-declaration -Wno-error=incompatible-function-pointer-types"

# set bundler config options for installing the pg gem
bundle config build.pg --with-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config

make install

# if you get an error when running make install due to the PG gem, run the command below and then re-run make install:
# gem install pg:1.5.7 -- --with-cflags="-Wno-error=implicit-function-declaration -Wno-error=incompatible-function-pointer-types" --with-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config

To excutable run:

  1. chmod 755 YourScriptName.sh
  2. ./YourScriptName.sh

Running Caseflow

  1. Ensure you are on the main branch and up to date by running
    1. git checkout main
    2. git fetch
    3. git pull origin main
  2. Start Vacols UTM VM (if not already running)
  3. Run make up-m1 to create the docker containers and volumes
  4. Run make reset to (re)create and seed the database; this may take a while depending on which branch you are on (anywhere from 5 mintues up to ~45 minutes)
    1. If you get a database not found error, run bundle exec rake db:drop db:create db:schema:load, and then run make reset again
  5. Open a second terminal tab/window
  6. Run make run-backend-m1 in one tab, and make run-frontend in the other
    1. The backend should launch on localhost:3000. Go there in your browser to access Caseflow
    2. The frontend launches on localhost:3500; This is a server that enables hot-reloading of modules during development. Going to this address in a browser will not work
    3. Optionally, you can do make run-m1 to launch both at the same time with Foreman, but if one server errors the other can remain running and lead to headache trying to get them back up

To launch caseflow after a machine restart:

  1. Start the VACOLS VM via UTM; login is not required
  2. In terminal, run colima start to start the docker daemon
  3. In terminal, go to the caseflow directory and run:
    • make up-m1 to start the docker containers
  4. Open a second terminal window/tab, and from the caseflow directory run:
    • make run-backend-m1 in one tab
    • make run-frontend in the other tab

Note: It takes several minutes for the VACOLS VM to go through its startup and launch the Oracle DB service, and about a minute for the Postgres DB to initialize after running make up-m1.

Installation Workarounds

OpenSSL

Only follow the below instructions if you have problems with openssl@3 or [email protected] not compiling.

  1. There have been issues in the past with compiling openssl 1.1.1 and openssl 3, which were worked around by sharing precompiled files to devs who are seeing the problem. This was likely a problem with our previous setup, where we needed to have an x86_64 homebrew installed alongside the standard arm64 homebrew. If you run into this issue following these instructions, post in the #bid_appeals_mac_support channel channel for support.

Gem Installation

During the gem installation if you are seeing errors indicating DESTDIR: command not found make sure the xcode command line tools installed are up-to-date

Running Caseflow

The following steps are an alternative to step 7 of the Running Caseflow section in the event that you absolutely cannot get those commands to work:

  1. In caseflow, run
    • a. make down
      • i. Removes appeals-db, appeals-redis, and localstack docker containers
    • b. docker-compose down –v
      • i. Removes caseflow_postgresdata docker volume
    • c. make up-m1
      • i. Starts docker containers, volume, and network
    • d. make reset
      • i. Resets caseflow and ETL database schemas, seeds databases, and enables feature flags
      • **If make reset returns database not found error:
        • a. Run command bundle exec rake db:drop
        • b. Download caseflow-db-backup.gz (not able to share this download via policy, ask in the slack channel)
        • c. Enter terminal, navigate to ~/Downloads
        • e. Run command
          • i. gzip -dck caseflow-db-backup.gz | docker exec -i appeals-db psql -U postgres
          • ii. (this command will link the caseflow_certification_database to docker)
        • f. Enter terminal, navigate to caseflow, and run
          • i. make up-m1
          • ii. make reset (this will take a while)
Deprecated instructions; do not use unless specifically directed

How to verify that you have an Apple Silicon processor:

  1. Click the Apple icon in the top-left of the screen
  2. Click 'About This Mac'
  3. Look for the 'Chip' section at the top of the list
    1. Apple Silicon processors will begin with 'Apple'; as of 7/2023, these a variant of 'Apple M1' or 'Apple M2'

Frequently Asked Question:

  1. Why is this so complicated?

Apple Silicon processors use a different architecture (arm64/aarch64) than Intel processors (x86_64). Oracle, which is used for the VACOLS database, does not have binaries to run any of their database tools natively on arm64 for MacOS. To work around this we use Rosetta to emulate x86_64 processors in the terminal, installing most of the Caseflow dependencies via the x86_64 version of Homebrew. It is important that while setting up your environment, you ensure you are in the correct terminal type and in the correct directory so that you do not install or compile a dependency with the wrong architecture.

  1. I am running into errors! Where can I go for help?

See the Installation Workarounds section for common or previously relevant workarounds that may help. Additionally, join the #bid_appeals_mac_support channel in Slack (or ask your scrum master to add you). You can search that channel to see if your issue has been previously discussed or post what step you are having a problem on and what you've done so far.

Ensure command line tools are installed via Self Service Portal prior to starting

Follow these instructions as closely as possible. If a folder is specified for running terminal commands, ensure you are in that directory prior to running the command(s). If you can't complete a step, ask for help in the #bid_appeals_mac_support channel of the Benefits Integrated Delivery (BID) Slack workspace.

Clone these Repos

  1. Create a ~/dev/appeals/ directory

  2. Clone the following repo using git clone into this directory

  3. Optional for setting up a machine, though you may work with these in the future

  4. If you cannot clone the above, you might need to do this setup

Homebrew Installation

  1. Install homebrew from self-service portal

Docker Installation

Note: We do not use Docker Desktop due to licensing. We recommend using Colima to run the docker service.

  1. Open terminal and run:
    1. brew install docker docker-compose colima
    2. mkdir -p ~/.docker/cli-plugins
    3. ln -sfn /opt/homebrew/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Install UTM and VACOLS VM

  1. Download UTM from this link
  2. Right click UTM.app and select “install with privilege management” then open the UTM.app
  3. Download the Vacols VM from this link
  4. After the file downloads, right click on it in “Finder” and select “Show Package Contents” and delete the view.plist file if it exists
  5. Right click on the application and select “Open With > UTM.app (default)”
  6. Select the “Play” button when it pops up in UTM
  7. Leave this running in the background. If you close the window, you can open it back up by repeating steps 5-7

Chromedriver, PDFtk Server, and wkhtmltox Installation

Note: You may need to restart your machine in between installing each of the packages.

  1. Open terminal and run
    • brew install --cask chromedriver
  2. Once it successfully installs, run command
    • chromedriver –version
  3. There will be a pop up. Before clicking “OK,” navigate to System Settings > Privacy & Security
  4. Scroll down to the security section and it will say “chromedriver was blocked from use because it is not from an identified developer”
  5. Select “Allow Anyway”
  6. Select “Yes” from pop up
  7. Reopen terminal and once again run chromedriver –version
  8. Select “Open”
  9. Download and install from this link. When you receive a security warning, follow steps 3-6 for PDFtk server
  10. Download this file and move through the prompts. When you receive a security warning, follow steps 3-6 for wkhtmltox

Oracle “instantclient” Files

  1. Download these DMG files
  2. After downloading, double click on one of the folders and follow the instructions in INSTALL_IC_README.txt to copy the libraries

Postgres Download

  1. Download and install from this link

Configure x86_64 Homebrew

Run the below commands from your home directory

  1. In a terminal, create a homebrew directory under your home directory
    • mkdir homebrew
  2. In a terminal, run
    • curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
  3. If you get a chdir error, run
    • mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew

Rosetta

  1. Open standard terminal and run:
    • softwareupdate -–install-rosetta –-agree-to-license
  2. Once Rosetta is installed, find the default terminal in “Finder” > Applications
  3. Right click and select “Get Info”
  4. Select “Open using Rosetta”

Modify your .zshrc File

  1. Run command open ~/.zshrc
  2. Add the following lines, if any of these are already set make sure to comment previous settings:
export PATH=~/homebrew/bin:${PATH}
eval "$(~/homebrew/bin/rbenv init -)"
eval "$(~/homebrew/bin/nodenv init -)"
eval "$(~/homebrew/bin/pyenv init --path)"

# Add Postgres environment variables for CaseFlow
export POSTGRES_HOST=localhost
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres
export NLS_LANG=AMERICAN_AMERICA.UTF8
export FREEDESKTOP_MIME_TYPES_PATH=~/homebrew/share/mime/packages/freedesktop.org.xml export OCI_DIR=~/Downloads/instantclient_19_8
  1. Save file
  2. Go to your active terminal and enter source ~/.zshrc or create a new terminal

Note: until rbenv, nodenv, and pyenv are installed, the eval commands will display a 'command not found' error when launching a terminal

Run dev setup scripts in Caseflow repo

VERY IMPORTANT NOTE: The below commands must be run in a Rosetta terminal until you reach the 'Running Caseflow' section

Script 1

  1. Enter a Rosetta terminal and ensure you are in the directory you cloned Caseflow repo into (~/dev/appeals/caseflow) and run commands:
    1. git checkout grant/setup-m1
    2. ./scripts/dev_env_setup_step1.sh
    • If this fails, double check your .zshrc file to ensure your PATH has only the x86_64 brew

Note: If you run into errors installing any versions of openssl, see the "Installation Workarounds" section at the bottom of this document

Script 2

  1. In the Rosetta terminal, install pyenv and the required python2 version:
    1. brew install pyenv
    2. pyenv rehash
    3. pyenv install 2.7.18
    4. In the caseflow directory, run pyenv local 2.7.18 to set the version
  2. In the Rosetta terminal navigate to caseflow folder:
    1. Run rbenv install $(cat .ruby-version)
    2. Run rbenv rehash
    3. Run gem install bundler -v $(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -n 1)
    4. Run gem install pg:1.1.4 -- --with-cflags="-Wno-error=implicit-function-declaration -Wno-error=incompatible-function-pointer-types" --with-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config
    5. Run bundle config build.pg --with-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config
    6. Run ./scripts/dev_env_setup_step2.sh

NOTE: If you get a permission error while running gem install or bundle install, something went wrong with your rbenv install which needs to be fixed.

  1. If there are no errors messages, run bundle install to ensure all gems are installed

Running Caseflow

VERY IMPORTANT NOTE TWO: This is where you switch back to a standard (non-Rosetta) terminal

  1. Once your installation of all gems is complete, switch back to a standard MacOS terminal:
    1. Open your ~/.zshrc file
    2. Comment the line export PATH=~/homebrew/bin:$PATH
    3. Uncomment the line export PATH=/opt/homebrew/bin:$PATH
    4. Add the line export PATH=$HOME/.nodenv/shims:$HOME/.rbenv/shims:$HOME/.pyenv/shims:$PATH
    5. Comment the lines eval "$({binary} init -)" for rbenv, pyenv, and nodenv if applicable
    6. If you added the line eval $(~/homebrew/bin/brew shellenv) after installing x86_64 homebrew, comment it out
  2. Open a terminal verify:
    1. that you are on arm64 by doing arch and checking the output
    2. that you are using arm64 brew by doing which brew and ensuring the output is /opt/homebrew/bin/brew
  3. Open caseflow in VSCode (optional), or navigate to the caseflow directory in your terminal and:
    1. brew install yarn
  4. Ensure you are on main branch and up to date by running
    1. git checkout main
    2. git fetch
    3. git pull origin main
  5. Start Vacols UTM VM (if not already running)
  6. Run make up-m1 to create the docker containers and volumes
  7. Run make reset to (re)create and seed the database; this may take a while depending on which branch you are on (anywhere from 5 mintues up to ~45 minutes)
    1. If you get a database not found error, run bundle exec rake db:drop db:create db:schema:load, and then run make reset again
  8. Open a second terminal tab/window
  9. Run make run-backend-m1 in one tab, and make run-frontend in the other
    1. The backend should launch on localhost:3000. Go there in your browser to access Caseflow
    2. The frontend launches on localhost:3500; This is a server that enables hot-reloading of modules during development. Going to this address in a browser will not work
    3. Optionally, you can do make run-m1 to launch both at the same time with Foreman, but if one server errors the other can remain running and lead to headache trying to get them back up

To launch caseflow after a machine restart:

  1. Start the VACOLS VM via UTM; login is not required
  2. In terminal, run colima start to start the docker daemon
  3. In terminal, go to the caseflow directory and run:
    • make up-m1 to start the docker containers
  4. Open a second terminal window/tab, and from the caseflow directory run:
    • make run-backend-m1 in one tab
    • make run-frontend in the other tab

Note: It takes several minutes for the VACOLS VM to go through its startup and launch the Oracle DB service, and about a minute for the Postgres DB to initialize after running make up-m1.

Installation Workarounds

OpenSSL

When installing rbenv, nodenv, or pyenv, both openssl libraries should install as dependencies. Only follow the below instructions if you have problems with openssl@3 or [email protected] not compiling.

  1. Download [email protected] and openssl@3 from this link
  2. Open “Finder” and find the two folders under “Downloads”
  3. Extract the .tar.gz or .zip archives
  4. In each of the extracted folders:
    1. Navigate to the ~/homebrew/Cellar subfolder
    2. Copy the openssl folder to your local machine's ~/homebrew/Cellar folder
    3. If the folder Cellar in ~/homebrew does not exist, create it with mkdir ~/homebrew/Cellar
    • Note: moving these folders can be done using finder or a terminal
  5. Run command (from a rosetta terminal)
    1. brew link --force [email protected]
    2. If the one above doesn’t work run: brew link [email protected] --force
    • Note: don't link openssl@3 unless you run into issues farther in the setup

Installing Ruby via Rbenv

If you are getting errors for rbenv being unable to find a usable version of openssl, run these commands prior to running the second dev setup script:

  1. brew install [email protected]
  2. export RUBY_CONFIGURE_OPTS="--with-openssl-dir=/usr/local/homebrew/Cellar/[email protected]"

Running Caseflow

The following steps are an alternative to step 7 of the Running Caseflow section in the event that you absolutely cannot get those commands to work:

  1. In caseflow, run
    • a. make down
      • i. Removes appeals-db, appeals-redis, and localstack docker containers
    • b. docker-compose down –v
      • i. Removes caseflow_postgresdata docker volume
    • c. make up-m1
      • i. Starts docker containers, volume, and network
    • d. make reset
      • i. Resets caseflow and ETL database schemas, seeds databases, and enables feature flags
      • **If make reset returns database not found error:
        • a. Run command bundle exec rake db:drop
        • b. Download caseflow-db-backup.gz (not able to share this download via policy, ask in the slack channel)
        • c. Enter terminal, navigate to ~/Downloads
        • e. Run command
          • i. gzip -dck caseflow-db-backup.gz | docker exec -i appeals-db psql -U postgres
          • ii. (this command will link the caseflow_certification_database to docker)
        • f. Enter terminal, navigate to caseflow, and run
          • i. make up-m1
          • ii. make reset (this will take a while)

<< Back

Clone this wiki locally