Appendix A. Installation – MongoDB in Action

Appendix A. Installation

In this appendix you’ll learn how to install MongoDB on Linux, Mac OS X, and Windows, and you’ll get at an overview of MongoDB’s most commonly used configuration options. For developers, there are a few notes on compiling MongoDB from its source.

I’ll conclude with some pointers on installing Ruby and RubyGems; this will aid those wanting to run the Ruby-based examples from the book.

A.1. Installation

Before we proceed to the installation instructions, a note on MongoDB versioning is in order. Briefly, you should run the latest stable version for your architecture. Stable releases of MongoDB are marked by an even minor version number. Thus, versions 1.8, 2.0, and 2.2 are stable; 1.9 and 2.1 are development versions and should not be used in production. The downloads page at http://mongodb.org provides statically linked binaries compiled for 32-bit and 64-bit systems. These binaries are available for the latest stable releases as well as for the development branches and nightly builds of the latest revision. The binaries provide the easiest way to install MongoDB across most platforms, including Linux, Mac OS X, Windows, and Solaris, and they’re the method we’ll prefer here.

A.1.1. MongoDB on Linux

There are three ways to install MongoDB on Linux. You can download the precompiled binaries directly from the mongodb.org website, use a package manager, or compile manually from source. We’ll discuss the first two in the next sections, and then provide a few notes on compiling later in the appendix.

Installing with precompiled binaries

First navigate to http://www.mongodb.org/downloads. There you’ll see a grid with all the latest downloadable MongoDB binaries. Select the download URL for the latest stable version for your architecture. These examples use MongoDB v2.0 compiled for a 64-bit system.

Download the archive using your web browser or the curl utility. Then expand the archive using tar:

$ curl http://downloads.mongodb.org/linux/mongodb-linux-x86_64-2.0.0.tgz
    > mongo.tg
$ tar -xzvf mongo.tgz

To run MongoDB, you’ll need a data directory. By default, the mongod daemon will store its data files in /data/db. Create that directory, and ensure that it has the proper permissions:

$ sudo mkdir -p /data/db/
$ sudo chown `id -u` /data/db

You’re ready to start the server. Just change to the MongoDB bin directory and launch the mongod executable:

cd mongodb-linux-x86_64-2.0.0/bin
./mongod

If all goes well, you should see something like the following abridged startup log. Note the last lines, confirming that the server is listening on the default port of 27017:

Thu Mar 10 11:28:51 [initandlisten] MongoDB starting :
  pid=1773 port=27017 dbpath=/data/db/ 64-bit
Thu Mar 10 11:28:51 [initandlisten] db version v2.0.0, pdfile version 4.5
...
Thu Mar 10 11:28:51 [initandlisten] waiting for connections on port 27017
Thu Mar 10 11:28:51 [websvr] web admin interface listening on port 28017

If the server terminates unexpectedly, then refer to section A.5.

Using a package manager

Package managers can greatly simplify the installation of MongoDB. The only major downside is that package maintainers may not always keep up with the latest MongoDB releases. It’s important to run the latest stable point release, so if you do choose to use a package manager, be sure that the version you’re installing is a recent one.

If you happen to be running Debian, Ubuntu, CentOS, or Fedora, you’ll always have access to the latest versions. This is because 10gen maintains and publishes its own packages for these platforms. You can find more information on installing these particular packages on the mongodb.org website. Instructions for Debian and Ubuntu can be found at http://mng.bz/ZffG. For CentOS and Fedora, see http://mng.bz/JSjC.

Packages are also available for FreeBSD and ArchLinux. See their respective package repositories for details.

A.1.2. MongoDB on Mac OS X

There are three ways to install MongoDB on Mac OS X. You can download the precompiled binaries directly from the mongodb.org website, use a package manager, or compile manually from source. We’ll discuss the first two in the next sections, and then provide a few notes on compiling later in the appendix.

Precompiled binaries

First navigate to http://www.mongodb.org/downloads. There you’ll see a grid with all the latest downloadable MongoDB binaries. Select the download URL for the latest stable version for your architecture. The following example uses MongoDB v2.0 compiled for a 64-bit system.

Download the archive using your web browser or the curl utility. Then expand the archive using tar:

$ curl http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.0.0.tgz >
    mongo.tgz
$ tar xzf mongo.tgz

To run MongoDB, you’ll need a data directory. By default, the mongod daemon will store its data files in /data/db. Go ahead and create that directory:

$ mkdir -p /data/db/

You’re now ready to start the server. Just change to the MongoDB bin directory and launch the mongod executable:

$ cd mongodb-osx-x86_64-2.0.0/bin
$ ./mongod

If all goes well, you should see something like the following abridged startup log. Note the last lines, confirming that the server is listening on the default port of 27017:

