Simplicity is the ultimate sophistication

Setting Up a Blog With Octopress

| Comments

Why Octopress

My web site is powered by Django so I would like explain before why I’m not providing the blog using the built-in framework. The main reason is that I want to keep separate the blog instance from the corporate (standard home page) one: this means different content, different formatting, essentially different entities. The website is dedicated to customers, of would-be ones, while the blog is more for hackers, colleagues like me.

The second reason is that the Django framework is intended to be the basement on which to provide a web site and a set of future web applications that require the full capabilities of a purely dynamic environment. Instead the blog is something that grows daily but its past content is essentially static. So this is a good reason to provide my blog a completely static suit: easier management, faster access times and minor load for the server.

Unfortunately I wasn’t able to find a Django-powered static-site generator with specific dedication to blogger needs. Recently I had the chance to read this excellent post from Matt Gemmel that explains the reasons why he decided to move his blogging platform from the dynamic Wordpress generator to Octopress.

So I decided to setup Octopress for my blog and in this article, by the way this is the first of my blog, I would like to show the steps I followed to implement it in my environment. Octopress official documentation is good and up to date but as it is organized in a series of articles is not completely linear and in some cases you may get in trouble in getting all things working.

What is Octopress

Octopress is a framework built in Ruby and based on the static web-site generator Jekyll (which powers Github Pages). It comes packaged with a basic layout (which is the one you can see in this page) and a set of 3rd party settings and plug-ins that provide functionalities perfectly suited for hackers, such as syntax highlighting and code blocks, Disqus comments integration, twitter sidebar, CSS only pull quotes and so on.

The basic Octopress flow consists in managing locally the blog content and configuration, generate it in order to be packaged in a consistent web site and finally deploying to the remote server. Besides the blog archive is file-system managed and there is no need to use a database repository to store articles and media.

Setup overview

Currently my configuration is the following:

  • the full web-site is hosted by Webfaction
  • the main running application is powered by Django
  • in order to improve performances, this blog is statically mapped to a Nginx web server
  • blog management and configuration is done locally in my Mac Book Pro
  • the package site is deployed remotely using rsync via ssh

This tutorial is focused on the Octopress side, I will provide only a generic overview of the server configuration which may change depending on your actual configuration.

Server configuration

webfaction provides customers the possibility to create several “applications” pre-packaged as one-click installers with a basic (but working) configuration. Besides the server setup is done in such way that these applications are connected to the web-server to provide better performances. This is clearly explained in the webfaction user guide.

In my case together with my main Django instance (which powers my website, still under development) I have a static application dedicated to the blog. The Octopress results will be deployed completely to this area as a fully-functional and independed web-site.


Install GIT

If you’re coming from Mac or Linux, Git will be already installed in your computer. If you need to install it, you will find all the information and software at

Install Ruby

Octopress requires Ruby 1.9.2. Mac OSX 10.7 (Lion) comes with a slightly older version, 1.8.7, so you are required to make a local installation of Ruby. To install this new version you need to install RVM before and then you can install Ruby:

