Deploying your blog with Jekyll

I have just moved from wordpress to Jekyll as my new blogging platform, and it is pretty fun. I now can write my blog posts in Markdown in my favourite text editor, have my blog version controlled with git, and deploy my site with a simple git push.

Deploying Jekyll is easy, but it can as well be confusing to newbs. Thus, I am writing this tutorial.

Choosing a Jekyll theme

There are lots of free Jekyll themes out there for you to choose with a little bit of googling. The theme I am currently using is Jekyll Mon Cahier. If you’re incline to develop your own theme, well, you can do it later after getting used to Jekyll first.

For the sake of this tutorial, I will be using Jekyll Mon Cahier.

git clone https://github.com/btquanto/jekyll_mon_cahier.git ~/blog

Installing and running Jekyll

You can either choose to install Jekyll, or use a pre-built Docker image

Installing Jekyll to your machine

  1. Jekyll is a ruby gem, thus installing ruby is the pre-requisite

     curl -L https://get.rvm.io | bash -s stable --ruby=2.0.0
    
  2. Now is the actuall installing Jekyll part

     gem install jekyll
    
  3. Running your site is easy

     cd ~/blog
     jekyll serve
    

    Learn more about the jekyll serve command with jekyll serve -h

  4. Checkout your blog at localhost:4000

Using docker

  1. Using docker is even neater, but the pre-requisite is that you have to install Docker first. Checkout the instructions on Docker’s website

  2. Then, just pull a pre-built docker image for jekyll. I am using btquanto/docker-jekyll here.

     docker pull btquanto/docker-jekyll
    
  3. Just run your site (follow the instructions of whichever image that you use)

     cd ~/blog
     docker run -u $UID -d \
         --name jekyll \
         -v `pwd`:/src \
         -p 4000:4000 \
         btquanto/docker-jekyll jekyll serve -H 0.0.0.0
    

Deploying your blog

  1. Generate a new ssh key without specifying any password. Save the key to ~/.ssh/id_rsa_np

     ssh-keygen
    
  2. Go to github.com and add the public key of the newly generated key pair to your account.

  3. Open ~/.ssh/config, and add the following content

     Host github.com-np
         HostName github.com
         User git
         IdentityFile ~/.ssh/id_rsa_np
         IdentitiesOnly yes
    
  4. Create some folders for deploying your blog

     sudo mkdir /var/www/
     sudo mkdir /var/www/blog
     sudo chown $USER:$USER /var/www/blog
     mkdir /var/www/site
     mkdir /var/www/scripts
    
  5. Clone your blog

     git clone [email protected]:<username>/<your-blog>.git /var/www/blog/src
    
  6. Add a upstart script for serving your website, save it in /etc/init/jekyll-watch.conf

     description "Start jekyll watch for generating blog"
     author "Quan To <[email protected]>"
    
     start on runlevel [2345]
     stop on runlevel [!2345]
    
     exec su <username> -lc "jekyll build -ws /var/www/blog/src -d /var/www/blog/site"
     respawn
    

    Remember to replace <username> with your username

    Then start the upstart job

     sudo start jekyll-watch
    
  7. Go to your DNS, create an A record, and point to your server.

  8. Create an nginx config in /etc/nginx/sites-available/jekyll-blog

     server {
         listen 80;
    
         server_name your.domain.name;
    
         root /var/www/blog/site/;
         index index.html index.htm index.php;
    
         location / {
         expires off;
             try_files $uri $uri/ =404;
         }
    
         error_page 404 /404.html;
     }
    

    Remember to adjust the file appropriately

    Enable the configuration file using a symlink

     sudo ln -s /etc/nginx/sites-available/jekyll-blog /etc/nginx/sites-enabled/jekyll-blog
    

    Reload nginx

     sudo service nginx reload
    

    Now you can access your website at your.domain.name

  9. Write a script for updating your src folder, put it in /var/www/blog/scripts/update.sh

     #!/bin/bash
     SRC_DIR="/var/www/blog/src"
     cd $SRC_DIR
     git fetch
     git reset origin/master --hard
    

    Give it execution permission

     chmod +x /var/www/blog/scripts/update.sh
    
  10. On your local machine, add an alias for convenient use

    echo "alias update_blog=\"ssh [email protected] /var/www/blog/scripts/update.sh\"" >> ~/.bashrc
    

That’s pretty much done. Now, everytime you want your server to fetch new blog posts from github and regenerate your blog, just call udpate_blog.