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.
We’ll conclude with some pointers on installing Ruby and RubyGems to 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, 2.2, 2.4, 2.6 and 3.0 are stable; 2.1, 2.3, and 2.5 are development versions and shouldn’t be used in production. The downloads page at www.mongodb.org provides statically linked binaries compiled for 32- and 64-bit systems. But as of MongoDB v3.0, 32-bit binaries will no longer be supported. 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 an easy way to install MongoDB across most platforms, including Linux, Mac OS X, Windows, and Solaris, and they’re the method we’ll prefer here. If you run into trouble, you can find more information in the official MongoDB manual at http://docs.mongodb.org/manual/installation.
A.1.1. Production deployments
Using a package manager installation may be preferable for server deployments of MongoDB, because the package installation usually includes scripts to start and stop MongoDB when the machine restarts. In the precompiled binary installation described here, we demonstrate how to run MongoDB from the command line, which is perfect for learning and debugging but not ideal if you’re running a server that other people are accessing. Each operating system distribution and package management system has small differences and idiosyncrasies, such as where MongoDB’s log file is placed. If you plan on running MongoDB as a production service, you should understand MongoDB’s configuration and think through error scenarios, such as what would happen if the server suddenly goes down. If you’re just learning MongoDB or experimenting with it, any installation method is fine.
A.1.2. 32-bit vs. 64-bit
You can download MongoDB binaries compiled for 32- or 64-bit architectures depending on the MongoDB version. If you’re installing MongoDB on a 64-bit machine, we highly recommended that you use the 64-bit binaries because the 32-bit installation is limited to storing only 2 GB of data. Most machines nowadays are 64-bit, but if you’re unsure you can check a Linux or Mac OS X machine by running the command
$ uname –a
which prints information about the operating system. If the OS version includes the text x86_64 (as opposed to i386), then you’re running a 64-bit version. For Windows machines, check the documentation for how to determine which architecture your OS is running.
A.2. 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.
A.2.1. Installing with precompiled binaries
First navigate to 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.6 compiled for a 64-bit system.
Open a command line and download the archive using your web browser, the curl utility or the wget utility. (You should check on the downloads page for the most recent release.) Then expand the archive using tar:
$ curl http://downloads.mongodb.org/linux/mongodb-linux-x86_64-2.6.7.tgz > mongo.tgz $ 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. Change to the MongoDB bin directory and launch the mongod executable:
cd mongodb-linux-x86_64-2.6.7/bin ./mongod
If all goes well, you should see something like the following abridged startup log. The first time you start the server it may allocate journal files, which takes several minutes, before being ready for connections. 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 host=iron Thu Mar 10 11:28:51 [initandlisten] db version v2.6.7 ... Thu Mar 10 11:28:51 [websvr] web admin console waiting for connections onport 28017 Thu Mar 10 11:28:51 [initandlisten] waiting for connections on port 27017
You should now be able to connect to the MongoDB server using the JavaScript console by running ./mongo. If the server terminates unexpectedly, refer to section A.6.
At the time of writing this, the most recent MongoDB release is 3.0.6.
A.2.2. 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 MongoDB, Inc. 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. There may also be other package managers not listed here that include MongoDB. Check the downloads page at www.mongodb.org/downloads for more details.
A.3. MongoDB on Mac OS X
If you’re using Mac OS X, you have three options for installing MongoDB. 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 options in the next sections, and then provide a few notes on compiling later in the appendix.
A.3.1. Precompiled binaries
First navigate to 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 v3.0.6 compiled for a 64-bit system.
Download the archive using your web browser or the curl utility. You should check on the downloads page for the most recent release. Then expand the archive using tar:
$ curl https://fastdl.mongodb.org/osx/mongodb-osx-x86_64-3.0.6.tgz > mongo.tgz $ 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. Go ahead and create that directory:
$ sudo mkdir -p /data/db/ $ sudo chown `id -u` /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-3.0.6/bin $ ./mongod
If all goes well, you should see something like the following abridged startup log. The first time you start the server it may allocate journal files, which takes several minutes, before being ready for connections. Note the last lines, confirming that the server is listening on the default port of 27017:
2015-09-19T08:51:40.214+0300 I CONTROL [initandlisten] MongoDB starting :
pid=41310 port=27017 dbpath=/data/db 64-bit host=iron.local
2015-09-19T08:51:40.214+0300 I CONTROL [initandlisten] db version v3.0.6
...
2015-09-19T08:51:40.215+0300 I INDEX [initandlisten] allocating new ns
file /data/db/local.ns, filling with zeroes...
2015-09-19T08:51:40.240+0300 I STORAGE [FileAllocator] allocating new
datafile /data/db/local.0, filling with zeroes...
2015-09-19T08:51:40.240+0300 I STORAGE [FileAllocator] creating directory
/data/db/_tmp
2015-09-19T08:51:40.317+0300 I STORAGE [FileAllocator] done allocating
datafile /data/db/local.0, size: 64MB, took 0.077 secs
2015-09-19T08:51:40.344+0300 I NETWORK [initandlisten] waiting for
connections on port 27017
You should now be able to connect to the MongoDB server using the JavaScript console by running ./mongo. If the server terminates unexpectedly, refer to section A.6.
A.3.2. Using a package manager
MacPorts (http://macports.org) and Homebrew (http://brew.sh/) 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.4. MongoDB on Windows
If you’re using Windows, you have two ways to install MongoDB. The easier, preferred way is to download the precompiled binaries directly from the mongodb.org website. You can also compile from source, but this option is recommended only for developers and advanced users. You can read about compiling from source in the next section.
A.4.1. Precompiled binaries
First navigate to 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.6 compiled for 64-bit Windows.
Download the appropriate distribution and unzip it. You can do this from the Windows Explorer by locating the MongoDB ZIP file, right-clicking on it, and selecting Extract All. You’ll then be able to choose the folder where the contents will be unzipped. Please keep in mind that because MongoDB v2.6, prebuilt MSIs are also available for download.
Alternatively, you can use the command line. First navigate to your Downloads directory. Then use the unzip utility to extract the archive:
C:> cd UserskyleDownloads C:> unzip mongodb-win32-x86_64-2.6.7.zip
To run MongoDB, you’ll need a data folder. By default, the mongod daemon will store its data files in C:datadb. Open the Windows command prompt and create the folder like this:
C:> mkdir data C:> mkdir datadb
You’re now ready to start the server. Change to the MongoDB bin directory and launch the mongod executable:
C:> cd UserskyleDownloads C:UserskyleDownloads> cd mongodb-win32-x86_64-2.6.7in C:UserskyleDownloadsmongodb-win32-x86_64-2.6.7in> mongod.exe
If all goes well, you should see something like the following abridged startup log. The first time you start the server it may allocate journal files, which takes several minutes, before being ready for connections. 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 host=iron Thu Mar 10 11:28:51 [initandlisten] db version v2.6.7 ... Thu Mar 10 11:28:51 [websvr] web admin console waiting for connections on
If the server terminates unexpectedly, refer to section A.6.
Finally, you’ll want to start the MongoDB shell. To do that, open a second terminal window, and then launch mongo.exe:
C:> cd UserskyleDownloadsmongodb-win32-x86_64-2.6.7in C:UserskyleDownloadsmongodb-win32-x86_64-2.6.7in> mongo.exe
A.5. 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. The latest compilation instructions for each platform can be found at www.mongodb.org/about/contributors/tutorial/build-mongodb-from-source.
A.6. 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 we provide a list of the most common of these errors along with their resolutions.
A.6.1. 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:UserskyleDownloadsmongodb-win32-x86_64-2.6.7inmongod.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 (www.mongodb.org/downloads).
A.6.2. 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 OS.
A.6.3. 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.
A.6.4. 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
This issue has two possible solutions. The first is to find out what other process is running on port 27017 and then terminate it, provided that it isn’t being used for some other purpose. One way of finding which process listens to port number 27017 is the following:
sudo lsof -i :27017
The output of the lsof command will also reveal the process ID of the process that listens to port number 27017, which can be used for killing the process using the kill command.
Alternatively, run mongod on a different port using the --port flag, which seems to be a better and easier solution. Here’s how to run MongoDB on port 27018:
mongod --port 27018
A.7. Basic configuration options
Here’s 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 and is useful if you want to store your MongoDB data elsewhere.
- --logpath —The path to the file 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, it’s 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 1000 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; you can discover a lot about a live MongoDB server this way.
- --fork —Detaches the process to run as a daemon. Note that fork works only 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 www.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. Create a new text file (we’ll call it mongodb.conf) and you can specify the config file equivalent[1] of all the preceding options:
As of 2.6, MongoDB uses a YAML config file format. See docs.mongodb.org/manual/reference/configuration-options for the current documentation on the available options.
storage:
dbPath: "/var/local/mongodb"
systemLog:
destination: file
path: "/var/log/mongodb.log"
net:
port: 27018
http:
RESTInterfaceEnabled: true
processManagement:
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.8. 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 newer version of Ruby, such as 1.9.3 or preferably 2.2.3, which is the current stable version. Version 1.8.7 is still used by many people, and it works well with MongoDB, but the newer versions of Ruby offer advantages such as better character encoding that make it worthwhile to upgrade.
A.8.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 https://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. You can find instructions for doing this at https://rubygems.org/pages/download.
A.8.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 addition to installing Ruby, you can 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.