Home

(Linux) Jekyll Toolbox container

Introduction

Jekyll is a Static Site Generator (SSG) written in Ruby that can be used to generate websites with minimal efforts thanks to templates and plugins. It is easy to use and very well documented. I use Jekyll to generate this website and am mostly happy with it. However, it can be tedious to set up because RubyGems (Ruby’s package manager), distribution packages, and environment variables can cause problems, and debugging can become annoying.

In my case, I had a horrible experience installing Jekyll on my host system along with RubyGems and its dependencies. I’m required to add ~/gem to my PATH, and later Bundle, a dependency, would create the ~/.bundle directory. Personally, I don’t want to install language specific package managers that create random dotfiles and directories that clutter my home directory on my host system, so I try to avoid them as much as I can with containers.

What is Toolbox?

Toolbox is a tool to run contained environments on Linux systems without having to manually set environment variables, permissions and more. It’s built on top of Podman, a drop-in replacement for Docker, and has minimal requirements to create containers.

For this reason, I wrote my own Dockerfile for Toolbox. Toolbox is convenient and doesn’t require a lot of knowledge about using containers, nor does it need a lot of flags or long commands like Podman or Docker do.

Installation

LPT: Never run random commands and scripts from the Internet! Always check the sources before running them.

Everything is available in the Jekyll Toolbox repository on Framagit, including the Dockerfile and the installation script.

Here’s what you need to do:

  1. if you haven’t already, install the toolbox package on your system using your favorite package manager. If you are using Fedora Silverblue, then it is already pre-installed.
  2. run the installation script manually. Alternatively, you can run the following command to avoid downloading the script to your system:

    On a POSIX compliant shell (bash or zsh), run:

    bash <(curl -s https://framagit.org/TheEvilSkeleton/jekyll-toolbox/-/raw/main/install.sh)
    

    On fish, run:

    bash (curl -s https://framagit.org/TheEvilSkeleton/jekyll-toolbox/-/raw/main/install.sh | psub)
    

This will create a new Toolbox container with the name jekyll, that you can now use to generate websites.

Optional: aliases

In the same script, I added support for adding aliases after user confirmation, so you don’t have to manually alias each command or run the full command to execute it. It only supports bash, zsh, and fish. You can deny it if you want.

The script automatically checks which shell you are using and asks where you want to output the aliases.

If you want to manually add the aliases to your shell configuration file, add the following:

On a POSIX compliant shell (bash or zsh):

alias bundle="toolbox run -c jekyll bundle"
alias jekyll="toolbox run -c jekyll jekyll"
alias gem="toolbox run -c jekyll gem"

On fish:

alias bundle "toolbox run -c jekyll bundle"
alias jekyll "toolbox run -c jekyll jekyll"
alias gem "toolbox run -c jekyll gem"

Usage

Unaliased commands are toolbox run -c jekyll COMMAND, for example toolbox run -c jekyll bundle exec jekyll serve.

If you followed the optional step, then you can use the bundle, jekyll and gem commands because they are aliased, for example bundle exec jekyll serve.

Testing

Test it on a website built on Jekyll, like this website. Clone the website’s repository and run the following commands to install the dependencies and start the webserver:

git clone https://framagit.org/TheEvilSkeleton/theevilskeleton.frama.io.git && cd theevilskeleton.frama.io
bundle install
bundle exec jekyll serve

LoadError

The only issue I got so far is cannot load such file -- $NAME (LoadError), like this one:

❯ bundle exec jekyll serve
Configuration file: /var/home/TheEvilSkeleton/Projects/theevilskeleton.frama.io/_config.yml
            Source: /var/home/TheEvilSkeleton/Projects/theevilskeleton.frama.io
       Destination: /var/home/TheEvilSkeleton/Projects/theevilskeleton.frama.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
       Jekyll Feed: Generating feed for posts
                    done in 0.363 seconds.
 Auto-regeneration: enabled for '/var/home/TheEvilSkeleton/Projects/theevilskeleton.frama.io'
                    ------------------------------------------------
      Jekyll 4.2.0   Please append `--trace` to the `serve` command 
                     for any additional information or backtrace. 
                    ------------------------------------------------
/usr/local/bundle/gems/jekyll-4.2.0/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError)
[...]

This can be easily fixed by executing bundle add $NAME in the root of the website’s source code, where $NAME is the name that will be the output in case of error. In this example you see webrick, so the solution is executing bundle add webrick in the root of the website (if the command is aliased).

This will update your Gemfile and your Gemfile.lock files to include $NAME in them.

Removing container

Removing the container is as easy as toolbox rm -f jekyll.


Enjoy the Toolbox container!