Apple's M1 & M2 Setup - department-of-veterans-affairs/caseflow GitHub Wiki

Mac M1 and M2 (Apple Silicon) Installation

STOP! The official setup instructions are located here. The instructions on this page are for testing changes which do not require sudo access.

How to verify that you have an Apple Silicon processor:

Click the Apple icon in the top-left of the screen
Click 'About This Mac'
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:

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. Additionally, the Ruby gems therubyracer and jshint require the library [email protected], which can also only be compiled and installed on x86_64 processors. 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.

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

Create a ~/dev/appeals/ directory
Clone the following repo using git clone into this directory
- https://github.com/department-of-veterans-affairs/caseflow.git
Optional for setting up a machine, though you may work with these in the future
If you cannot clone the above, you might need to do this setup

Homebrew Installation

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.

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

Download UTM from this link
Right click UTM.app and select “install with privilege management” then open the UTM.app
Download the Vacols VM from this link
After the file downloads, right click on it in “Finder” and select “Show Package Contents” and delete the view.plist file if it exists
Right click on the application and select “Open With > UTM.app (default)”
Select the “Play” button when it pops up in UTM
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

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

Oracle “instantclient” Files

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

Postgres Download

Download and install from this link

Configure x86_64 Homebrew

Run the below commands from your home directory

In a terminal, create a homebrew directory under your home directory
- mkdir homebrew
In a terminal, run
- curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
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

Open standard terminal and run:
- softwareupdate -–install-rosetta –-agree-to-license
Once Rosetta is installed, find the default terminal in “Finder” > Applications
Right click and select “Get Info”
Select “Open using Rosetta”
- Note: you can copy the standard terminal executable to your desktop and enable Rosetta on that, so that you don’t need to disable rosetta on the default terminal once Caseflow setup is complete

Modify your .zshrc File

Run command open ~/.zshrc
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

Save file
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

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

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
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-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config
5. Install [email protected] by doing the following (these steps assume that vi/vim is the default editor):
  1. run HOMEBREW_NO_INSTALL_FROM_API=1 brew edit [email protected]
  2. go to line 21 in the editor by typing :21 Note: the line being removed is disable! date: "2023-06-19", because: "depends on Python 2 to build"
  3. delete the line by pressing d twice
  4. save and quit by typing :x
  5. run HOMEBREW_NO_INSTALL_FROM_API=1 brew install [email protected]
6. Configure build opts for gem therubyracer:
  1. bundle config build.libv8 --with-system-v8
  2. bundle config build.therubyracer --with-v8-dir=$(brew --prefix [email protected])
7. run ./scripts/dev_env_setup_step2.sh 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.
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

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
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
Open caseflow in VSCode (optional), or navigate to the caseflow directory in your terminal and:
1. brew install yarn
Ensure you are on master branch and up to date by running
1. git checkout master
2. git fetch
3. git pull origin master
Start Vacols UTM VM (if not already running)
run make up-m1 to create the docker containers and volumes
run make reset to (re)create and seed the database; this takes a while (~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
open a second terminal tab/window
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:

Start the VACOLS VM via UTM; login is not required
In terminal, run colima start to start the docker daemon
In terminal, go to the caseflow directory and run:
- make up-m1 to start the docker containers
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.

Download [email protected] and openssl@3 from this link
Open “Finder” and find the two folders under “Downloads”
Extract the .tar.gz or .zip archives
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
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:

brew install [email protected]
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:

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