// Tutorial //

How To Get Started with Jekyll on an Ubuntu VPS

Published on August 28, 2013
Default avatar
By Alex Ghiculescu
Developer and author at DigitalOcean.
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!

In this guide we are going to use the following:

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.


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
10 Comments

When running “cap deploy:setup”, I get this error message:

“Stage not set, please call something such as ‘cap production deploy’, where production is a stage you have defined”

This tutorial is outdated. I’m stuck.

If you got the “warning: remote HEAD refers to nonexistent ref, unable to checkout” similar error, you need to change default git repos HEAD file:

Change ref: refs/heads/master to ref: refs/heads/your_branch

In the instructions you say jekyll new . and then cd myblog, but the former creates the directory tree in the current tree; a directory named myblog is not created. There is no need to change directory if the current directory was the intended target and jekyll new . was executed, right?

Is capistrano or anything like it really necessary? Assuming only moderate blog traffic, would jekyll serve not work ok? I guess I’d need to create some kind of startup configuration to start it up on system boot, but isn’t something like capistrano overkill for that? (Or maybe not, I’m not really knowledgeable about it.)

Can you either remove or update this article cause its completely inaccurate. Thank you

Why does the webserver need to own the files in the webroot? I think you are wrong and it’s a security risk.

@dj.wibby or if you’re not using a Gemfile:

gem install capistrano -v 2.15.4

Use the old capistrano in your Gemfile:

Deployment

gem “capistrano”, “~>2.15.4”

@js.magoon Really?! Could you list the steps you took into deploying your app?