Rob Hunter

How to Install Octopress on Ubuntu

This guide covers the basics of installing Octopress on on Ubuntu. The process is very similar to installing Octopress on Debian, but with a couple of extra steps. As with Debian, I recommend rbenv over rvm for Ruby version management. However, there’s no package for ruby-build, so we’ll have to retrieve the source from Github.

First, install the dependencies for working with git and Ruby. It’s likely that you’ll have some of these installed already.

$ sudo apt-get install build-essential git rbenv zlib1g-dev libssl-dev

Without the zlib1g-dev package, you will encounter errors later on while trying to install Ruby gems.* The last package, libssl-dev, is necessary only if you plan to deploy through Rsync (more on that below).

Next, initialize rbenv:

$ rbenv init
$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc

Restart your shell:

$ source ~/.bashrc

The ruby-build package provides an install command for use with rbenv. Unlike Debian, Ubuntu doesn’t have ruby-build in its repositories (note that ruby-builder, which is in the Ubuntu repositories, is not the same thing as ruby-build). Instead, we’ll have to retrieve and install ruby-build via Github. The maintainer of ruby-build has some fantastic documentation on how to do that here. You only need to enter the three commands listed under the line “If you only intend to use ruby-build via rbenv then you can install it locally as a plugin,” e.g.:

$ mkdir -p ~/.rbenv/plugins
$ cd ~/.rbenv/plugins
$ git clone git://github.com/sstephenson/ruby-build.git

What may not be obvious, however, is that you need to then issue an additional command from within the ~/.rbenv/plugins directory:

$ sudo ./install.sh

This launches the installation script for ruby-build. Afterwards, you may need to restart your shell again with $ source ~/.bashrc.

Now, you can use the install command for rbenv, provided by ruby-build, to install the version of Ruby appropriate for Octopress:

$ rbenv install 1.9.2-p290

This will take a while. Once rbenv reports that Ruby has been installed, issue the following command:

$ rbenv rehash

Now, you’re ready to install Octopress. Clone the Octopress Github repository into whatever folder you please, e.g.:

$ mkdir -p ~/Projects/Octopress
$ git clone git://github.com/imathis/octopress.git ~/Projects/Octopress

Now, verify that the appropriate version of Ruby is specified for your Octopress directory.

$ cd ~/Projects/Octopress
$ ruby -v

If the ruby -v command doesn’t report that you’re using Ruby 1.9.2, then make sure you’ve entered all the previous commands correctly.

At this point you can follow the directions as they’re specified at octopress.org:

$ gem install bundler
$ rbenv rehash
$ bundle install
$ rake install

You can now deploy Octopress and start blogging! I prefer to deploy through Rsync, but note that this requires using SSH (as well as a webhost that permits the use of SSH). If you’re unfamiliar with the basics of SSH, there’s a good guide on generating key pairs here. For hosting I use NearlyFreeSpeech, which offers SSH access (although you have to submit a support request for SSH to be enabled for your account).

If you deploy through Rsync, you may encounter errors** unless you installed the libssl-dev package. If you didn’t do so already, install it now:

$ sudo apt-get install libssl-dev

Then, re-install Ruby so it can be built against the new libraries:

$ rbenv install 1.9.2-p290

Once you have your deployment set up, you’re ready to edit and publish blog posts. Note that Octopress posts are written using the Markdown syntax.

* Specifically, you’ll see something like this:

$ gem install bundler
ERROR:  Loading command: install (LoadError)
    no such file to load -- zlib
    ...

** The error messages will look something like this:

$ rake generate
(in ~/octopress)
## Generating Site with Jekyll
directory source/stylesheets/
   create source/stylesheets/screen.css
Configuration from ~/octopress/_config.yml
~/.rbenv/versions/1.9.2-p290/lib/ruby/1.9.1/net/https.rb:92:in `require': no such file to load -- openssl (LoadError)
 from ~/.rbenv/versions/1.9.2-p290/lib/ruby/1.9.1/net/https.rb:92:in `'
  from ~/octopress/plugins/gist_tag.rb:10:in `require'
  ...