Installing Toto on OS X Mountain Lion

A while back I wrote a guide on getting started with Toto, the blogging engine I use to run this site. While Toto is very easy to use, the initial installation can be quite tricky. The old instructions are outdated now with new versions of Mac OS X, so here is a new guide on getting the blog set up and running on Mountain Lion.

Now, if you’re not a developer, the number of steps below might put you off. Toto is developer friendly, especially those who work with Ruby, so from their standpoint the guide isn’t even necessary. For everyone else though, there is a short learning curve, which may be seem fairly steep. The steps below have less to do with installing Toto than setting up a Ruby-focused development environment on a Mac. This means there’s a few of them, but even so, each individual step is very simple, so even if you’ve never used a command line before, this won’t be very hard to do on a fresh install of OS X Mountain Lion.

1. Install Xcode and Xcode command line tools

To run Toto locally we’ll need some components that are installed with Apple’s Xcode development toolkit. Xcode is not installed by default on a new copy of OS X so we’ll need to download and install it. Use the App Store to search for and install Xcode. Once Xcode is installed, you’ll need to install the command line package. To do this:

  1. Run Xcode, and, as soon as the app opens, open the Preferences window by clicking on “Xcode” menu item, and then choosing “Preferences”.

  2. Go to the “Downloads” tab and then click on the “Install” button next to “Command Line Tools”

2. Install Homebrew

Homebrew is a package manager for OS X. If you’re not familiar with the package manager concept then what it is is basically a little command line app that will let you easily install development focused tools and frameworks. For our purposes we’ll be using it to install Git, but it will most certainly be valuable for you in the future for other things as well.

To install Homebrew, open Terminal.app (search for it in Spotlight if you’ve never used it before), paste the following line in, hit Enter, and wait for it to install.

ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go)

Note: the above should work at the time of writing this. You can always check the official Homebrew website to ensure the installation details are still correct. Also: if at any time during the process you’re asked for your OS X password, make sure to type it in.

3. Install Git

Now that we have Homebrew installed, we can easily install Git. Git is a distributed version control system, which is basically the engine that will keep track of any file changes in Toto, such as new articles, article edits and template changes, and will let you publish those changes to the server.

To install Git using Homebrew, open a Terminal.app window if you’ve closed the previous one, type the following command and hit Enter:

brew install git

4. Install RVM

OS X Mountain Lion comes with an installation of Ruby, the programming language that Toto runs on. The version of the interpreter is fairly old however, so we’ll need to update it. To do this I recommend installing something called Ruby Version Manager (RVM). RVM is an invaluable tool for Ruby development which lets you easily install and switch between multiple versions of Ruby on your system.

Apple’s new command line tools don’t come with GCC (Gnu Compiler Collection), which RVM needs to run, so we’ll need to grab this first. This can be done with Homebrew, but for this specific package we’ll need to enable the homebrew-dupes repository. To do this, type:

brew tap homebrew/dupes

Then to install GCC:

brew install apple-gcc42

If I remember correctly RVM also needs the “libksba” library, which you can grab easily with Homebrew:

brew install libksba

Then to install RVM execute the following command:

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

Note: RVM may start with an installation note, so read through it to continue the process (you may have to scroll down with the down key). Also, as with the Homebrew command above, you can always check the RVM installation page to ensure the details are up to date. After installing RVM you’ll need to close the current terminal window and open a new one (or paste the line of code the installation instructions give you at the end).

5. Install Ruby

Once you have RVM, close the old Terminal window and open a new one to initialize RVM. Toto runs great on 1.9.3, so to install it just type:

rvm install 1.9.3

Then, when the installation finishes, to switch to 1.9.3, as well as specifying it as the default interpreter, type:

rvm --default use 1.9.3

6. Install Ruby gems: Toto, Thin, etc.

Ruby gems are Ruby programs that are compiled into packages that other Ruby apps on your machine can make use of. The Toto blog engine is a Ruby gem, and so is the Ruby server we can use to run it called Thin. To get Toto simply type:

gem install toto

To get the Thin Ruby web server, type:

gem install thin

You don’t have to keep typing a new command every time though, if you have a multiple set of gems you want to install, just list them all separated by a single space, like: “gem install toto thin”

7. Get the default Toto template

Now we have all the prerequisites to run a Toto blog on the local computer. To start off we need the default Toto template, which is where new blog post files will go as well. Open a new Terminal window and type:

cd

This takes you to your home directory. If you’re not familiar with command line commands, you can make a new folder by typing:

mkdir blogs

This will create a folder called “blogs” in your home folder, the same home folder you see in the sidebar of your Finder. To get in the folder type:

