Following on from my opening post, one of the main hurdles preventing me from blogging was the setup of a blogging platform and the management of the hosting. Thankfully, Octopress and Heroku have provided a simple, effective and free way for me to publish my thoughts to the web. In this post I will explain how I got started with Octopress on Heroku.
Setting up your development environment
First off you are going to require Ruby 1.9.2. At this point your natural temptation may be to download and compile the source code directly. This will work for the most part, but any seasoned Ruby developer will advice you against this path.
When doing any serious Ruby development you most likely will be working on numerous projects that use a variety of different frameworks, each with their own specific Ruby and Gem version requirements. Managing multiple versions of Ruby and Gems manually is a rather daunting task.
Thankfully this problem has been solved already by RVM and Rbenv. Both RVM and Rbenv provide an isolated Ruby environment, encapsulating Ruby and Gems to specific versions. This allows each Ruby project on your system to run a targeted version of Ruby and Gems per project without concerning yourself with conflicts. I am not going to advocate either of these tools over each other, but I will be using RVM in this article. There are instructions on using Rbenv on the Octopress setup guide.
To install RVM, in Terminal run;
Once RVM has finished installing, you should add it to your shell as a command. Run the following command to update your
Finally you should update your Terminal sessions
.bash_profile to load the new profile settings.
Now you’re ready to install Ruby 1.9.2.
This command installs Ruby 1.9.2 as a Gem into your
~/.rvm/gems/ folder. Now within each Ruby application, you can create a
.rvmrc file that defines the Gem sets required by the project. For example, Octopress instructs RVM to use Ruby 1.9.2 by including the following in its
The best way of getting Octopress is directly from Github. This will require your system to have Git installed. By cloning the Octopress project, obtaining updates in the future will be as easy as
git pull origin master. However you may prefer to fork the project on Github and then clone from your own repository. In this case, I am happy with the standard build of Octopress, so will clone it directly.
This will place an instance of Octopress into my
~/Projects/octopress folder. You may wish to place it elsewhere, it does not matter where at this time.
Now change directory into the newly created local Git repository and check the Ruby version.
1 2 3
You should see the Ruby version you previously installed, the exact version number and details will differ depending on your platform and other environment variables. The Ruby environment is controlled by the RVM
~/Projects/octopress/.rvmrc file I mentioned earlier.
Next we install Bundler into this project.
Taken from its own website, Bundler provides the following functionality;
Bundler manages an application’s dependencies through its entire life across many machines systematically and repeatably.
bundler install command is invoked, it reads the required list of Gems from the projects
Gemfile. If you were inspect the
Gemfile for Octopress, you can see the project dependencies.
Finally, to install the default Octopress theme run the following command.
This will setup your local instance of Octopress with the standard theme. In my instance this command failed with the following message.
1 2 3 4 5
In some circumstances this will happen if you have a newer version of rake installed for whatever reason. Usually the Gemfile and Bundler will resolve these issues, but because both
rake 0.9.2 and
rake 0.9.2.2 are matched in the Gemfile this conflict is not resolved. However in this case, following prescribed advice provides the expected outcome.
Octopress is now installed locally and is ready for you to begin blogging. You can use a plethora of hosting services with Octopress. As Octopress compiles a static version of your site, it would be perfectly possible just to publish the
public/ folder to any standard HTTP server such as Apache or Nginx.
Because the contents of
public/ folder is compiled by Octopress, by default the Git clone of the project will contain a
.gitignore file with an entry to ignore the
public folder. We need to remove this entry to ensure the
public/ folders contents are included in our git repository and pushed upstream.
To remove the entry, edit the
.gitignore file remove the offending line.
Deployment to Heroku
Deployment to Heroku requires an account on Heroku. If you do not have an existing Heroku account, sign up for one now.
I am discovering that as with most things in Ruby, there is usually a Ruby Gem tailored to working with whatever Ruby service you require. Heroku is no different.
To install the Heroku Gem.
Now we have the Heroku Gem available, we can create our Heroku app. This does require an existing Heroku account, so if you still have not signed up with the Heroku service, now really is the time!
Note: To proceed you will need to have a SSH public key. Github have a great guide if you require help.
First we need to tell Heroku about our account. Using the
heroku login command, we can authenticate ourselves with the Heroku service.
1 2 3 4 5 6
If successful, the
heroku login command will upload our SSH public key automatically to the Heroku service. The reason for this is that you publish to Heroku using Git, and just like any other standard Git remote repository, connection is made over SSH.
Next we create an application on Heroku that will host this blog.
1 2 3
Well we have an app, but I don’t like the name. Heroku will generate a random name for applications if no name is supplied. After doing some research, I discovered you can provide a name, thus
heroku create defreyssinet would result in an application located at
defreyssinet.heroku.com. However it is not a disaster as we can rename any Heroku application after creating it.
To rename our app, within the
~/Projects/octopress folder type.
1 2 3
This has updated the hostname on Heroku and rather neatly tidied up our local Git repository remote entries. It is possible to do this manually by logging on to the Heroku site and renaming the app there, then updating the local git repository remote entries.
At this point we have a Heroku app linked to our local Octopress Git repository. We can verify that our app has indeed been created by logging onto Heroku and selecting the My Apps menu item.
Now we have a local instance of Octopress and a host ready to accept our new blog. What is lacking is the content.
Creating a new post
As I mentioned earlier, Octopress is a static site generator rather than a fully fledged web application like Wordpress or Habari. This implies that there is a specific workflow in relation to publishing using Octopress. The typical publication flow for an article is as follows;
- Create an article -
- Write some content
- Review -
- If more work required, return to step 2.
- Publish -
git push heroku <your app>
Before we get ahead of ourselves, it is time to setup the configuration of the blog using the
_config.yaml file found in the root of the project. All of the configuration settings are described in detail on the Configuring Octopress page. Before creating any content it is probably worth familiarizing and editing this file to your specific needs.
Creating an article simply uses the
rake new_post["title"] task. This creates a new file in the
~/Projects/octopress/source/_posts/ folder with a name composed of the date and the title. The extension will be
.markdown as we will be writing in Markdown format.
Note: We will only be working in the
source/ folder and we must not touch the
public/ folder. The
rake generate task compiles the contents of
source/ and places it into
So lets go ahead and create an article. (I’m prefixing with
bundle exec here to avoid the version complaint seen earlier.)
Rake helpfully creates a new Markdown file called
2012-01-14-get-blogging-with-octopress-on-heroku in the
source/_posts folder. Opening up the new file will reveal the following.
1 2 3 4 5 6 7
The header of this file contains some yaml front matter. There are additional options available to control the publication state and author.
Personally I think the time of publication is less important, but this is easily fixed by removing the time index from the (Edit: don’t do this as it will mess up article ordering!). I have also turned off comments
comments: false for this post.
It is now possible to add some content to this page in Markdown format. We don’t need a title as the filename will become the title, so don’t start with a
# my title block.
1 2 3 4 5 6 7 8 9 10 11
With some content in place, we can generate our first blog post using the
rake generate task.
1 2 3 4 5 6
At this point Octopress has compiled the static version of our site. It is possible to load the
public/index.html folder into any browser to view our new content.
With POW installed, the following commands will create a local web server hosting our Octopress site.
Now it is simply a case of navigating to http://octopress.dev to see the site we just compiled. This is a really quick and simple way of reviewing changes.
Users on other platforms that wish to test in a server environment locally just need to host their local
Previewing the site should present a page that looks similar to the screenshot below.
Looking good. At this point we can carry on editing and reviewing until we’re happy the post is ready. Remember that each time a change is made, an additional
rake generate task needs to be invoked before any changes will be available in the
Publishing to Heroku
The first post is completed, reviewed and ready for publication. This is where Heroku makes our lives very easy. First we need to check all of our changes into the local Git repository.
With the local repository up to date, we can push the repository to Heroku. Once the repository is pushed to Heroku it will be available immediately, so be sure you’re really ready to publish before pushing upstream.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Once the repository is pushed upstream, it will be available from the address configured in the Heroku app. In this case we named the app
defreyssinet so the site will be available from http://defreyssinet.heroku.com.
In this blog post we have covered how to create a blog using the Octopress static site generator and host it on Heroku. In particular we have covered provisioning a local development environment with POW, obtaining Ruby using RVM and cloning the Octopress project from Github. We created a new Heroku application instance using the Heroku cli interface. Then we discovered how the publishing cycle works with Octopress, revolving around the
rake generate task. Finally we pushed the Octopress blog to Heroku for production.
This article only scratches the surface of what Octopress offers, for more information I encourage everyone to read the official documentation.
Octopress will certainly not be to everyones tastes, but I hope this article has provided those with the slightest curiosity about Octopress some impetus to try it from themselves.