Getting Started with Roots Sage, Trellis, and Bedrock on MacOS

Trellis, Bedrock, and Sage development on macOS 10.13+ is supported by several libraries and software packages.

Requirements

Trellis, Bedrock, and Sage development on macOS relies on several libraries and software packages. This guide will show you how to install and configure each of these recommended packages on your computer. This guide assumes basic knowledge of command line and terminal usage.

• Xcode Command Line Tools
• Git
• Homebrew
• Composer
• nvm
• Node.js

Xcode Command Line Tools

Install Xcode Command Line Tools using the built-in command:

$ xcode-select --install

Git

Git is automatically installed as part of the Xcode Command Line tools. Configure Git with your user information:

$ git config --global user.name "Your Name"
$ git config --global user.email "yourname@example.com"

Homebrew

Install Homebrew from the instructions at https://brew.sh, or with the following command:

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

Composer

Install Composer from Homebrew:

$ brew install composer

SSH keys

Create SSH key

Trellis and GitHub both use SSH keys to communicate securely without the need to type a username and password each time. Create your SSH key and add them to your macOS Keychain:

$ ssh-keygen -t ed25519 -C "your_email@example.com"

For more details on generating SSH keys, see GitHub's excellent documentation.

Add your SSH key to the ssh-agent

Modify your ~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain.

Edit your ~/.ssh/config file and add the following lines:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Working with Sage

Sage relies on a few build tools to manage dependencies and build assets. Install these tools:

• nvm
• Node.js
• yarn

nvm

Install nvm from the instructions at https://github.com/creationix/nvm, or with the following command:

$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.0/install.sh | bash

Node.js

Install the latest Node.js LTS release from nvm:

$ nvm install --lts

yarn

Install yarn:

$ npm install --global yarn

Working with Trellis

Trellis relies on a few additional software packages to function. Install these packages:

• Vagrant >= 2.1.0
• a Vagrant provider:
  • Intel based Macs: VirtualBox >= 4.3.10
  • Apple Silicon (M1) based Macs: Parallels Pro >= v17
• Trellis CLI

Vagrant

We recommend installing Vagrant through their official installers: Vagrant downloads

We don't recommend Homebrew for two reasons:

1. brew automatically upgrades packages now by default which can cause issues
2. it's very hard to downgrade to an older specific version of Vagrant if need be

If you really want to use Homebrew to manage Vagrant, then run the following:

$ brew install vagrant

Vagrant Providers

VirtualBox (Intel Macs)

Download and install the "OS X Hosts" version of VirtualBox from https://www.virtualbox.org/wiki/Downloads

Parallels (Apple Silicon (M1) Macs)

See our Vagrant docs for details.

Trellis CLI

Install Trellis CLI from Homebrew.

brew install roots/tap/trellis-cli

NFS

For macOS Catalina or later, you will have to grant full disk access to /sbin/nfsd.

1. Navigate to System Preferences → Security & Privacy → Privacy → Full Disk Access
2. Click +
3. Press Command Shift G at the same time.
4. Enter the /sbin directory.
5. Double click the nfsd file.