We have been serving our documentation and blog on GitHub Pages. This arrangement was convenient; just push to a GitHub repo’s gh-pages branch, and it was live.

This has served us well over the years, but we wanted to serve it over SSL from our custom domain.

To make this happen, we needed to modify the application into a standalone app that can be served on Heroku.

How did we do it?

Using Puma

GitHub Pages sites are served with Jekyll, which comes with a built-in server script. This is handy for local development, but it may not be appropriate for production use.

So we opted for using Puma.

Gemfile

To serve a Jekyll site with Rack, which Puma uses, we add rack-jekyll to Gemfile:

gem 'rack-jekyll'
gem 'puma'

config.ru

Puma needs to know how to serve this app, so add a new file config.ru:

require 'rack/jekyll'
require 'yaml'
run Rack::Jekyll.new

This is a very straightforward configuration suggested by rack-jekyll.

Test locally

Now, confirm that Puma can serve the app:

bundle install
bundle exec puma

Configure deployment to Heroku

Assuming that you have created a Heroku application to deploy this application to, we need to make two more changes to our application.

Procfile

Our application will run as a web Dyno, and it is defined in Procfile as:

web: bundle exec puma -p $PORT

Rake task assets:precompile

In order to serve static sites like ours, Heroku’s default buildpack expects to have a Rake task named assets:precompile.

For Jekyll sites, it just needs to execute jekyll build:

namespace :assets do
  task :precompile do
    puts `bundle exec jekyll build`
  end
end

Be sure that Rakefile can load all the tasks

This might seem obvious, but it bears mentioning explicitly.

Our docs app runs HTML::Proofer to check broken links when commits are pushed to GitHub. This is done via Rake, and the gem was installed only in the :test group.

As a result, rake assets:precompile failed to run until the gem was installed in all groups.

Redirect HTTP to HTTPS

As mentioned in the beginning, our goal was to serve the documentation over SSL. It is, then, vital that all HTTP traffic is redirected to HTTPS so that transition is transparent to users.

To achieve this, we use Rack::SslEnforcer.

Adding this is also straightforward:

Add to Gemfile

gem 'rack-ssl-enforcer'

And to config.ru

require 'rack-ssl-enforcer'

use Rack::SslEnforcer, :except_environments => 'development' # before `run Rack::Jekyll.new`

Deploy, sit back and enjoy!

Head on over to http://docs.travis-ci.com! You will be happily redirected to https://docs.travis-ci.com, and know that we stand behind the document you are viewing.

If you find incorrect information, though, please open a GitHub issue at https://github.com/travis-ci/travis-ci/issues, or better yet, suggest improvements by opening a pull request for https://github.com/travis-ci/docs-travis-ci-com.

Happy testing!