Table of Contents
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:
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:
set :application, "Blog"
set :repository, '_site'
set :scm, :none
set :deploy_via, :copy
set :copy_compression, :gzip
set :use_sudo, false
set :user, "deployer"
set :deploy_to, "/home/#{user}/blog"
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
%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:
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 80 default_server;
server_name 123.456.789.10;
root /home/deployer/blog/current;
index index.html
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:
sudo nginx -t
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.
