How To: Setting up Jekyll for Heroku

After going through several outdated tutorials, I finally managed to successfully deploy my Jekyll site onto Heroku.

The key is to stay hopeful through your git commits.

In this post, I am going to talk a bit about Jekyll and Heroku, cover on how to set Jekyll up for Heroku deployment and how to use Rake to make life simpler.


Along with building a site with Jekyll, I also wanted to familiarize myself with Heroku. That’s it.

What is Jekyll?

Jekyll was created by Tom Preson-Werner, the co-founder of Github. As to how it came to be, you can read more about it from his post, Blogging Like a Hacker.

Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server.

What is Heroku?

Heroku is basically a cloud platform to build and deploy projects. I chose Heroku because I have heard great things, and the user interface is really clean and simple to use. Also, “Heroku” just sounds really badass. I suspect that I will be using Heroku a lot in the near future so I wanted to familiarize myself with it ASAP.

Heroku is a cloud application platform – a new way of building and deploying web apps.

Our service lets app developers spend their time on their application code, not managing servers, deployment, ongoing operations, or scaling.

Creating a Jekyll Site

My super best blogger best friend Ariel wrote a post about how to Set up Jekyll for Github.io Pages (without the hand-holding experience) along with how to use a Rake Boilerplate. I want to thank her for helping me get started on Jekyll (fortunately, I got the hand-held version).

Note: github.io pages are a great way to host your repo site. It is also easier to set up for and goes hand-in-hand with Jekyll sites. So if you are looking for an alternative host to Heroku, I recommend this route. Each Github account comes with one free github.io page.

I’ll briefly go over how to create a Jekyll site anyways. This is for OS X.

Make sure you have the Jekyll Gem installed
$ gem install jekyll
Use Jekyll to create a new site
$ jekyll new "SITE-NAME"

So for example, if I were to create a jekyll site for charuri:

$ jekyll new charuri

Jekyll will then generate a base site for you under a folder named the charuri, in this case. I am not going to go into detail about the files.

To see immediate results (I would hold off doing this until setting Jekyll up for Heroku), cd into the directory of the site and run:

$ jekyll serve

Setting up Jekyll for Heroku

From my git commits, you can tell that I failed about 3 Jekyll builds before managing to get my site deployable to Heroku. You need to manually edit some settings to tell Heroku what to compile for the Jekyll app.

This is the tutorial that worked out for me, so all credits to Big Binary.

Add exclude vendor to _config.yml

Open _config.yml and add the following line at the very bottom.

exclude: ['vendor']
Add Procfile

Create a new file called Procfile at the root of the project with the following content.

web: bundle exec jekyll build && bundle exec thin start -p$PORT -V
console: echo console  
rake: echo rake
Add Gemfile

Add Gemfile at the root of the project.

source 'https://rubygems.org'

gem 'jekyll', '2.4.0'
gem 'rake'
gem 'foreman'
gem 'thin'
gem 'rack-contrib'

You can install all gems by running this in the root directly of your site:

$ bundler install

If you don’t have the Bundler gem installed:

$ gem install bundler
Add config.ru

Add config.ru at the root of the project with the following content.

require 'rack/contrib/try_static'

use Rack::TryStatic,
	:root => "_site",
	:urls => %w[/],
	:try => ['.html', 'index.html', '/index.html']

run lambda { |env|
  	return [404, {'Content-Type' => 'text/html'}, ['Not Found']]
Test on local machine first.
$ bundle exec jekyll serve

Deploying to Heroku

Now that your site is ready to be deployed to Heroku, let’s get your Heroku repo ready and push your site onto it. Make sure you’re signed up and have an account.

Install Heroku Toolbelt

You can download the installation here. Now you can use the heroku command.

Log into Heroku on your terminal
$ heroku login
Enter your Heroku credentials
Email: charuri@example.com
Create an app on Heroku

This prepares Heroku to receive your source code. This will create an app with a random generated named.

$ heroku create

To create an app with your chosen name:

$ heroku create charuri
Deploy your code
$ git remote add heroku git@heroku.com:charuri.git

If access is needed, you might need to add a key:

$ heroku keys:add

$ git push heroku master

If deployment verification passed, congratulations! Check out your deployed site with:

$ heroku open

Rake Boilerplate

I left this for last because for some reason every time I added in the Rakefile before I set up my site for Heroku, it would always fail. The Rake Boilerplate by gemmesson makes generating your site, creating new posts or pages, much simpler.

The Github README explains pretty well everything, but if you still don’t get it, I’ll try to help.

Setting Up the Rakefile

Just download the rakefile from the Github repo and pop it into your site’s root folder. You’ll want to edit your _config.yml. This is what I added to mine looks like:

# Rake settings
 template: _post.txt
 extension: md
 template: _page.txt
 extension: md
 git: vim
 branch: master
 command: rsync
 settings: -av
 source: _site/
 destination: ~/Documents/projects/charuri/

You can use this time to also edit the rest of your site settings.

From my settings above, I want to create a _post.txt post template:

layout: post

and _page.txt page template, both in the root directory:

layout: page
Now preview your site.
$ rake preview

If a browser tab doesn’t open for you automatically, it will be viewable at localhost:4000.

and if it looks good:

Deploy it!
$ rake deploy["I did it!"]

The rake commands are really useful so I’m going to keep a reference on this post just in case.

rake post["Title"]
rake draft["Title"]
rake publish
rake page["Title"]
	rake page["Title","Path/to/folder"]
rake build
rake watch
	rake watch[number]
	rake watch["drafts"]
rake preview
rake deploy["Commit message"]
rake transfer


I’m still wondering what I gained from deciding to swim through a raging river to the other side of the bank instead of crossing the already built bridge. I suppose I became buffer.

Last but not least, remember to always stay determined! (و ˃̵ᴗ˂̵)و