Matthias Sitte bio photo

Matthias Sitte

Just another physicist enthusiastic about Linux and FOSS

Twitter Facebook Google+ LinkedIn XING ResearchGate Google Scholar Github Stackoverflow

Jekyll is a simple web site generator written in Ruby that generates static HTML sites from a template directory that contains some raw text files in various formats, parses those files with the Markdown and Liquid converters, and then creates a complete, portable, and ready-to-publish static website. This static website approach is advantegeous since the resulting website is small, fast, and easy to handle for web servers like Apache2 or nginx. It basically avoids much of the bloat that comes with typical blogs using [Wordpress] or similar blog software, and it reduces the security risks due to the lack of poorly designed plugins.

Jekyll also is the engine behind GitHub Pages used by many people to host their project pages, blogs, or websites from GitHub’s servers for free. A popular way to use Jekyll is to keep your site’s files in a (local) Git repository, to edit them locally, and then to use git push to deploy the site to your web server.

Installing required software packages

First, you need to install Ruby, Jekyll, and Git on your local machine if you haven’t done this already. Installing Jekyll is quite easy and straightforward, and it should only take a few minutes. Before you start, make sure that your system has the following requirements installed:

  • Ruby (including development headers)
  • RubyGems
  • NodeJS, or another JavaScript runtime (for CoffeeScript support).

Assuming that you are running an up-to-date Debian or Debian-based Linux OS like Ubuntu, you can install Ruby and RubyGems with the appropriate development headers with a single command:

workstation$ sudo apt-get install ruby ruby-dev rubygems

The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:

workstation$ sudo gem install jekyll

This will install all of Jekyll’s gem dependencies automatically so you don’t have to worry about them at all.

Now you need Git which you can easily using your package manager:

workstation$ sudo apt-get install git

Creating a website

The Jekyll website has a nice quick-start guide to using the tool, as well as thorough documentation. Here, we will only cover the basic usage of Jekyll, but you may refer to their documentation for day-to-day usage and customization.

Create a folder on your local computer where you want to store your website files, and create a new blog using Jekyll’s new command:

workstation$ jekyll new new_website

This will create an new_website/ directory containing the configuration files, a posts directory, and other required bits. Now you can enter that directory and start up a server process to preview the website in your browser:

workstation$ cd new_website
workstation$ jekyll serve

Jekyll will build your blog, and after a few seconds you should be able to visit http://localhost:4000 in your browser.

Prepare the server

For the sake of concretenes, we will assume that you have already set up a server running a web server like Apache2 or nginx. We will also assume that the document root of the web server is the /var/www directory.

First, you will need to install Jekyll and Git. For Debian and Ubuntu, you will have to install the following packages:

server$ sudo apt-get install ruby ruby-dev rubygems git-core

To have a remote server handle the deployment for you every time you push changes using Git, you can create a user account deploy which has all the public keys that are authorized to deploy in its authorized_keys file:

server$ sudo useradd deploy

Now change into the home directory of the newly created deploy and create a new “bare repository” to deploy to:

server$ su deploy
server$ cd
server$ mkdir repos
server$ cd repos
server$ git init --bare new_website.git

With that in place, set up the post-receive hook is done as follows:

server$ cd new_website
server$ cp hooks/post-receive.sample hooks/post-receive
server$ chmod +x hooks/post-receive
server$ exit

Now add the following lines to hooks/post-receive script and make sure that the web server’s document root /var/www has write permissions for the deploy user:

GIT_REPO=$HOME/repos/new_website.git
TMP_GIT_CLONE=$HOME/tmp/new_website
PUBLIC_WWW=/var/www

git clone $GIT_REPO $TMP_GIT_CLONE
jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW
rm -Rf $TMP_GIT_CLONE
exit

Local Git repository

Now it’s time to set up a local Git repository in the same directory as the Jekyll website so that any changes you make can be tracked:

workstation$ git init .
workstation$ git add .
workstation$ git commit -m "Initial commit"

Run the following command on any users that need to be able to deploy using this hook:

workstation$ git remote add deploy deploy@example.com:~/repos/new_website.git

Finally, deploying is now as easy as running the following Git push command:

workstation$ git push deploy master