How To Get Started with Jekyll on an Ubuntu VPS

Introduction

Jekyll is a simple static site generator. It takes pages input in Markdown, Textile, Liquid, HTML, and CSS, and outputs complete static HTML pages. Jekyll works well with GitHub Pages, but there are some limitations - for example, it's not particularly easy to work with plugins. Thus, hosting a Jekyll site on your own VPS can be a good idea. Doing so is easy!

Installing Requirements

If you haven't already, install Ruby and RubyGems. The best way to do this is using the Ruby Version Manager (RVM). Use the command from the RVM homepage (rvm.io), which should look something like:

curl -L https://get.rvm.io | bash -s stable --ruby=2.0.0

Follow any other prompts to install Ruby on your system. Once it's installed, you can install the the required gems:

gem install jekyll capistrano

Creating a Blog With Jekyll

Jekyll's website has a quick start guide that steps you through creating a simple Jekyll site and serving it. There's plenty more usage details there. We'll start by creating a simple blog. Switch into the directory you'd like to work from, and run:

Navigate to the "myblog" directory and you should see a few folders. The one we care about is _site; this one contains the static site generated by Jekyll, which we will be deploying in the next step.

Setting Up the Blog for Deployment With Capistrano

If your Jekyll site is still running (after running jekyll serve), quit that process. Still in the "myblog" directory, run:

capify .

This creates the necessary files for a Capistrano deployment. Capistrano is "opinionated software" that assumes you'll be deploying via SSH. When you run the command, it should have created a file at config/deploy.rb; open it, and update it to resemble this:

# replace this with your site's name
set :application, "Blog"
set :repository, '_site'
set :scm, :none
set :deploy_via, :copy
set :copy_compression, :gzip
set :use_sudo, false
# the name of the user that should be used for deployments on your VPS
set :user, "deployer"
# the path to deploy to on your VPS
set :deploy_to, "/home/#{user}/blog"
# the ip address of your VPS
role :web, "123.456.789.10"
before 'deploy:update', 'deploy:update_jekyll'
namespace :deploy do
[:start, :stop, :restart, :finalize_update].each do |t|
desc "#{t} task is a no-op with jekyll"
task t, :roles => :app do ; end
end
desc 'Run jekyll to update site before uploading'
task :update_jekyll do
# clear existing _site
# build site using jekyll
# remove Capistrano stuff from build
%x(rm -rf _site/* && jekyll build && rm _site/Capfile && rm -rf _site/config)
end
end

The next step is to set up the VPS with the directory structure required by Capistrano. You only need to do this once:

cap deploy:setup

Finally, deploy your VPS:

cap deploy

Capistrano's deploy task will:

Remove any existing static Jekyll sites

Build your Jekyll site

Clean up uneccessary files included in the build (mostly cap files)

Copy the contents of your static site, via SFTP, to your VPS, dropping them in the specified directory

Hosting Your Blog With nginx

Back on your VPS, switch into the nginx sites-available directory. This is generally located at:

cd /etc/nginx/sites-available

If you run ls in this directory you should (at least) see a file called "default". If you like, you can use this as a template:

For a static site, you don't need much configuration. The following configuration should work as a bare minimum:

server {
# listen on http (port 80)
# remove the "default_server" if you are running multiple sites off the same VPS
listen 80 default_server;
# the IP address of your VPS
server_name 123.456.789.10;
# see http://nginx.org/en/docs/http/server_names.html for options
# to use your own domain, point a DNS A record at this IP address
# and set the server name to (eg.) "blog.example.com"
# the path you deployed to. this should match whatever was in your
# Capistrano deploy file, with "/current" appended to the end
# (Capistrano symlinks to this to your current site)
root /home/deployer/blog/current;
index index.html
# how long should static files be cached for, see http://nginx.org/en/docs/http/ngx_http_headers_module.html for options.
expires 1d;
}

Alternatively you can use this gist to get the bare essentials. Either way, create a new file in this directory with your desired nginx configuration. Once you've created it, you need to create a symlink to it from the sites-enabled directory:

Using symlinks means it's easy to take a site offline by removing the symlink without touching the original configuration file.

Next, make sure nginx is able to read the files it will be serving. Nginx needs to be able to read and execute everything everything in the directory it's hosting, and all parent directories. To do this, we'll give ownership of the site's directory to the nginx user, www-data. Then we'll give it read and execute access to the required directories: