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

Linux w/ Docker and Docker Compose >= 2.0

Using docker avoids the need to locally install jekyll/ruby/bundler/etc.

The instructions below use *nix as an example and should work on MacOS just fine. Windows should work too, just needs the shell commands translated.

1. Make sure docker and docker-compose are installed via your package manager or the documentation
2. Prepare a project dir somewhere and clone the repository:

$ mkdir c4l2026
$ cd c4l2026
$ git clone git@github.com:code4lib/2026.code4lib.org.git

3. Create a new file called docker-compose.yml with the following content (edit ports, tty options as you like)

version: '3.8'

services:
  jekyll:
    image: jekyll/jekyll:latest
    command: jekyll serve --watch --force_polling --host 0.0.0.0
    ports:
      - "4000:4000"
    volumes:
      - ./2026.code4lib.org:/srv/jekyll
    working_dir: /srv/jekyll
    environment:
      JEKYLL_ENV: development
    stdin_open: true
    tty: true

• To run: docker-compose -p c4l up -d in the project directory.
• To stop: docker-compose -p c4l down in the project directory.

The git repository is bound as the working directory in the container so you can make changes normally on your host machine, and the containerized jekyll will see changes and update. The project -p c4l argument is optional, but useful to help separate this docker environment from others if they share resource names.