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:
-
Run Xcode, and, as soon as the app opens, open the Preferences window by clicking on “Xcode” menu item, and then choosing “Preferences”.
-
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.
- Update 24 Oct 2012: It seems that Heroku is discouraging the use of older stacks, including the one called Bamboo, which I recommended above, so if you want to host on Heroku you’ll have to use their latest stack Cedar. Unfortunately this stack does not have Varnish cache on which Toto relies for its caching, meaning that every time the same page is loaded again it will be rendered again, leading to a slower experience. That said… Toto renders pages very quickly, so for a small blog this may not be an issue, but if you expect waves of thousands of visitors you may need to look at other hosting solutions (You’ll need to set up a server with Ruby, Rubygems, Thin, Apache/Nginx, and Varnish cache). If you do host on the latest Heroku stack, you’ll need to use a Gemfile instead of a ‘.gems’ file to specify the gems, which Heroku documents here.