Jekyll is a static-site generator that provides some of the benefits of a Content Management System (CMS) while avoiding the performance and security issues introduced by such database-driven sites. It is “blog-aware” with special features to handle date-organized content, although its usefulness is not limited to blogging sites. Jekyll is well-suited for people who need to work off-line, who prefer to use a lightweight editor instead of web forms for maintaining content, and who wish to use version control to track changes to their website.
In this tutorial, we will install a Jekyll 3.2.1 development site on Ubuntu 16.04. In later tutorials, we’ll explore the content generated here, publish a static site to the same server, and eventually deploy to a production location.
License and legal information
This work is created by Melissa Anderson and is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. I have copied it for the sole purpose of archiving and data centralizing. Minor changes have been made to the original article that you can find on Digital Ocean.
To follow this tutorial, you will need:
- An Ubuntu 16.04 server
- with a non-root user with sudo privileges
Once you’ve completed this prerequisite, you’re ready to install Jekyll and its dependencies.
Step 1 — Installing Jekyll
We’ll start by updating our package list to be sure we have the latest information on the newest versions of packages and their dependencies.
sudo apt-get update
Then we’ll install Ruby and its development libraries as well as
gcc so that Jekyll’s libraries will compile once we install Jekyll:
sudo apt-get install ruby ruby-dev make gcc
When that’s complete, we’ll use Ruby’s
gem package manager to install Jekyll itself as well as Bundler to manage Gem dependencies:
sudo gem install jekyll bundler
gem install jekyll bundler --user-installbut we haven’t tested it yet.
We repeat these operations on our laptop to be able to develop without an internet connection.
Step 2 — Create a new development site
On our laptop, from our home directory, we’ll use Jekyll’s
new command to create scaffolding for a site in a sub-directory called
cd ~ sudo jekyll new docs.sammy.fr #Output New jekyll site installed in /home/sammy/docs.sammy.fr.
Jekyll specifies its default theme, minima, in its Gemfile. We’ll need to run Bundler to install the theme:
cd ~/docs.sammy.fr bundle install
To start jekyll web server locally run the command below and access your site through
Step 3 — Use git to control our versions and deploy
We want to use git to control our versions, record the changes made to the website and deploy it to our web server.
To do so we start by creating a repository on our laptop:
cd ~/docs.sammy.fr git init .
We can then make our initial commit:
git add -A git commit -m "Initial commit"
On our server we create the git repository that will hold our project:
mkdir docs.sammy.fr.git cd docs.sammy.fr.git git --bare init
And we create the directory that will hold the compiled website:
docs.sammy.fr.conf, use Let’s Encrypt to have a SSL certificate, activate the site with
a2ensiteand restart apache.
We add a post-receive hook so that when the server receives a push from our laptop, the jekyll compilation starts and the compiled files are placed in
Here are the contents of the post-receive hook:
GIT_REPO=$HOME/Git/docs.sammy.fr.git TMP_GIT_CLONE=$HOME/tmp/docs.sammy.fr PUBLIC_WWW=/var/www/docs.sammy.fr/public_html rm -rf $TMP_GIT_CLONE git clone $GIT_REPO $TMP_GIT_CLONE cd $TMP_GIT_CLONE bundle exec jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW rm -rf $TMP_GIT_CLONE exit
Now make the hook executable with:
chmod ug+x hooks/post-receive
If you ever need to log your post-receive hook you can add the following code at the beginning of the file:
LOG_FILE=/tmp/postreceive.log # Close STDOUT file descriptor exec 1<&- # Close STDERR FD exec 2<&- # Open STDOUT as $LOG_FILE file for read and write. exec 1<>$LOG_FILE # Redirect STDERR to STDOUT exec 2>&1 echo "This line will appear in $LOG_FILE, not 'on screen'"
We can now run the following command on any laptop that needs to be able to deploy using this hook:
cd ~/docs.sammy.fr git remote add deploy firstname.lastname@example.org:~/Git/docs.sammy.fr.git
Deploying is now as easy as running the following on our laptop:
git push deploy master
Step 4 — Verification
Run manually the following commands on the server to verify that the compilation succeeds:
GIT_REPO=$HOME/Git/docs.sammy.fr.git TMP_GIT_CLONE=$HOME/tmp/docs.sammy.fr PUBLIC_WWW=/var/www/docs.sammy.fr git clone $GIT_REPO $TMP_GIT_CLONE jekyll build -s $TMP_GIT_CLONE -d $PUBLIC_WWW
git clone -b <branch_name> <git_repo> <clone_dir> to clone a specific branch
You might have to install some dependencies with
cd $TMP_GIT_CLONE bundle install
You can also run jekyll locally with
bundle exec jekyll serve
Step 5 — Authentification