Menu
Article How-to

Installing Jekyll with Toolbx

Rich Hughes

• 2 min read

Installing Jekyll on an Immutable Linux Distribution and More with Toolbx

This guide provides a robust method for installing and using Jekyll on an immutable Linux distribution, such as Aurora Linux (assuming it's based on Fedora Silverblue/Kinoite) or any Fedora-based system using Toolbox. It utilizes rbenv for Ruby version management within the Toolbox container.

Assumptions:

  • You are using an immutable Linux distribution that supports Toolbox.
  • You have Toolbox installed and configured.
  • You have a basic understanding of the command line.

Steps:

    • @development-tools: Installs essential build tools (compiler, etc.).
    • -devel packages: Provide headers and libraries for compiling Ruby.
    • Clones rbenv into your home directory.
    • Configures your shell to use rbenv.
    • Replace my-jekyll-site with your desired site name.

Install Jekyll in an existing project, but preserve git:

cd /var/home/rhuze/GitIt/Atomic-Linux-Docs
jekyll new --blank --skip-bundle .
git add .
git commit -m "Initial commit after jekyll init"
bundle install
bundle exec jekyll serve

Install Jekyll and Create a New Site (Option 2: Outside a Git Repo):This creates a completely independent Jekyll site.

cd ~  # Go to your home directory
jekyll new my-new-site
cd my-new-site
bundle install
bundle exec jekyll serve

Install Jekyll and Create a New Site (Option 1: Inside a Git Repo Subdirectory):This is the recommended approach if you have an existing Git repository and want to add a Jekyll site within it.

cd /path/to/your/git/repo  # Replace with the path to your Git repository
jekyll new my-jekyll-site  # Create the site in a *new* subdirectory
cd my-jekyll-site        # Navigate into the new Jekyll site directory
bundle install           # Install project dependencies
bundle exec jekyll serve  # Start the development server

Install Bundler:

gem install bundler

Verify Ruby Installation:

ruby -v
gem -v

Install a Ruby Version:

rbenv install --list  # (Optional) List available Ruby versions
rbenv install 3.2.2  # Replace with your desired (or latest stable) Ruby version
rbenv global 3.2.2  # Set as the default for this Toolbox

Install ruby-build (rbenv plugin):

git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Install rbenv:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

Install Development Dependencies:

sudo dnf install -y @development-tools zlib-devel libyaml-devel openssl-devel readline-devel bzip2-devel autoconf automake libtool bison sqlite-devel

Enter Toolbox:

toolbox enter

Important Notes and Best Practices:

  • bundle exec: Always use bundle exec before running Jekyll commands (e.g., bundle exec jekyll serve, bundle exec jekyll build). This ensures you're using the gems specified in your project's Gemfile.
  • Gemfile: The Gemfile and Gemfile.lock files in your Jekyll project are critical. They define your project's dependencies.
  • Project Location: Choose a location for your Jekyll project within your home directory inside the Toolbox. You can mount directories from the host if needed.
  • Toolbox Persistence: rbenv configuration is automatically persistent across Toolbox sessions because it's added to ~/.bashrc.
  • Troubleshooting:
    • If you encounter errors, carefully read the error messages.
    • Ensure g++ is available ( which g++ ) after installing @development-tools. If not, exit and re-enter Toolbox.
    • For package issues, try sudo dnf clean all and sudo dnf makecache.
  • Multiple Toolboxes: For complete isolation, create different Toolbox containers for different projects.
Share