bash < <(curl -s
echo '[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # Load RVM function' >> ~/.bash_profile
source ~/.bash_profile
rvm install 1.9.2 && rvm use 1.9.2

Install Octopress

The best way to install octopress is to clone it from its GitHub repository. In the code below I clone octopress in a new directory, called octopress (but you can use any name), then entering on it and checking ruby is 1.9.2

git clone git:// octopress
cd octopress    # If you use RVM, You'll be asked if you trust the .rvmrc file (say yes).
ruby --version  # Should report Ruby 1.9.2

At this point I need to install octopress dependencies, by first installing bundler, a Ruby gem whose purpose is to facilitate code sharing by providing check and automatic installation of dependencies, so a sort of package manager and then running it:

gem install bundler
bundle install

the output will be a sequence of ruby packages (and their versions) that are effectively used by octopress. The packages are defined in the Gemfile file in the octopress root and the resulting installed dependencies will be saved in the Gemfile.lock file.

At the end we can install octopress’ default theme; this command will copy the default “classic” theme to the source file:

rake install

You can overwrite the existing them by later sending a new install command specifying a different theme:

rake install["theme-name"]

themes are defined in the .themes directory and are stored in directories having the same name of the theme. You are welcome to play with the classic theme by copying to a custom one and changing the configuration. Up to now there are not many new themes around, probably because the default one is good enough for bloggers that implemented it.

rake is another Ruby gem that works like a Make but completely implemented in Ruby. All Octopress commands will be provided using rake and the Rakefile file is the Makefile equivalent.

In order to update Octopress you can pull all changes from the remote github repo:

git pull octopress master     # Get the latest Octopress
bundle install                # Keep gems updated
rake update_source            # update the template's source
rake update_style             # update the template's style

The two update_source and update_style rake commands will update the source code and themes by preserving user changes. This is clearly a compromise between the need to pull the whole installation from the git repository but at the same time keeping the changes done by the user. Of course this approach will work only if the user followed the conventions clearly explained in the updating page of octopress official blog.


At this point we need to configure our octopress installation. The configuration will affect how octopress works and how the website will be generated. Note that many settings can be done at a later stage, they are all in all settings that impact on the way your blog is presented to the user but not in the inner structure. Other settings instead are relevant as they are strictly related to the way you will provide the data to build the blog and how this will be deployed to the web server.

The basic octopress configuration is done by working on four files:

_config.yml       # Main config (Jekyll's settings)
Rakefile          # Configs for deployment
config.rb         # Compass config         # Rack config

_config.yml is a YAML file coming from Jekyll’s heritage. This file is divided in three main sections:

  • main: where you define your blog url, page title and subtitle, author and other settings typical of html pages headers and footers.
  • jekyll: these are all settings coming from Jekyll and define the way the site is built; normally you will leave these settings unchanged with the only exception of the root key that must be set to your blog root; so if you decide to host your blog in a subdirectory of the main domain, like then you will need to set root: blog
  • third party: octopress comes with a set of predefined links to external services, like twitter stream or github or disqus. In this section you can setup basic access settings to these services.
  • config.rb and are respectively configuration files for compass and rack. We can leave them unchanged.


    The final step, before starting with blogging, is to configure octopress for deployment in the web server well your blog will be shown in the world wide web. Octopress official blog contains a nice documentation on the subject. Essentially the recommended ways are puhsing to a remote git server or directly rsync-ing on it.

    Pushing to a remote git, this can be a public or private GitHub repository or if you have ssh access to a server a new git repository dedicated to your blog, offers the advantage of allowing the blog to be managed from different authors from their own computers and then synchronize the changes to the common server. Git based deployment is based on the fact that the _deploy directory generated by rake is not managed by octopress git. So in your server (or on GitHub) you can define a git repository, whose master root directory is exactly the webserver blog root, and then push remote your local _deploy content to that server. At the end you will work with two branches: one is the source branch for blog management, the other is the master branch for the generated content.

    My preferred option is instead to work with rsync via ssh. I will explain this part in more detail.

    First step consists in providing the hosting server with the public key from your local server. So if you haven’t done yet you must create the keys:

    cd ~/.ssh
    ssh-keygen -f my_public_key -C 'My public keys for Octopress' -N '' -t rsa -q
    and then add the content inside the server’s ~/.ssh/authorized_keys file

    Then you must update your Rakefile by providing the ssh user name and host and the user document root:

    ssh_user = "" #this works on webfaction
    ssh_port       = "22"
    document_root = "~/webapps/blog"
    deploy_default = "rsync"
    Other interesting settings in the configuration file are:
    new_post_ext    = "html"  # default new post file extension when using the new_post task; default is markup
    new_page_ext    = "html"  # default new page file extension when using the new_page task; default is markup
    Then to generate and deploy just type:
    rake generate
    rake deploy
    this will update the public directory and will sync it remotely.

    Special care must be taken if you decide to publish on a subdirectory of your site. In such case you must specify this subdirectory inside the configuration files, as by default all assets (e.g. javascript files, css files, images) will be referenced from /. In such case the recommended procedure is to send a set_root_dir command and customize the configuration files:

    # this updates Rakefile, compass', _config.yml 
    rake set_root_dir[your/path]
    # _config.yml
    # Rakefile (if deploying with rsync)
    document_root = "~/"

    And finally… blogging!

    At this point you’re ready to blog. You can follow the Blogging Basics post in the Octopress official blog. This page explains how to create a new post, how to insert a standard page (not a blog post) and how to manage plugins. Another recommended reading is the Theming and customization guide that explains how to customize the page theme.