Setting Up an Apple Mac for Ruby Development

  1. Do This First!
  2. Configuring a User Account
  3. Configuring Security
  4. Setting Up for Ruby Development
  5. Essential Developer Tools
  6. Installing MySQL on Mac OS X
  7. Other Applications
  8. Other Resources

This is a set of notes for setting up an Apple Mac, specifically as a development system for Ruby. Current versions of OS X have a fairly good default configuration for general-purpose use, but you do need to to adjust some of the security settings. In addition, you will need to install several pieces of software in order to make the system useful for development.

Do This First!

Login once, run Software Update, and ensure that the operating system is at the latest point release. This is particularly crucial for Mac OS X 10.5 (Leopard), where the firewall software was significantly modified by a later point release.

After all of the updates have been applied, and the computer has rebooted, create an Admin user account for your use. If other people will be using the machine, create Standard accounts for them.

Always login to this new account. The benefit of leaving the initial account untouched is that it ensures that you always have a working account to login with.

Admin accounts have sudo privileges: All Admin accounts on a Mac may use sudo to run command-line utilities with administrative (root) privileges.

You should also find an external hard drive. Begin using Time Machine as soon as possible, as it provides the most easy method for backing up your system.

Configuring a User Account

Creating a Private Applications Folder

Once you have logged into your account, create a folder called Applications within your home folder. Whenever you are prompted to drag a new applications into the global Applications folder, put it in this private Applications folder instead. Some applications have to be installed to global folders, but in most cases you can keep the system directories clean by storing third-party products in your private Applications folder.

Securing the Safari Browser

Whether or not you use Safari, you should open it once, and change these settings:

Both of these options have been proven to allow successful attacks on systems.

Configuring Security

Mac OS X is a reasonably secure operating system, but unfortunately convenience has won out over security in a few places. These can easily be corrected by changing a few settings. If you are using a laptop then you should probably make all of these changes as soon as possible.

Basic Settings

Select System Preferences > Security > General, and set the following:

Under Firewall, choose Block all incoming connections. On Leopard (Mac OS X 10.5) this option does not exist; instead set Allow only essential services.

New installations of Snow Leopard use secure virtual memory by default. If you enable secure virtual memory yourself, restart your system so that the feature is active.

Requiring a Password on Bootup

Intel-based Macs include EFI firmware that runs when the machine is powered on, to start the operating system. This takes the place of the standard PC BIOS, or Open Firmware on older Macs. If your computer is frequently left in public places, then set a boot password. Otherwise, any malicious individual can change the firmware settings to boot from a disc or device of their choosing, and completely avoid all of the security measures of the installed operating system.

Apple Knowledge Base article HT1352 provides full details.

Setting Up Time Machine Backups

Time Machine is very, very simple to setup. Just take a suitably large external hard drive, plug it in to your Mac, and agree when prompted. The drive setup process will reformat the hard drive. The only settings that may need to change are the exclusions.

Choose System Preferences > Time Machine, and click Options. Add to the exclusions list any folders that contain ISO disk images, virtual machines, or database files (such as Entourage). If the external hard drive is short of space, exclude the System folder.

A Word on File Vault

Only use File Vault if you know that you need it, are aware of the consequences, and know how to recover your data. File Vault is secure, which means that you can permanently lose access to your data if you lose the passwords.

The design of File Vault also means that it can seriously affect the performance of operation involving any large file, such as multimedia, disk images, or virtual machines.

I recommend that you keep any sensitive data in an encrypted volume created with TrueCrypt, instead of using File Vault or the facilities for encrypted disk images.

Setting Up for Ruby Development

RubyGems needs a C compiler in order to build the native extensions that are part of many gem packages. XCode Tools, the Apple developer suite, includes a C compiler. The XCode Tools installer is on the OS X Install DVD provided with current Macs, in the Optional Installs folder.

The latest version of XCode is always available from the Mac Dev Center Website. You will need to register and login to access the downloads from the Mac Dev Center.

Next, ensure that you update the copy of RubyGems on your system, as the versions supplied with both Leopard (Mac OS X 10.5) and Snow Leopard (Mac OS X 10.6) have been superseded. To update RubyGems on Snow Leopard, enter this command in a Terminal window:

sudo gem update --system

See below for instructions on how to update RubyGems on Leopard.

Once the current version of RubyGems is installed, do not use sudo for any further gem commands, apart from updates to RubyGems itself. RubyGems will then install all new packages and updates to a private gem repository within your home directory, leaving the system copies untouched. For example, use this command to get the latest version of Rake, without disturbing the copy bundled with Mac OS X itself:

gem update rake

If you have followed the instructions above, you can upgrade Rails to the latest release with RubyGems. Enter this command in a Terminal window:

gem update rails

Finally, amend your PATH setting so that the command-line utilities from your private gem directory are invoked by default.

Amending Your PATH Setting

Your PATH environment variable needs to include the bin subdirectory of your private gem directory, so that the correct version of the command-line tools are invoked by default. To do this, create a text file called .profile within your home directory. Once the file exists, the settings in it override the global defaults. Add this line in the .profile file:

export PATH=$HOME/.gem/ruby/1.8/bin:$PATH

Any change to your profile applies to all new Terminal windows, but does not affect those that are currently open.

Upgrading RubyGems on Leopard (Mac OS X 10.5)

To do this, first install the updater through RubyGems itself:

sudo gem install rubygems-update

Then run the updater:

sudo update_rubygems

