I’ve been a happy WordPress user since 2003, but I decided to go with Octopress for this blog, and I’m planning on porting my two WordPress music sites (Monfresh and They Make Music) to Octopress at some point this year.

Octopress is an open-source “blogging framework for hackers” that runs on Jekyll. It lets you write posts using your favorite text editor, and generates a static site. Since there are no databases, fancy web UIs, or admin logins to worry about, Octopress-powered sites are super fast and secure out of the box. Octopress also comes with a great-looking mobile-friendly responsive theme, and many more goodies.

The official Octopress Setup documentation is quite robust, but it is not geared towards beginners (it is a “framework for hackers” after all), so there are a few things that aren’t covered. Having configured this blog recently, I thought I’d put together a step-by-step tutorial that covers the initial setup, various customizations, and deployment to Amazon S3.

Step 1: Install Git, RVM and Ruby 1.9.3

If you haven’t already, the easiest way to install those tools is to follow my tutorial: How to Install Xcode, Homebrew, Git, RVM, & Ruby 1.9.3 on Snow Leopard & Lion.

Step 2: Install Octopress

1
2

$ cd path/to/directory_where_you_want_to_install_octopress
$ git clone git://github.com/imathis/octopress.git octopress

Step 3: Create a gemset for Octopress

1

$ rvm --create use 1.9.3@octopress

Octopress comes with a default .rvmrc file (in the root octopress directory) that is configured to use Ruby 1.9.2. Since we’re using Ruby 1.9.3, we need to edit this file to use the “octopress” gemset we just created. Open the .rvmrc file in your favorite text editor and replace its contents with:

1

rvm use 1.9.3@octopress

To learn what this does and why it’s useful, read my post on RVM gemsets and .rvmrc.

Step 4: Setup Octopress

1

$ cd octopress 

When asked if you trust the .rvmrc file, type y for “yes”.

1

$ gem install bundler

Octopress is dependent on several Ruby gems to run properly. Bundler allows you to manage those dependencies easily. I encourage you to click through to the Bundler site to understand how it works.

Once you have Bundler installed, you can install all the required gems (as specified in the Gemfile) by running the following command:

1

$ bundle     # This is the shortcut for "bundle install"

Install the default Octopress theme:

1

$ rake install

Step 5: Install POW

POW is a great alternative to WEBrick for testing your site locally. Installing it is as easy as:

1

$ curl get.pow.cx | sh

To make Octopress use POW:

1
2

$ cd ~/.pow
$ ln -s /path/to/octopress octopress 

Let’s create our first blog post and test the POW server. First, we need to go back to the octopress directory.

1

$ cd /path/to/octopress

If octopress was the last directory you were in before going to .pow, then you should be able to use this shortcut, which will take you back to the directory you were in before you last changed directories:

1

$ cd -

To create a new post:

1

$ rake new_post["title"]

As explained in the Blogging Basics section of the official Octopress documentation, this will create a file in source/_posts with the following format: YYYY-MM-DD-post-title.markdown. Note that your title in the rake command cannot include commas, otherwise the generated file will get truncated at the comma. I’m not sure if this will be fixed in 2.1, but you can always add commas later when editing the Markdown file in your favorite text editor. I’ve been using Mou to edit my Markdown files and I love it.

To see if this worked, run:

1

$ rake watch

Then once you see this in Terminal:

1

>>> Compass is watching for changes. Press Ctrl-C to Stop.

Go to http://octopress.dev in your favorite browser and you should see your shiny new Octopress blog!

Step 6: Configure your blog

Now that you’re up and running, you’ll want to make a few configuration changes, and possibly some customizations. The first file you’ll want to edit is _config.yml (in the Octopress root directory). Most of the settings you’ll be changing are self-explanatory and well-documented on the official Octopress Blog Configuration page.

One setting that is currently broken in version 2.0 is description. If you visit your site’s home page, the meta description tag will contain the first few words of the most recent post, instead of what you entered in _config.yml. This is fixed in version 2.1 of Octopress (which should be released soon). If you do enter a description, make sure it doesn’t include a colon followed by a space, since that is part of the YAML syntax and will result in a cannot parse YAML error.

Besides url, title, subtitle, and author, here are the other settings I changed:

simple_search

1

simple_search: http://www.duckduckgo.com/

I like DuckDuckGo because of their ”don’t track” and ”don’t bubble” policies. In order to finalize the switch from Google to DuckDuckGo, you also have to replace the html between {% if site.simple_search %} and {% endif %} in source/_includes/navigation.html with the following code, as described in the DuckDuckGo Help article on Octopress:

1
2
3
4
5
6

