Octopress is a static site generator based on Jekyll. You write your posts in Markdown and Octopress generates the HTML for your site. This simplifies your hosting requirements. No application server or database required.
Octopress has great documentation. The docs got me 95% of the way there, but left some unanswered questions. This guide answers the questions I had on migrating and hosting Octopress. I refer to the official docs where it makes sense, to avoid repetition.
There are lots of options for hosting your blog: GitHub Pages, Amazon S3, Heroku (or other PaaS), or a virtual private server. I evaluated all the hosting options and decided on Amazon S3. GitHub Pages doesn’t support redirects at the moment. I originally overlooked S3, thinking they didn’t support redirects either, but in fact they do! Heroku is a good (and free) option, but I didn’t want to run a Rack or WSGI process to handle redirects. My goal was simplicity, so that ruled out managing a VPS.
Git & Ruby
I’m using Homebrew for package management.
Octopress requires Ruby. I followed the Octopress guide for installing Ruby with RVM. I’m not a Rubyist, and haven’t really compared rbenv to rvm. They both seem perfectly good for this exercise.
I’m hosting my fork of Octopress on Bitbucket. GitHub offers 5 private repositories and unlimited collaborators with their micro plan. I prefer to save those slots for projects with collaborators. Bitbucket’s model is reversed: 5 collaborators and unlimited private repositories.
There are a couple of advantages to keeping your fork private. Many of the plugins, such as Google Analytics, require setting an API key in the Octopress
_config.yml. Octopress also supports a
published flag, which allows you to keep work-in-progress posts that don’t show up when the site is generated. Neither of these belong in a public repository.
You can fork the Octopress repository hosted on GitHub directly to Bitbucket, using the import repository feature on bitbucket.org. Then clone your fork.
At this point Bitbucket is the
1 2 3
Now is a good time to add a remote to the official Octopress repository, so you can get updates.
1 2 3 4 5 6
My setup looks like this:
Next up is configuring Octopress. I just followed the configuration steps and had an empty blog running in no time. Now I needed to migrate my WordPress blogs to Octopress.
Two utilites make the WordPress migration easy: exitwp and wp2oct-links. exitwp converts an entire WordPress site to Markdown. wp2oct-links generates the rewrite rules for permanently redirecting old URLs to new ones. Both are python utilites. I highly recommend The Hitchhiker’s Guide to Python for getting setup with Python.
WordPress has an exporter in the admin panel. Use that to export any posts and pages you want to migrate. The exporter generates an XML file which we’ll feed to exitwp. Then copy the result of exitwp to your Octopress directory.
1 2 3 4 5 6 7
I should note that preserving your URL scheme in Octopress removes the need for redirects. The WordPress URL scheme is
/year/month/day/post-title/. The default Octopress URL scheme is
/blog/year/month/day/post-title/. Simply configuring the Octopress URL scheme to match WordPress will save you the trouble of dealing with redirects.
Otherwise use wp2oct-links to generate the rewrite rules, and set those aside for later. We’ll use those rules when setting up Amazon S3.
1 2 3 4 5 6
At this point all your posts and pages have been transfered to Octopress. Maybe you’ve even written a new post. Now it’s time to publish the site. Amazon S3 offers static website hosting and redirects. The Amazon S3 Developer Guide has a step-by-step tutorial on hosting websites on Amazon S3.
Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be unique across all of Amazon S3.
You can map a
CNAME on your domain to an S3 bucket. My bucket name is
www.julianbonilla.com. The bucket is reachable on S3 at
The AWS console has a tool for uploading your site to S3. There are also plenty of graphical and command line clients. I settled on S3tools for transfering my files.
Now generate your site and upload to S3.
1 2 3
Each S3 object has an access control list. Objects are private by default, the
--acl-public flag sets your site to public (readable by anyone). Amazon offers two storage tiers: standard and reduduced redundancy storage (RRS). RRS is cheaper than standard storage ($0.093/GB/month vs $0.125/GB/month). But RRS does not replicate objects as many times as standard storage. I use the
--reduced-redundancy flag since I can generate the site from source.
The Amazon Developer Guide has a detailed explanation on configuring a web page redirect. For each of the rewrite rules generated with wp2oct-links, I created a zero-byte object with a matching key in S3. You can script this or create them directly in AWS console. Then you set the
x-amz-website-redirect-location metadata for each object to point to the new object in your bucket. Amazon S3 will respond with a 301 redirect.
1 2 3 4 5 6
The last step is pointing DNS to your S3 bucket. Make sure everything is working on
s3-website-us-east-1.amazonaws.com. Then create a
CNAME that matches your bucket name. I use Hover to manage my DNS.
Here are some useful tips I collected.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21