Known Working Configurations

To address #49, we are listing out hardware + software configurations that are known to work when building the Jekyll site. At a bare minimum, you will need ruby, rubygems, and bundler.

M2 macOS 15 Sequoia

(September, 2025). Using mise to manage ruby instead of rbenv.

$ uname -a && ruby --version && gem --version && bundle --version
Darwin Clytemnestra 24.6.0 Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:51 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T8112 arm64
ruby 3.3.1 (2024-04-23 revision c56cd86388) [arm64-darwin23]
3.5.9
Bundler version 2.7.1

Setup steps:

# install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git mise # install git & mise
git clone https://github.com/code4lib/2026.code4lib.org
cd 2026.code4lib.org
mise use ruby@3.3.1
bundle install

macOS 12 Monterey

A typical Macbook Pro (not using Apple M1 silicon).

$ uname -a && rbenv --version && ruby --version && gem --version && bundle --version
Darwin MacBook-Pro 21.1.0 Darwin Kernel Version 21.1.0: Wed Oct 13 17:33:23 PDT 2021; root:xnu-8019.41.5~1/RELEASE_X86_64 x86_64
rbenv 1.2.0
ruby 2.5.7p206 (2019-10-01 revision 67816) [x86_64-darwin20]
RubyGems 2.7.6.2
Bundler version 2.2.29

These steps should recreate an environment that successfully builds the site.

$ # install homebrew using the steps at https://brew.sh
$ brew install rbenv # install rbenv from homebrew
$ rbenv install 2.5.7 # install ruby from rbenv
$ # below, we clone & enter the site's git repo
$ cd ~/Documents && git clone git@github.com:code4lib/2022.code4lib.org && cd 2022.code4lib.org
$ rbenv local 2.5.7 # tell rbenv to use ruby 2.5.7 in the repo's directory
$ gem install bundler # install bundler
$ bundle install # install project dependencies
$ bundle exec jekyll serve # build the site & run a local dev server

macOS Big Sur w/ Ruby 3.0.0

➜ uname -a && rbenv --version && ruby --version && gem --version && bundle --version
Darwin derek-mbp-personal.zoladz.local 20.3.0 Darwin Kernel Version 20.3.0
rbenv 1.2.0
ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin20]
RubyGems 3.2.3
Bundler version 2.3.6