My blog with Jekyll, Part 2 : Setting things up

9 minute read

This article is part of a three articles long series telling how I set up my blog (the very one you’re reading). This series contains:

This is the second part of the series and here, we will focus on setting all I call ‘the infrastructure’ ; from the setting up of Jekyll on my main machine to addressing some of Jekyll limitations.

REQUIREMENTS FOR A JOURNEY IN BITS

As I wanted to start this blog series by talking about the choice of the blogging platform, I end up brushing about the requirements of the blog. It’s not really an issue if you forget about messiness since regardless of the winning platform, I wanted to have these following capacities:

  • ability to fully modify my blog from at least my main development machine, from editing a blog post to change a plugin to even write one,
  • ability to write and edit blog posts and other files from any machine connected to internet,
  • ability to host it freely and efficiently.

So I had the current challenges to address:

  • Install and configure a Jekyll ready environment on my main laptop,
  • Find a free hosting provider,
  • Find a way to edit my blog posts over the internet.

SETTING UP THE MAIN OFFICE

Since my main development machine is a laptop running on Archlinux and to avoid lengthening this post, all the instructions when needed to be specific will be targeted at the Archlinux distribution. Jekyll is made in Ruby and so needs a Ruby development environment to function. A bit of research made me realise that Jekyll was in my favorite distribution’s User Package Repository (AUR). So I thought I might end this setup in two to three moves.

Turns out it was a bit more complicated than that. A Ruby version was already installed on system level and it was incompatible with the version needed for Jekyll. As I plan to keep my blog gems up to date (new is always better), constantly messing with the system level Ruby and gems was out of question. What I needed was a way to have different version of ruby and gems switchable at runtime, a kind of version manager.

When I started this blog, I was new in the Ruby world, and things were a bit messy. So let’s review the Ruby toolings first before implementing the solution.

Since talking about the distribution will uselessly lengthen this article, you might go to the Further Reading section to have more infos about Archlinux, it’s package manager and how to install software in AUR.

A word on Ruby tooling

The Ruby tooling world is messy (repetition is pedagogy and emphasis) and can be hard to get for a starter in Ruby. It is composed of:

  • an integrated package manager, RubyGems: RubyGems is the standard package manager of the Ruby world. It’s integrated in the distributions of Ruby since the version 1.9. Thanks to it, ruby programs and libraries are packaged in a self-contained format called ‘gems’. It used throughout a command line utility called gem.

  • a de-facto package manager, Bundler: Why would you use Bundler over RubyGems ? Because dependencies management. With RubyGems, you provide your program/library as one big bundle whereas Bundler provide allow you to provide only your code and a file called Gemfile which list your dependencies. A single command and all gems are installed. In essence, Bundler act as a wrapper on top of RubyGems.

  • a Ruby version manager: the kind of tool I needed. It allow you to have multiple versions of Ruby installed on a single version. In order to provide this separation, these tools install a ruby version in a separate, non standard directory (generally an ensemble of subdirectories in your home folder) and provide you a mean to switch the version on-the-fly. The more used of them are:

    • Ruby Version Manager (RVM): the most established of the profession. Although great, it doesn’t work well with Bundler. It also override some of linux command to do his job (some say it’s ok while other think it’s an aberration)
    • rbenv: the current challenger. It’s meant to be lighter than RVM.

For the tooling, I end up with rbenv and bundle as I find them lighter for the first and efficient for the second.

The actual setup

Alright so let’s install our environment. We first need to install rbenv and distinct version of Ruby to avoid messing with the system-wide one. Since rbenv is in archlinux’s AUR, I only have to use an AUR Helper (yaourt in my case) to do it. rbenv also use ruby-build for an easier installation of ruby version. The installation steps are inspired by the documentation. In my case I had to do :

# install ruby-build
yaourt ruby-build

# install rbenv
yaourt rbenv

# doing that will show you the instructions to setup rbenv once for all
rbenv init

# while the instructions from the previous command asked to put 'eval "$(rbenv init -)"'
# in the ~/.bash_profile file, on Archlinux and derivates it works only if you add
# the line in the ~/.bashrc file. So we just do
echo 'eval "$(rbenv init -)"' >> ~/.bashrc

# download and execute rbenv-doctor to ensure everything is good to go
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

# list the available versions of rbenv
rbenv install -l

# Install the desired version, for exemple Ruby 2.5.0
rbenv install 2.4.3

# Ensure our current shell is configured with the wanted Ruby version
rbenv shell 2.43

