« Back to home

Deploying Octopress to GitHub or Heroku

I spent numerous hours messing with command line and figuring out the deployment process for Octopress. I recently migrated all my blog posts from Menace Studio which was using the Orchard Project CMS. I really liked the CMS which is built around ASP.NET MVC and SQL Compact back end. My main issue with Orchard as well as other ones such as
WordPress is that they're all trying to be an all in one solution (blogs, ecommerce, personal, etc.) which makes it really bulky.

The main reasons why I switched to Octopress is the fact that the site is entirely static generated content. The posts and pages are basically generated HTML from Markdown which makes the content easier to manage and back up. I use Dropbox to store the source files which includes the generated HTML to be deployed.

Deploying to either Heroku or GitHub pages using GitHub is pretty straight forward but using a custom domain can be a little challenging. This link for instance helped me get to setting up a custom domain for GitHub fairly quickly. I had a few stumbling blocks along the way and I wanted to write this post to bring all the information needed to deploying Octopress using a custom domain as quickly as possible.

Deployment instructions to GitHub pages and Heroku can be found here:

One thing that I would warn people about is to never setup/configure your local Git repository to deploy to both Heroku and GitHub. Maintenance will become a pain since you have to make sure that you're consistently pushing changes to both remote locations. Otherwise, things will get out of sync and the only way to fix is to delete the .git directory. If you follow the instructions above correctly, things shoud go smoothly.

Custom domain using GitHub pages

Go to your domain name registrar (mine is GoDaddy) and add the settings below for the DNS.

  • Add A (Host) and point to
  • Add a CNAME (Alias) for www and point to <username>.github.io.

To intiate a Git repository and setup the deployment to GitHub pages (as default).

rake setup_github_pages
rake generate
rake deploy
git add .
git commit -m "deploying"
git push origin master

Go to your <Octopress project>/source/ and add a CNAME file and put your custom domain name without the http or www (ie. menacestudio.com). When I made the changes above, it took more than 5 hours for the changes to take in effect so you have to be really patient (and yes, it does sucks when you have to wait for that long).

Custom domain using Heroku

The process for deploying to Heroku is pretty similar but the DNS resolution seems to take in effect very quick. Mine took literally a minute. I took the GitHub pages route in the beginning but decided to switch to Heroku since the setup for custom domain is easier. Pushing files to Heroku server seems to take 10 times longer since it tries to resolve dependencies.

Go to your domain name registrar and add the settings below for the DNS.
- Add A (Host) and create 3 entries (@) that points to, and - On the command line, type heroku domains:add <your_domain_name>.com. This lets Heroku know which domain belongs to your application.

To create a new Heroku app and set as default remote repository. As a side note, for the heroku command to work,
you will have to install Heroku Toolbelt which consists of tools that are helpful when deploying to Heroku server.

heroku create
git config branch.master.remote heroku

Pushing to Heroku is accomplished by performing the steps below.

rake generate
git add .
git commit -m "deploying"
git push heroku master

In addition to the Octopress documentation regarding Heroku custom domains, here's the documentation by Heroku that goes into details regarding custom domains. A useful command to check the status of your DNS changes is nslookup <your_domain_name> which tells you which IP(s) your domain is pointing to.


comments powered by Disqus