You may need to run the updater twice for it to complete successfully.

Essential Developer Tools

Every developer needs a text editor and a version control system. Mac OS X includes software for both of these jobs, but most developers prefer to install more sophisticated tools.

Choosing a Text Editor

Very few programmers use TextEdit, the supplied desktop text editor for Mac OS X. TextEdit is designed for light-weight word processing, rather than development, and many superior options exist. Mac OS X itself also includes both Emacs and the vim version of vi, for traditional UNIX users. The most popular text editors for programmers on OS X are probably BBEdit and TextMate, both of which are proprietary.

Whichever text editor you choose, remember to set the EDITOR environment variable in your ~/.profile file, so that this editor is automatically invoked by command-line tools like your version control system. For example, put this line in your profile to make TextMate the favored text editor:

export EDITOR="mate"

Installing the Git Version Control System

Mac OS X includes both Subversion, and the obsolete CVS, so that you can work with older source code repositories. Install and use Git, instead of these older tools. Git has become the standard for Ruby and Rails development.

To install Git, first go to the Web site and follow the link for Other Download Options to obtain a Mac OS X disk image. Open your downloaded copy of the disk image and run the enclosed installer in the usual way, then dismount the disk image.

Current versions of BBEdit do not include any integration with Git. To enable the Git support features of TextMate, choose TextMate > Preferences > Advanced and create a new shell variable called TM_GIT with this value:


You can then either press Control-Shift-G to call a short menu of options, or select Bundles > Git for a complete set of commands.

Installing MySQL on Mac OS X

If you develop any kind of database-driven application, it is useful to have a version of the database server available on your system. The majority of Ruby Web applications use MySQL, which you can easily set up.

First, download the disk image for the 64-bit version of MySQL Community Server from the MySQL Web site. Open the disk image and run the enclosed package. Once you have done this, run the installer for the preferences pane, which is in the main disk image alongside the package for the server.

MySQL on OS X is not installed with a configuration file. The MySQL server automatically runs with the default configuration. To override the defaults, create a MySQL configuration file as /etc/my.cnf and add your custom settings there.

The MySQL package installs all of the required files into a subdirectory of /usr/local/, and ensures that the symbolic link /usr/local/mysql points to the root directory for most recent version of MySQL on the system. This means that the command-line utilities always appear to be in /usr/local/mysql/bin. To conveniently run these utilities, add this location to your PATH environment variable:

export PATH=$HOME/.gem/ruby/1.8/bin:/usr/local/mysql/bin:$PATH

To install the Ruby driver for MySQL on Mac OS X Snow Leopard, run this command:

sudo env ARCHFLAGS="-arch x86_64" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

You must have setup the Ruby installation with a compiler, as described above. The Ruby MySQL driver requires a compiler to build native extensions.

Securing MySQL

Set a password for the root accounts. First, login with the mysql command-line utility:

mysql -u root -q

The -q Option Disables Command History: By default, the MySQL client stores the full text of every command in a history file. If you know that you are going to run statements that include passwords or other sensitive data, use the -q option.

Run these statements to change the password for root access:

UPDATE mysql.user SET password = PASSWORD('yourpassword') WHERE user LIKE 'root'; FLUSH PRIVILEGES; EXIT;

You now need a password to login to the installation as root. To login with root again, use this command:

mysql -u root -p

Enter the password when prompted.

You should also remove the anonymous accounts and test database that MySQL automatically includes:


If you intend to run MySQL in production, or duplicate a production environment for testing, create a configuration file. Production installations of MySQL should be configured with appropriate SQL modes to enable data integrity safeguards. By default, MySQL permits various types of invalid data to be entered.

Removing MySQL from Mac OS X

To remove MySQL later, first ensure that you have not set it to at startup, and then stop the service. Run these commands in a Terminal window to delete MySQL from your system:

sudo rm -r /usr/local/mysql-5.1.41-osx10.5-x86_64
sudo rm -r /usr/local/mysql
sudo rm -r /LibraryPreferencePanes/MySQL.prefPane

Ensure that you have backup copies of any data before you delete the MySQL installation.

If you amended your PATH variable, remember to remove /usr/local/mysql/bin from it.

Other Applications

Mac OS X has a double identity – it is both a UNIX operating system, and a proprietary graphical desktop system. This enables it to host a broad range of products from both strands of software development.

Desktop Applications

The ready-to-use versions of VirtualBox are free for personal use, but not actually Open Source. If you want to pay for a virtual machine application with better desktop integration, VMWare Fusion is probably the best product available.

Command-line Utilities

Current versions of Mac OS X include most of the popular UNIX command-line utilities. If you need to install additional command-line tools, add Homebrew to your system.

Other Resources

Online Resources

Apple offer overviews and task-orientated help on their support Web site.

Every new user should probably read How to switch to the Mac, by Rui Carmo.

The iusethis site is probably the best resource for finding new software, as well as a useful way to maintain a catalog of your installed applications.


The single best book on Mac OS X is the Missing Manual, by David Pogue. Once you have this, you only need to buy books that are specifically relevant to your fields of interest.

If you use TextMate, then you should buy TextMate: Power Editing for the Mac, by James Edward Gray. Most of the power of TextMate is not obviously apparent, which make this book close to essential for new TextMate users.

Rubyists will also benefit from getting a PDF version of Programming Ruby (the Pickaxe book). This may not be the best resource for learning Ruby, but it is the most complete reference, and is very useful to have on your computer in a searchable form.