How to install Jekyll on a Mac with an arm64 (aka “Apple Silicon”) processor.

Background

This document shows how I was able to install Jekyll on a Mac with an amd64 processor.

I tried this last week and I got a warning about Homebrew not being stable for arm64 systems yet. I tried it again today out of curiosity, and it installed successfully, even though the Homebrew “blog” doesn’t mention any changes since last week (it still has “2.7.0” as the most recent version).

Installation

Install Homebrew

From Homebrew install instructions

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

Note: if you’re going to copy/paste this, please copy/paste from the Homebrew web site instead. It’s entirely possible that they may have updated something and I haven’t updated this page yet.

Check PATH

For arm64 systems, Homebrew installs everything under /opt/homebrew/ and does not symlink installed binaries into /usr/local/bin/ like it does on Intel systems.

Make sure the following directory is in your PATH, in the appropriate order. I generally want binaries installed by Homebrew to be used instead of binaries with the same names that came with macOS, so I have it in my PATH before the /usr/bin and /bin directories.

• /opt/homebrew/bin - contains the brew command itself, along with symlinks to executables installed by Homebrew packages

If you updated your PATH, be sure to start a new shell and make sure the change worked.

Install recent Ruby from Homebrew

In theory Jekyll should work with the Ruby 2.6 that comes with macOS 11, however I couldn’t get it to work when I tried on an Intel machine

brew install ruby

Update PATH

First choose PREFIX as:

• /usr/local for x86_64 systems
• /opt/homebrew for arm64 systems

Make sure the following directories are in your PATH, in the appropriate order.

• For ruby and associated binaries
  • $PREFIX/opt/ruby/bin
• For executables installed as system-wide Ruby gems when GEM_HOME is not set (see below)
  • $PREFIX/lib/ruby/gems/2.7.0/bin - if using Ruby 2.7.x
  • $PREFIX/lib/ruby/gems/3.0.0/bin - if using Ruby 3.0.x

  Note that the directory name will always be “n.n.0”, regardless of the “point release” version. For example, if “ruby -v” says “2.7.2p137”, the directory name will still be “2.7.0”.

If you updated your PATH, be sure to start a new shell and make sure the change worked.

Set the GEM_HOME variable

Setting a value for the GEM_HOME variable will override the location where “system-wide” Ruby gems will be installed. This is normally done if you don’t have write access to the normal system-wide Ruby gems directory (maybe because you’re using a system’s “native” Ruby and you’re running as a user without administrator rights), or if you don’t want to risk making system-wide changes (which is always a good excuse.)

In my case, I always set this variable when using Ruby from Homebrew, even though I’m normally the same user that installed Homebrew and Ruby (and therefore have write permissions to the directory). The alternative is to use things like the “gem install --user-install” option when installing gems, which installs the gems to a directory within your home directory.

Setting a GEM_HOME value will also installs the gems to a directory within your home directory, however there is no way to tell “bundle install” to use “gem install --user-install” when it needs to install gems. The closest alternative is to use “bundle install --deployment”, which installs any gems in the “vendor/bundle/” directory within that one application. This will work, and may be preferred if you work with multiple Ruby applications that need different versions of certain gems, however you have to remember to include the “--deployment” option with every “bundle install” command.

I find it easier to just set the GEM_HOME variable and not worry about it.

In .bashrc or .zshenv, add something like this:

########################################
# Ruby "system-wide" gems in home directory

if [[ -d "${HOME}/.gems" ]]
then
    export GEM_HOME="$HOME/.gems"
    PATH="${HOME}/.gems/bin:${PATH}"
fi

Install Jekyll

Assuming that the GEM_HOME variable points to a directory within your home directory, then…

gem install jekyll bundler

Check PATH

Assuming you installed Jekyll using Ruby 3.0.x (when I did this process while writing this document it was 3.0.0), make sure that the following directory is in your PATH, in the appropriate order.

• $HOME/.gem/ruby/3.0.0/bin

If you updated your PATH, be sure to start a new shell and make sure the change worked.

webrick

The webrick gem is a minimal web server, commonly used for testing Ruby applications that function as web services. In ruby 2.x it was included as a standard part of the Ruby distribution, however in Ruby 3.0 it is no longer installed by default.

The jekyll app uses it, but does not explicitly declare it as a dependency, either when installing, or in the Gemfile files of the web sites that it creates.

If you are using Ruby 3.0 or later, each Jekyll site will have a Gemfile in its directory. Edit this file and add the following line:

gem "webrick"

Then run “bundle install” (or “bundle install --deployment”, if you want to install it within just this one application). This will install the webrick gem if it isn’t already installed, along with any other gems needed by Jekyll for this web site.

Verify that Jekyll is working

Run Jekyll’s local server and make sure they work as expected. For example, if you already have a Jekyll site, cd into that directory and…

bundle exec jekyll serve

This command should print something like this, and then just sit there waiting.

Configuration file: /Users/jms1/git/jms1info/_config.yml
            Source: /Users/jms1/git/jms1info
       Destination: /Users/jms1/git/jms1info/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 0.244 seconds.
 Auto-regeneration: enabled for '/Users/jms1/git/jms1info'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Assuming this is true, you should be able to visit http://127.0.0.1:4000/ and test the site.

Testing on a non-local machine

The http://127.0.0.1:4000/ URL will only work if you’re working with jekyll on your local machine. If you are SSH’d into another machine and working on the site there, you will need to make arrangements for a browser on your local machine to be able to access that machine’s localhost interface. This can be done using SSH port forwarding. I don’t really want this document to go into a full explanation of how SSH port forwarding works, but if you need an example, and you’re using OpenSSH (which is what macOS comes with)…

On your local workstation (i.e. the machine physically in front of you), SSH into the remote machine using a command like this:

ssh -L4000:127.0.0.0:4000 user@server

If you’re already SSH’d into the remote system, you have three options:

• Log out of the SSH connection and then use the command above to log back in.

• Open a second window and use the command above.

  Be sure to not log out of that second SSH connection until you’re finished with the port forwarding.

• Add the port forwarding to your existing SSH connection, using the “~C” escape sequence.

  If you’re not familiar with how to do this, the ssh man page sorta explains how it works, and a web search for something like “ssh escape forward” should find dozens of web pages that go into more detail. I may even write one myself at some point.)

Once the port forwarding is set up, accessing http://127.0.0.1:4000/ from a browser on your local machine should access 127.0.0.1:4000 on the remote machine, and allow you to view what Jekyll is serving on the remote machine.

Changelog

2021-01-03 jms1

• Started to finish a few incomplete sentences (things I had started to say but then went off and changed something else), ended up adding a good amount of new content.

2021-01-02 jms1

• Initial version, after the first time I got it working