Recently, as an educational experience, and a place to share lessons learned, I decided to setup this Octopress blog hosted via GitHub.

Configuration

While I have a Linux server at home, I do most of my work from my Early 2008 MacBook. Since I am a conditions to and a fan of the GNU tools, I use Macports to manage them and other useful tools. You will need a compiler, git, ruby, bash shell, and a terminal. The following table summarizes my the various items I happen to have installed.

Setup and pitfalls

In addition to the Octopress documentation, there are many excellent guides to setting up Octopress hosted via GitHub, e.g.,

• Getting Started With Octopress
• Custom Domain With Octopress and Github Pages
• How I built my blog in one day
• Setup Octopress Under Mac OS X Lion

Studying these guides closely provided the outline for setting up my particularly instance.

Most of my difficulty came from order of operations. I looked at the instructions, and presumed I knew better, but order was important. So, I present the following items in the order that finally worked for me.

Git

Git is the fashionable and powerful revision control system. Get it and try it, even from your browser.

If you are CLI-shy, try GitHub for Mac. There are several other Mac GUI options, e.g. GitX or SourceTree. GitX is flexible and works well enough, particularly to visualize branching. SourceTree certainly looks glossy, however I have only toyed with it because I’m not a huge fan of Atlassian.

Getting the right Ruby

Octopress requires Ruby v1.9.3+. There are a number of ways to get to v1.9.3 on the Mac: MacPorts, Ruby Version Manager (RVM), rbenv.

Upgrading the Apple native v1.8.x is highly discouraged. Believe me. I know. I tried it, and it was painful undoing what I did.

Ruby Version Manager

RVM seemed the best choice for me. Being so tired after recovering my native Ruby, I thought I could simply

1

$ sudo gem install rvm

but after some issues, I uninstalled it from the native ruby environment and followed the processes suggested on the RVM quick install guide

1

curl -L https://get.rvm.io | bash -s stable

The first try, it failed with the error:

1

You requested building with 'gcc-4.2' but it is not in your path.

and I discovered I had a CC environment variable set that pointed elsewhere. So an unset CC and rm -rf ~/.rvm, then the install again was successful, however it warned me

1
2
3

RVM is not a function, selecting rubies with 'rvm use ...' will not work.
You need to change your terminal settings to allow shell login.
Please visit https://rvm.io/workflow/screen/ for example.

After checking the link, it all seemed unnecessarily complicated, but I did verify the warning:

1
2

$ type rvm | head -n1
 -bash: type: rvm: not found.

The was easily solved by issuing

1

[[ -r "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"

Trying the check again,

1
2

$ type rvm | head -n1
rvm is a function

things look good. Simply adding it to your .bash_profile ensures it will be loaded each time you do login.

My rvm install had already installed Ruby 1.9.3 selected selected it as the default, however you can verify and ensure this by

1
2
3
4
5

$ ruby --version
ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin11.4.0]
$ rvm use 1.9.3
Using /Users/username/.rvm/gems/ruby-1.9.3-p194
Running /Users/username/.rvm/hooks/after_use

GitHub

First, as mentioned in all guides, sign up for a free GitHub account, and then create a repository for as indicated for User Pages. The repository naming scheme is username/username.github.com. There is no need to add anything to the repository, GitHub will recommend adding a README.

I have yet to setup a custom domain, but a portion of the process is described here.

Octopress

Clone the Octopress repo with

1
2

$ git clone git://github.com/imathis/octopress.git octopress.git
$ cd octopress.git  # trust the .rvmrc when asked, i.e. yes

Next, install the bundler Ruby gem

1
2

$ gem install bundler
$ bundler install

which will installed a number of items. Once complete, we can setup the default classic theme with

1

$ rake install

This repo will hold both your content and the Octopress code. To update Octopress, see the Updating Octopress guide.

Connecting Octopress to GitHub

The Deploying Octopress to GitHub Pages instructions clearly outline how to accomplish this. In summary, from the top of the octopress.git repo

1

$ rake setup_github_pages

answering the questions as required, i.e., repo url is git@github.com:username/username.github.com.git. Then,

1
2

$ rake generate # generate the content from markdown
$ rake deploy   # copy the content to be deployed

Commit and push your changes

1
2
3

$ git add .
$ git commit -am 'initial import' # a very poor commit message :(
$ git push origin source

The last line pushes source to the master branch of your GitHub repo.

Waiting …

Lastly comes the waiting. GitHub recommends about 10 minutes. My experience is that it take 1-5 min to receive the e-mail that the page(s) have been created, and 10-15 min for the site to appear initially. Afterwards, content appears much more quickly, at the 1-5 min range.

Blogging

Finally, you are ready to generate content. The Octopress Blogging Basics page enumerate the helper functions and process to get your content to your GitHub repo.

So far, I have found the rake preview version useful. In one Terminal.app tab, I invoke

1

$ rake preview  # start local web server

while in another, invoke

1

$ rake watch    # auto-regen on change

while editing markdown in a third. I verify my blog changes via browser on localhost:port. The port will be listed on one of the first few INFO lines after preview startup

1
2
3
4

$ rake preview
[2012-09-08 21:53:52] INFO  WEBrick 1.3.1
[2012-09-08 21:53:52] INFO  ruby 1.9.3 (2012-04-20) [x86_64-darwin11.4.0]
[2012-09-08 21:53:52] INFO  WEBrick::HTTPServer#start: pid=77869 port=4000

and voilà, we see port=4000, so http://localhost:4000 should do it.

Conclusion

This was a straightforward process, once I thought more carefully about order of operations. I also, unfortunately, messed up my repo to start due to a typo, which caused my source to push to a source branch in GitHub, rather than master. This caused me no end of heartache as I waited for my pages to be created, but of course they weren’t because there was no master branch. After a few repo deletes, and typing correctly, it finally worked. Personally, I hope you have less trouble.