Thursday, 14 December, 2017 UTC
Summary
Jekyll, the static website generator written in Ruby and popularized by GitHub, is a great candidate for being run on Heroku. Originally built to run on GitHub Pages, running Jekyll on Heroku allows you to take advantage of Jekyll’s powerful plugin system to do more than convert Markdown to HTML. On my blog, I have plugins to download my Goodreads current and recently read books and to generate Open Graph images for posts. That said, it’s not straightforward to get up and running on Heroku without using
jekyll serve to do the heavy lifting. jekyll serve uses Ruby’s built-in, single threaded web server WEBrick, but a public site should be using a web server more suited for production, like nginx.We’ll start from the very beginning. You’ll need Ruby and Bundler installed.
I like ruby-install and chruby as my Ruby installer and switcher.
This is the platform-agnostic way of installing the latest version of ruby-install. If you prefer, you can find instructions for OS X and Windows in ruby-install’s README.
The commands below use the most recent versions of ruby-install and chruby available when this post was published. You probably want to use more recent versions if available.
$ wget -O ruby-install-0.6.1.tar.gz https://github.com/postmodern/ruby-install/archive/v0.6.1.tar.gz $ tar -xzvf ruby-install-0.6.1.tar.gz $ cd ruby-install-0.6.1/ $ sudo make install You’ll also want chruby, which you can similarly install in a more platform specific way using instructions in chruby’s README.
$ wget -O chruby-0.3.9.tar.gz https://github.com/postmodern/chruby/archive/v0.3.9.tar.gz $ tar -xzvf chruby-0.3.9.tar.gz $ cd chruby-0.3.9/ $ sudo make install Install the latest Ruby and use it:
$ ruby-install ruby $ chruby ruby You’ll need Bundler and the Jekyll gem:
$ gem install bundler jekyll Fetching: bundler-1.9.9.gem (100%) Successfully installed bundler-1.9.9 Fetching: jekyll-3.6.2.gem (100%) Successfully installed jekyll-3.6.2 2 gems installed Generating a new jekyll site is straightforward, and you get a site template for free similar to starting a new Rails app. We’ll be saving our work in Git along the way:
$ jekyll new jekyll-on-heroku Ignoring nokogiri-1.8.1 because its extensions are not built. Try: gem pristine nokogiri --version 1.8.1 Running bundle install in /Users/caleb.thompson/code/jekyll-on-heroku/_rundoc/tmp/jekyll-on-heroku... … New jekyll site installed in /Users/caleb.thompson/code/jekyll-on-heroku/_rundoc/tmp/jekyll-on-heroku. $ cd jekyll-on-heroku $ git init Initialized empty Git repository in /Users/caleb.thompson/code/jekyll-on-heroku/_rundoc/tmp/jekyll-on-heroku/.git/ $ git add . $ git commit -m "jekyll new jekyll-on-heroku" [master (root-commit) ea8cd80] jekyll new jekyll-on-heroku 8 files changed, 206 insertions(+) create mode 100644 .gitignore create mode 100644 404.html create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 _config.yml create mode 100644 _posts/2017-12-07-welcome-to-jekyll.markdown create mode 100644 about.md create mode 100644 index.md We have our Jekyll site (go ahead and try
jekyll serve if you’d like), but we’ll need a Heroku app to deploy to. You will need an account and the CLI installed before this step. We’re going to use the official Ruby buildpack as well as Heroku’s (unofficial) Static buildpack to do the site generation and static page serving, respectively:$ heroku create Creating app... done, radiant-bastion-50307 https://radiant-bastion-50307.herokuapp.com/ | https://git.heroku.com/radiant-bastion-50307.git $ heroku buildpacks:add heroku/ruby Buildpack added. Next release on radiant-bastion-50307 will use heroku/ruby. Run git push heroku master to create a new release using this buildpack. $ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-static Buildpack added. Next release on radiant-bastion-50307 will use: 1. heroku/ruby 2. https://github.com/heroku/heroku-buildpack-static Run git push heroku master to create a new release using these buildpacks. Heroku’s buildpacks need specific files to be present to work correctly. We already have
Gemfile for the Ruby buildpack, but we’ll also need a static.json file for the static buildpack. I’ve added a few of my favorite options to the static.json, and we’ll need to use _site/ for our root as that is where Jekyll builds its static content by default.In file
static.json write:{ "clean_urls": true, "https_only": true, "root": "_site/" } Let’s save our progress again.
$ git add static.json $ git commit -m "Add static.json with reasonable defaults" [master 6e1dea7] Add static.json with reasonable defaults 1 file changed, 5 insertions(+) create mode 100644 static.json The Ruby buildpack runs
rake assets:precompile when it’s available. This is inspired by Rails’ pattern, but it works for any assets you’ll need. We’re going to use it for our entire site by running jekyll build.In file
Rakefile write:task "assets:precompile" do exec("jekyll build") end You’ll need Rake to run this in the first place, and we can save ourselves trouble in the future by specifying a version.
At the end of
Gemfile add:gem "rake" ruby "2.4.2" And run
bundle to install Rake.$ bundle … Bundle complete! 5 Gemfile dependencies, 24 gems now installed. Use `bundle info [gemname]` to see where a bundled gem is installed. We need to add the changes for the Rake task and new dependencies:
$ git add Rakefile Gemfile Gemfile.lock $ git commit -m "Add Rake task to build Jekyll site" [master 94f664b] Add Rake task to build Jekyll site 3 files changed, 10 insertions(+) create mode 100644 Rakefile Finally, we can push the app to Heroku!
$ git push heroku master warning: not sending a push certificate since the receiving end does not support --signed push remote: Compressing source files... done. remote: Building source: remote: remote: -----> Ruby app detected remote: -----> Compiling Ruby remote: -----> Using Ruby version: ruby-2.4.2 remote: -----> Installing dependencies using bundler 1.15.2 remote: Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment … remote: -----> Detecting rake tasks remote: -----> Precompiling assets remote: Running: rake assets:precompile remote: Configuration file: /tmp/build_c29844d07a39f5ce14fd64c34fc17680/_config.yml remote: Source: /tmp/build_c29844d07a39f5ce14fd64c34fc17680 remote: Destination: /tmp/build_c29844d07a39f5ce14fd64c34fc17680/_site remote: Incremental build: disabled. Enable with --incremental remote: Generating... remote: done in 0.901 seconds. remote: Auto-regeneration: disabled. Use --watch to enable. remote: Asset precompilation completed (1.49s) remote: remote: ###### WARNING: remote: No Procfile detected, using the default web server. remote: We recommend explicitly declaring how to boot your server process via a Procfile. remote: https://devcenter.heroku.com/articles/ruby-default-web-server remote: remote: -----> Static HTML app detected remote: % Total % Received % Xferd Average Speed Time Time Time Current remote: 100 838k 100 838k 0 0 5598k 0 --:--:-- --:--:-- --:--:-- 5628k remote: -----> Installed directory to /app/bin remote: -----> Discovering process types remote: Procfile declares types -> (none) remote: Default types for buildpack -> web remote: remote: -----> Compressing... remote: Done: 26.4M remote: -----> Launching... remote: Released v3 remote: https://radiant-bastion-50307.herokuapp.com/ deployed to Heroku remote: remote: Verifying deploy... done. To https://git.heroku.com/radiant-bastion-50307.git * [new branch] master -> master Open the URL at the end and enjoy your new Jekyll app on Heroku!