Thu Mar 10 11:28:51 [initandlisten] MongoDB starting :
  pid=1773 port=27017 dbpath=/data/db/ 64-bit
Thu Mar 10 11:28:51 [initandlisten] db version v2.0.0, pdfile version 4.5
...
Thu Mar 10 11:28:51 [initandlisten] waiting for connections on port 27017
Thu Mar 10 11:28:51 [websvr] web admin interface listening on port 28017

If the server terminates unexpectedly, then refer to section A.5.

Using a package manager

Package managers can greatly simplify the installation of MongoDB. The only major downside is that package maintainers may not always keep up with the latest MongoDB releases. It’s important to run the latest stable point release, so if you do choose to use a package manager, be sure that the version you’re installing is a recent one.

MacPorts (http://www.macports.org) and Homebrew (http://mxcl.github.com/homebrew/) are two package managers for Mac OS X known to maintain up-to-date versions of MongoDB. To install via MacPorts, run the following:

sudo port install mongodb

Note that MacPorts will build MongoDB and all its dependencies from scratch. If you go this route, be prepared for a lengthy compile.

Homebrew, rather than compiling, merely downloads the latest binaries, so it’s much faster than MacPorts. You can install MongoDB through Homebrew as follows:

$ brew update
$ brew install mongodb

After installing, Homebrew will provide instructions on how to start MongoDB using the Mac OS X launch agent.

A.1.3. MongoDB on Windows

There two ways to install MongoDB on Windows. The easier, preferred way is to download the precompiled binaries directly from the mongodb.org website. You can also compile from source, but this is recommended only for developers and advanced users. You can read about compiling from source in the next section.

Precompiled binaries

First navigate to http://www.mongodb.org/downloads. There you’ll see a grid with all the latest downloadable MongoDB binaries. Select the download URL for the latest stable version for your architecture. Here we’ll install MongoDB v2.0 compiled for 64-bit Windows.

Download the appropriate distribution, and then unzip it. You can do this from the Windows Explorer by locating the MongoDB .zip file, right-clicking on it, and then selecting Extract All... You’ll then be able to choose the folder where the contents will be unzipped.

Alternatively, you can use the command line. First navigate to your Downloads directory. Then use the unzip utility to extract the archive:

C:\> cd \Users\kyle\Downloads
C:\> unzip mongodb-win32-x86_64-2.0.0.zip

To run MongoDB, you’ll need a data folder. By default, the mongod daemon will store its data files in C:\data\db. Open the Windows command prompt, and create the folder like so:

C:\> mkdir \data
C:\> mkdir \data\db

You’re now ready to start the server. Just change to the MongoDB bin directory and launch the mongod executable:

C:\> cd \Users\kyle\Downloads
C:\Users\kyle\Downloads> cd mongodb-win32-x86_64-2.0.0\bin
C:\Users\kyle\Downloads\mongodb-win32-x86_64-2.0.0\bin> mongod.exe

If all goes well, you should see something like the following abridged startup log. Note the last lines, confirming that the server is listening on the default port of 27017:

Thu Mar 10 11:28:51 [initandlisten] MongoDB starting :
    pid=1773 port=27017 dbpath=/data/db/ 64-bit
Thu Mar 10 11:28:51 [initandlisten] db version v2.0.0, pdfile version 4.5
...
Thu Mar 10 11:28:51 [initandlisten] waiting for connections on port 27017
Thu Mar 10 11:28:51 [websvr] web admin interface listening on port 28017

If the server terminates unexpectedly, then refer to section A.5.

Finally, you’ll want to start the MongoDB shell. To do that, open a second terminal window, and then launch mongo.exe:

C:\> cd \Users\kyle\Downloads\mongodb-win32-x86_64-2.0.0\bin
C:\Users\kyle\Downloads\mongodb-win32-x86_64-2.0.0\bin> mongo.exe

A.1.4. Compiling MongoDB from source

Compiling MongoDB from source is recommended only for advanced users and developers. If all you want to do is operate on the bleeding edge, without having to compile, you can always download the nightly binaries for the latest revisions from the mongodb.org website.

That said, you may want to compile yourself. The trickiest part about compiling MongoDB is managing the various dependencies. These include Boost, Spider-Monkey, and PCRE. The latest compilation instructions for each platform can be found at http://www.mongodb.org/display/DOCS/Building.

A.1.5. Troubleshooting

MongoDB is easy to install, but users occasionally experience minor problems. These usually manifest as error messages generated when trying to start the mongod daemon. Here I provide a list of the most common of these errors along with their resolutions.

Wrong architecture

If you try to run a binary compiled for a 64-bit system on a 32-bit machine, you’ll see an error like the following:

-bash: ./mongod: cannot execute binary file

On Windows 7, the message is more helpful:

This version of
C:\Users\kyle\Downloads\mongodb-win32-x86_64-1.7.4\bin\mongod.exe
is not compatible with the version of Windows you're running.
Check your computer's system information to see whether you need
a x86 (32-bit) or x64 (64-bit) version of the program, and then
contact the software publisher.

The solution in both cases is to download and then run the 32-bit binary instead. Binaries for both architectures are available on the MongoDB download site (http://www.mongodb.org/downloads).

Nonexistent data directory

MongoDB requires a directory for storing its data files. If the directory doesn’t exist, you’ll see an error like the following:

dbpath (/data/db/) does not exist, terminating

The solution is to create this directory. To see how, consult the preceding instructions for your operating system.

Lack of permissions

If you’re running on a Unix variant, you’ll need to make sure that the user running the mongod executable has permissions to write to the data directory. Otherwise, you’ll see this error

Permission denied: "/data/db/mongod.lock", terminating

or possibly this one:

Unable to acquire lock for lockfilepath: /data/db/mongod.lock, terminating

In either case, you can solve the problem by opening up permissions in the data directory using chmod or chown.

Unable to bind to port

MongoDB runs by default on port 27017. If another process, or another mongod, is bound to the same port, you’ll see this error:

listen(): bind() failed errno:98
    Address already in use for socket: 0.0.0.0:27017

There are two possible solutions to this. The first is to find out what other process is running on port 27017 and then terminate it. Alternatively, run mongod on a different port using the --port flag. Here’s how to run MongoDB on port 27018:

mongod --port 27018

A.2. Basic configuration options

Here I present a brief overview of the flags most commonly used when running MongoDB.

  • --dbpath—The path to the directory where the data files are to be stored. This defaults to /data/db.
  • --logpath—The path to the filename where log output should be directed. Log output will be printed to standard output (stdout) by default.
  • --port—The port that MongoDB listens on. If not specified, this is set to 27017.
  • --rest—This flag enables a simple REST interface that enhances the server’s default web console. The web console is always available 1,000 port numbers above the port the server listens on. Thus if the server is listening at localhost on port 27017, then the web console will be available at http://localhost:28017/. Spend some time exploring the web console and the commands it exposes, as you can discover a lot about a live MongoDB server this way.
  • --fork—Detaches the process to run as a daemon. Note that fork only works on Unix variants. Windows users seeking similar functionality should look at the instructions for running MongoDB as a proper Windows service. These are available at mongodb.org.

Those are the most important of the MongoDB startup flags. Here’s an example of their use on the command line:

$ mongod --dbpath /var/local/mongodb --logpath /var/log/mongodb.log
--port 27018 --rest --fork

Note that it’s also possible to specify all of these options in a config file. Simply create a new text file (we’ll call it mongodb.conf) and you can specify all the preceding options, one per line:

dbpath=/var/local/mongodb
logpath=/var/log/mongodb.log
port=27018
rest=true
fork=true

You can then invoke mongod using the config file with the -f option:

$ mongod -f mongodb.conf

If you ever find yourself connected to a MongoDB and wondering which options were used at startup, you can get a list of them by running the getCmdLineOpts command:

> use admin
> db.runCommand({getCmdLineOpts: 1})

A.3. Installing Ruby

A number of the examples in this book are written in Ruby, so to run them yourself, you’ll need a working Ruby installation. This means installing the Ruby interpreter as well as Ruby’s package manager, RubyGems.

You should use a version of Ruby greater than or equal to 1.8.7. Versions 1.8.7 and 1.9.3 are the most common production versions at the time of this writing.

A.3.1. Linux and Mac OS X

Ruby comes installed by default on Max OS X and on a number of Linux distributions. You may want to check whether you have a recent version by running

ruby -v

If the command isn’t found, or if you’re running a version older than 1.8.7, you’ll want to install or upgrade. There are detailed instructions for installing Ruby on Mac OS X as well as on a number of Unix variants at http://www.ruby-lang.org/en/downloads/ (you may have to scroll down the page to see the instructions for the various platforms). Most package managers (such as MacPorts and Aptitude) also maintain a recent version of Ruby, and they’re likely to be the easiest avenue for getting a working Ruby installation.

In addition to the Ruby interpreter, you need the Ruby package manager, RubyGems, to install the MongoDB Ruby driver. Find out whether RubyGems is installed by running the gem command:

gem -v

You can install RubyGems through a package manager, but most users download the latest version and use the included installer. Instructions for doing this can be found at https://rubygems.org/pages/download.

A.3.2. Windows

By far the easiest way to install Ruby and RubyGems on Windows is to use the Windows Ruby Installer. The installer can be found here: http://rubyinstaller.org/downloads. When you run the executable, a wizard will guide you through the installation of both Ruby and RubyGems.

In additional to installing Ruby, you can also install the Ruby DevKit, which permits the easy compilation of Ruby C extensions. The MongoDB Ruby driver’s BSON library may optionally use these extensions.