Note that the last command will be reproduce everytime we fire a new shell and are willing to work with a different Ruby version. To circumvent it, we need to add a file at the root of our blog or ruby application containing the Ruby version we want to use. This version has to be exact with one of those installed through rbenv install. The instruction to do that will be provide below.

We can now proceed with the installation of Bundler and Jekyll. Thanks to the documentation of Jekyll, it was pretty straightforward. All I had to do was:

# Install Jekyll and Bundler gems through RubyGems
gem install jekyll bundler

# Since we installed executables gems, we need to tell rbenv to take them into account
rbenv rehash

# Create a new Jekyll site at ./my-blog
jekyll new my-blog

# Change into your new directory
cd my-blog

# Set the Ruby version needed by the blog, so we won't need to do precise it everytime
echo '2.4.3' > .ruby-version

# Build the site on the preview server
bundle exec jekyll serve

# Now browse to http://localhost:4000

Our blog is now available at http://localhost:4000 and looks like

jekyll-working
A working blog on Jekyll.

Now that I had a platform ready to accept content, I needed to host.

HOSTING FREE(DOM)

You might ask yourselves what would I want a free service ? Easy. While I was searching I discovered that I could achieve free and performing hosting depending on my technological stack. It was a strong plus for Jekyll. They was three serious contender: Github, Gitlab and Netlify.

  • Github, the home of free software was an appealing contender. It offer free static site hosting. To do so just push your code in a repository named following the pattern your-username.github.io and you’re good to go ; they will automatically build and publish it. You can even put a CNAME redirection to use your domain name. Three reason made me ditch it: the blog repository needs to be public, no all Jekyll plugins are allowed by they automatic build system and they was better then them in optimizing your website.

  • Gitlab, is one of Github challenger with pretty good offer on the git repository department. They static site hosting was the same than github with a few differences: you can have a private repository and there’s no limitation in the plugin department. Ditched because of optimization too.

The winner was Netlify. Not only they were they providing the same automatically build-n-deploy on push than Gitlab and Github, the same Jekyll plugin freedom than Gitlab but also CDN functionalities and HTTPS. And all that free as a beer. To use Netlify as a hosting platform for a static site is simple and the documentation made a great deal at explaining. For the sake of brevity, only the steps I took to achieve that are mentioned below.

  • Sign up for an account on Netlify,
  • Connect my blog’s repository platform,
  • Configure a Netlify website for Jekyll,
  • Change my domain name DNS to Netlify’s because my domain name provider didn’t have ALIAS records,
  • Manually obtain a wildcard certificate with Let’s Encrypt ; Netlify auto HTTPS certificate wasn’t providing such certificate which I was in need.

EDITING MY BLOG EVERYWHERE I GO

One drawback with using Jekyll as blogging platform is that you need to install and configure the whole pack (rbenv, Ruby, Bundler, Jekyll, git ) before being able to start editing your blog. Now I could and probably may end up setting up a containerized environment I would push on every machine I want to use but I will save it for another blog post…or not. Plus it’s really only convenient on a development machine. What if I go super saiyan with an idea of a post and all I have in the hands is my slate tablet ?

To circumvent this limitation, I one can use online editors which have the ability to commit your modification directly to you repository. You just have to sign up for an account, connect your repository through its platform and you’re good to go. They provide you with an editor with preview so you have an idea of the result.

Two strong contender where Prose and Forestry. Prose lose the competition because it could connect only to github but also because it was the less polished of the two. Forestry really live up to its promise: A static CMS that commits. Moreover, it can connect with Github, Gitlab or Bitbucket. And last but not least, it support many collaborators. A big thumbs up.

So once I created an account to Forestry and connected my blog repository on gitlab to it, I was on the editor below.

image-center

You don’t edit your post as markdown, the editor window will generate it for you, but it’s great. I can quickly edit existing articles or write entire new drafts then finish it later on my main development machine. Other than that, you can add Jekyll data files, add medias, template and edit the posts front matters. With this last one, all the ‘infrastructure’ requirements have been fulfilled.

WRAP IT UP

Wow, that was a long one. The very first of all. Now that I have talked about the setting up, let’s achieve the series with the customization of the blog next. It won’t be that long, I promise.

FURTHER READING

Archlinux is my favorite linux distribution. It’s a rolling release distribution aiming to follow the KISS principle and being close to packages maintainers’ recommendations and decisions. You can read a bit more about it here and there. One of it’s interesting feature is the AUR repository and the AUR Helpers. I use Yaourt as AUR helper.

ACKNOWLEDGMENTS

Thanks to Mariam Nourya Koné for reviewing and suggestions.