<form action="{{ site.simple_search }}" method="get">
  <fieldset role="search">
      <input type="hidden" name="sites" value="{{ site.url | shorthand_url }}" />
      <input class="search" type="text" name="q" results="0" placeholder="Search&hellip;"/>
  </fieldset>
</form>

RSS

1

subscribe_rss: http://feeds.feedburner.com/MoncefBelyamani

I use Google’s Feedburner service to manage my feeds and to view their stats.

permalink, category_dir, and pagination_dir

By default, Octopress sets up your blog under a blog directory, so that your post URLs (permalinks), category URLs, pagination URLs, and archives URL all begin with:

1

http://yoursite.com/blog/

My personal preference is to keep my URLs nice and short, so I made some changes to the permalink, category_dir, and pagination_dir settings to move everything to the root directory.

1

permalink: /:title

1

category_dir: categories

1

pagination_dir:  #Leave it empty by deleting "blog"

Move archives to the root

To make your archives URL point to http://yoursite.com/archives instead of http://yoursite.com/blog/archives, move the archives folder in source/blog/archives to source/archives and edit line 17 in source/index.html to:

1

<a href="/archives">Blog Archives</a>

Step 7: Customize your blog

Navigation menu

To edit your navigation menu items, make your changes in source/_includes/custom/navigation.html.

Background image

To change your site’s background image, edit line 75 in sass/base/_theme.css. I’m using the Inflicted pattern from the wonderful Subtle Patterns site.

Colors

To change colors, edit sass/custom/_colors.scss.

Sidebar

To add a custom aside in your sidebar, such as My Other Sites on this site, add a new HTML file in source/_includes/custom/asides with code in this format:

1
2
3
4
5
6
7

<section>
  <h1>Custome Aside Title</h1>
  <ul>
      <li><a href="http://somesite.com">Cool Site</a></li>
      <li><a href="http://anothersite.io">Useful app</a></li>
  </ul>
</section>

Step 8: Deploy your blog

The Octopress documentation covers deployment on Github Pages, Heroku, and a web host with Rsync. I’ll be going over a fourth option, which is just as fast and convenient: Amazon S3.

If you don’t already have an S3 account, sign up, then click on My Account / Console in the top right, then click on Security Credentials. Keep that web page open, because you will need your Access Key ID and Secret Access Key, which you can find in the Access Keys tab of the Access Credentials section.

Next, install the ponyhost gem:

1

$ gem install ponyhost

ponyHost is an awesome gem by Johannes Wagener that lets you “easily create and deploy Amazon S3 powered websites”.

Then, create the S3 bucket with a website configuration:

1

 $ ponyhost create your-site

your-site will be the name of your S3 bucket, and has to correspond to the domain name you’ve chosen for your site, such as www.yoursite.com or blog.yoursite.com. You’ll then need to create a DNS CNAME record for your bucket name to point to s3-website-us-east-1.amazonaws.com. Amazon S3’s static site hosting service does not support naked domains, so you cannot create a bucket called yoursite.com (without www or some other subdomain). However, you can easily redirect any requests for yoursite.com to www.yoursite.com, as detailed below.

I use Hover¹ for my domain names, and this is how I pointed the CNAME record for www.moncefbelyamani.com to s3-website-us-east-1.amazonaws.com :

1. Log in to your Hover account and go to the DNS section.

2. Click on +Add New.

3. Select your Octopress domain name from the Domain dropdown

4. Select CNAME from the Record Type dropdown
5. Type your bucket name (for me, it was www.moncefbelyamani.com) in the Hostname field and s3-website-us-east-1.amazonaws.com in the Target Host field, then click Save.

If you want your visitors to be able to reach your blog by going to yoursite.com (without the “www”), then you need to redirect any URL that starts with yoursite.com to the corresponding URL with the www prefix. The awesome free service wwwizer makes this very easy. Here are the steps, using Hover once again:

1. Go back to the Manage Your DNS section
2. Click on +Add New.
3. Select your Octopress domain name from the Domain dropdown
4. Select A from the Record Type dropdown
5. Type yoursite.com in the Hostname field and 174.129.25.170 in the Target Host field, then click Save.

After you create your CNAME and A records, you should end up with 2 new entries that look like this:

That’s it for the ponyhost setup. To publish your posts to your site and make them available for the world to read, you need to run three more commands:

1

$ rake generate

This generates all your posts and pages into the public directory. This is the directory you want to push to your S3 bucket, so remember to always cd to your public directory before pushing:

1

$ cd public

Now we’re ready to push with ponyhost:

1

$ ponyhost push www.yoursite.com

Et voilà!

I hope this post was helpful and informative. Let me know if you find any errors, run into any issues, or have any questions.