cd blogs

You don’t have to do the above, but it makes sense to keep the blogs we’ll create organized in some folder other than just your home folder where all the main stuff sits.

Download the default template using Git by typing the following line, substituting “myblog” to whatever title you want to use for the folder in which your blog will sit:

git clone git://github.com/cloudhead/dorothy.git myblog

Then once again to navigate to this folder using the Terminal type:

cd myblog

8. Running Toto

After navigating to our blog folder, to run Toto using the Thin Web server type:

thin start

If everything has installed correctly, the server should now be running and you’ll see a message like this:

>> Using rack adapter
>> Thin web server (v1.4.1 codename Chromeo)
>> Maximum connections set to 1024
>> Listening on 0.0.0.0:3000, CTRL+C to stop

To see the blog in action, open your Web browser and go to “localhost:3000” as the address (i.e. local machine, port 3000, which Thin uses by default). You should now see the default blog setup running live on your computer.

9. Hosting the blog on Heroku

I recommend a cloud hosting service called Heroku to publish the blog. The footprint of the blog is so small you can run it without problems on the free starter plan, and the other essential add-ons, like linking a custom domain name, are free as well at the time of writing this.

To start using Heroku you need to go to heroku.com and get an account.

You then need to grab the Heroku gem, which provides additional functionality for interfacing with Heroku servers. The alternative to the gem is getting something called the Heroku toolbelt, which is a combination of the gem’s command line functionality, Git, and a tool called Foreman. This option is good for developers of other languages other than Ruby, but since I already have Ruby and Git, and don’t want Foreman, I just go for the gem:

gem install heroku

Now, there’s a good Ruby deployment guide over at Heroku you can read, which covers the next steps. It covers everything right after install, so I recommend you read through that. Most of the sections you can ignore, the ones you want to read are: “Local workstation setup”, “Store your app in Git”, and “Deploy to Heroku”. I’ll summarize the key steps now.

First, you’ll want to log in to Heroku:

heroku login

This will put up a message asking you for your account details, so enter your username and password.

The next thing it will do is ask you to upload something called an “SSH public key”. This is a very long string of characters that is used to identify your computer every time you want to deploy your blog changes to the Heroku server. It’s like a key instead of a password. If you don’t have a key available, you’ll be asked to generate one. Make sure to type “y” and hit Enter to confirm.

Also, when you communicate with the Heroku server your machine may ask you to add its IP address to a list of trusted servers, so make sure to confirm in the same way when asked.

Now, ensuring you’re still in your blog directory, as specified in the last step, you can deploy your app by typing the following, substituting “myblog” to a single word name you want to use to identify your Blog at Heroku (it will also act as a Heroku subdomain, e.g. myblog.heroku.com):

heroku create myblog --stack bamboo

This will set up a new app at Heroku ready for you to deploy. The --stack bamboo bit sets up the blog on an older stack which has a cache engine called Varnish that Toto uses to cache pages. Newer Heroku stacks don’t have it, so it’s important to pick the right stack. The last step is to push the changes to the server. In our case it means pushing everything as it’s all new. This is where Git comes in:

git push heroku master

Let that run for a bit and if all goes well you should momentarily have a new Toto blog running on Heroku. Once the deployment process stops and gives you back the command prompt, you can type the following to open your new blog in your browser (or simply navigate to “myblog.heroku.com”:

heroku open

Running into problems?

If you run into any problems during the install process, make sure to read the error message carefully. Sometimes it might not be an error at all, just a startup message, as you might encounter in the case of RVM, in this case read it carefully to ensure you have everything you need before proceeding with the installation (you may even have to scroll down using the down arrow key). The error messages often give you enough info to figure out what’s missing.

If you run into a dead end, or see a mistake in the guide, you can drop me an email to let me know what’s wrong. I cannot promise to get back to everyone, but I do want to make sure the guide is correct so I will do my best to help out.


Share on Twitter Facebook Email

“For even falsehood, uttered by the tongue of man, seemed like truth and light before this hopelessly-deaf and unresponsive silence.”

My new book: a translation of selected short stories by Leonid Andreyev, the father of Russian Expressionism from the Silver Age of Russian literature. A piercing, pitiless glance into the heart of the human condition.

☛ Read online

Further Reading

Proust wrote that the true voyage of discovery is not to visit strange lands, but to possess other eyes, to behold a hundred universes that each of them beholds. Thus, in the words of Ruskin, what good books give us is not mere knowledge, but sight.

Sign up to my email newsletter to receive regular recommendations of exceptional books on a wide range of topics including design, art, history and philosophy. A summary of latest site updates will also be included. Sign up below: