« Back to home

Setting up Octopress

Posted on
Setting up Octopress

This is an old post. It may contain broken links and outdated information.

I'm no superhacker, and the reason I at first passed up Octopress (which this blog uses) in favor of things like Wordpress and Drupal and Joomla is because of the wealth of documentation available for those platforms—and, more to the point, the ease of googling for the inevitable error messages. I tend to measure GNU/Linux activities not by the amount of time they take to conclude, but rather by their NTO rating—that's "Number of Tabs Opened". Every time I read about a configuration gotcha or pitfall that I need to remember, I'll pop open a new tab and leave the important info up in its original; when I hit a roadblock or something doesn't work right, it's another Firefox tab and another trip to Google. Most of my Linux projects have extremely high NTO ratings, and getting Wordpress and MySQL/MariaDB going was no exception (and it didn't help that I made an abortive attempt to use PostgreSQL as my back-end database, just for the hell of it).

Installing Octopress, on the other hand, is a relatively simple activity because the preinstall tasks aren't that complex. There's no database to configure and no PHP or perl to screw with; in fact, you don't even need a web server, as Octopress comes with the built-in ability to publish itself to Github. You simply need Git, in order to pull down the software, and a functional Ruby framework, to do the page generating and compiling and publishing.

Here at Bigdinosaur.org, we're currently running Ubuntu Server 11.10, with Nginx and php-fpm for serving static and dynamic web content. I didn't have Git or Ruby installed, so I had to install these. There also ended up being two additional prerequisite packages I didn't have, and not having them prior to installing Ruby caused significant problems with making Octopress work. To save any readers the same frustration I went through, I'll list them along with everything else below.

First things first, to get Octopress up and running on Ubuntu 11.10, you'll need to install the following:

$ sudo aptitude install git build-essential zlib1g-dev libssl-dev 

Git is necessary because the Octopress installation files are housed in a git repository. Build-essential is needed because we'll be compiling Ruby (but fear not, as it's an automated process!), and zlib1g-dev and libssl-dev install libraries that need to be included when Ruby is built, because otherwise it'll throw errors when you're setting up Octopress or generating your static pages.

I went with rbenv over RVM, because rbenv is lighter and lacks the shell alterations of RVM.

The next step is to install Ruby, and how you do this depends on your platform. For GNU/Linux, the Octopress docs recommend using either RVM or rbenv, both of which are version management tools which let you easily manage Ruby installs. I went with rbenv over RVM, because rbenv is lighter and lacks the shell alterations of RVM. There are some outstanding and detailed instructions available on installing and configuring rbenv, and I won't copy them here because the linked page does an excellent job of explaining what to do.

After rbenv was instaled I ran into my first snag, which ended up being due to the absence of the zlib1g-dev package. When running the command gem install bundler, I received the following error:

$ gem install bundler
ERROR:  Loading command: install (LoadError)  
    no such file to load -- zlib
ERROR:  While executing gem ... (NameError)  
    uninitialized constant Gem::Commands::InstallCommand

The solution was to install zlib1g-dev, and then re-run rbenv install 1.9.2-p290 to rebuild Ruby, which will then be rebuilt with zlib support.

I already have a web server, and so I chose to configure Octopress to use its rsync deploy method to publish pages. I made a small test entry and told Octopress to generate a set of pages for the very first time...and ran into my second snag.

$ rake generate
(in /home/lee/octopress)
## Generating Site with Jekyll
directory source/stylesheets/  
   create source/stylesheets/screen.css 
Configuration from /home/lee/octopress/_config.yml  
/home/lee/.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 /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/1.9.1/net/https.rb:92:in `<top (required)>'
    from /home/lee/octopress/plugins/gist_tag.rb:10:in `require'
http://octopress.org/    from /home/lee/octopress/plugins/gist_tag.rb:10:in `<top (required)>'  
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/site.rb:76:in `require'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/site.rb:76:in `block in setup'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/site.rb:75:in `each'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/site.rb:75:in `setup'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/site.rb:30:in `initialize'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/bin/jekyll:224:in `new'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/bin/jekyll:224:in `<top (required)>'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/bin/jekyll:19:in `load'
    from /home/lee/.rbenv/versions/1.9.2-p290/lib/ruby/gems/1.9.1/bin/jekyll:19:in `<main>'

The similarities of the errors—"no such file to load"—led me to be hopeful that I could resolve the problem by another quick library install. I already had the main openssl package installed, but that package doesn't put any libraries in /usr/include. What is needed is the libssl-dev package, which stuffs /usr/include/openssl full of yummy library files. As with the zlib issue above, if you run into this issue, the fix is to install the missing library and then re-run rbenv install 1.9.2-p290 to re-build Ruby with openssl support.

And that was it—the install and build and publish process was successful. The only way that my experience diverged from the install documents was in having to install the two additional libraries so that Ruby would build with the right things mixed into it. Other than that, getting Octopress onto Ubuntu Server was strictly a paint-by-numbers affair. Hooray!

Discuss this post on the BigDinosaur forums