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!

In this guide we are going to use the following:

• Jekyll for write our content
• nginx to serve our content
• Capistrano to deploy

Installing Requirements

On your VPS:

1. Set up an Ubuntu VPS
2. Install and start nginx

Locally:

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:

jekyll new .
cd myblog
jekyll serve

You should be able to see your site running at localhost:4000.

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:

1. Remove any existing static Jekyll sites
2. Build your Jekyll site
3. Clean up uneccessary files included in the build (mostly cap files)
4. 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:

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/example.com

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:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com

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:

sudo chown -R www-data:www-data /home/deployer/blog/current
sudo chmod 755 -R /home

Finally, you should tell nginx to update its configuration. You can do this by:

# tests the nginx configuration; if this is not successful you should fix any errors raised
sudo nginx -t

# safely restarts the nginx worker
sudo kill -HUP `cat /var/run/nginx.pid`

Alternatively, you can just restart nginx. But the above option is generally considered safer.

sudo service nginx restart

Testing And Going Forward

Navigate to the IP address of your VPS. You should see the homepage of your Jekyll site!

What’s next? You can now start writing content and customizing your site with Jekyll. Whenever you have new content you’d like to push online, it’s as easy as doing as doing cap deploy.