As mentioned already this site is a Github Pages site uses Jekyll. Here are some notes about using containers to develop with Jekyll.
Jekyll Docker container
The instructions for building your GitHub Pages site locally describes installing Ruby, installing Bundler and running
bundle install locally. All straightforward enough except, I don’t want to maintain a local development environment. In my time as a technical manager I would rate the no.1 time sink in a project being the time it takes for a developer to get thier local development environment up and running without errors. For development to be productive the local development environment setup should be quick, repeatable, platform independent and “just work” every single time. One way to achive this is by using containers, so I did a quick search and found the Official Jekll Docker Image. I did need to spend a little bit of time getting the command line options right, but with that now sorted it’s now working reliably each and every time. Here are the steps I used to get up and running.
Creating a new Jekyll site
Assuming you’ve done the repo setup steps already and are working in the repository root where
README.md is present and want to create a new Jekyll site in this location.
Points to note:
- The Jekyll process in the container needs to write to the local filesystem. If the local filesystem permissions do not allow this an error will appear. In the above command, I’m using the environment variable option to set the UID and GID of the Jekyll process to match that of the owner of the directory so no ownership or permission errors will appear.
- Jekyll will error if the target location for the new project is not empty, in my case the location where I was creating the new Jekyll site already contained a file (LICENSE) so I needed to force Jekyll to write to this location by using the
Serve the Jekyll site locally
jekyll/jekyll Docker container will be using Ruby version 3.1 and Ruby 3.0 broke some things that previously worked because Jekyll serve fails on Ruby 3.0 (webrick missing). The work around is to run the following command once to edit the
Gemfile to include
gem "webrick" (or simple add it directly to the
Next start the webserver:
Test locally by browsing http://localhost:4000
Running rootless with podman
Always needing to use
sudo and requiring the correct
UID is not ideal, it would be simpler if we could run without needing
sudo and worry not about needing to export the correct UID environment variable.
The commands to repeat the above process with
Points to note:
--forceoption is only required when files are already present in the new Jekyll project location.
:Zis required for hosts that have SELinux enabled. This is explained in detail here Podman volumes and SELinux.
- Running the
bundle add webrickcommand is requied only once to update
Save a post without publishing
There is a predefined global variable called
published that can be set to false to save a post and keep it unpublished when the site is generated.