Appendix A. Installing MongoDB
Installing MongoDB is a simple process on most platforms. Precompiled binaries are available for Linux, Mac OS X, Windows, and Solaris. This means that, on most platforms, you can download the archive from http://www.mongodb.org, inflate it, and run the binary. The MongoDB server requires a directory it can write database files to and a port it can listen for connections on. This section covers the entire install on the two variants of system: Windows and everything else (Linux, Max, Solaris).
When we speak of “installing MongoDB,” generally what we are talking
about is setting up mongod, the core database server.
mongod is used in a single-server setup as either master
or slave, as a member of a replica sets, and as a shard. Most of the time,
this will be the MongoDB process you are using. Other binaries that come
with the download are covered in Chapter 8.
Choosing a Version
MongoDB uses a fairly simple versioning scheme: even-point releases are stable, and odd-point releases are development versions. For example, anything starting with 1.6 is a stable release, such as 1.6.0, 1.6.1, and 1.6.15. Anything starting with 1.7 is a development release, such as 1.7.0, 1.7.2, or 1.7.10. Let’s take the 1.6/1.7 release as a sample case to demonstrate how the versioning timeline works:
Developers release 1.6.0. This is a major release and will have an extensive changelog. Everyone in production is advised to upgrade as soon as possible.
After the developers start working on the milestones for 1.8, they release 1.7.0. This is the new development branch that is fairly similar to 1.6.0, but probably with an extra feature or two and maybe some bugs.
As the developers continue to add features, they will release 1.7.1, 1.7.2, and so on.
Any bug fixes or “nonrisky” features will be backported to the 1.6 branch, and 1.6.1, 1.6.2, and so on, will be released. Developers are conservative about what is backported; few new features are ever added to a stable release. Generally, only bug fixes are ported.
After all of the major milestones have been reached for 1.8.0, developers will release something like, say, 1.7.5.
After extensive testing of 1.7.5, usually there are a couple minor bugs that need to be fixed. Developers fix these bugs and release 1.7.6.
Developers repeat step 6 until no new bugs are apparent, and then 1.7.6 (or whatever the latest release ended up being) is renamed 1.8.0. That is, the last development release in a series becomes the new stable release.
Start over from step 1, incrementing all versions by .2.
Thus, the initial releases in a development branch may be highly unstable (x.y.0, x.y.1, x.y.2), but usually, by the time a branch gets to x.y.5, it’s fairly close to production-ready. You can see how close a production release is by browsing the core server roadmap on the MongoDB bug tracker.
If you are running in production, you should use a stable release unless there are features in the development release that you need. Even if you need certain features from a development release, it is worth first getting in touch with the developers through the mailing list and IRC to let them know you are planning on going into production with a development release and get advice about keeping your data safe. (Of course, this is always a good idea.)
If you are just starting development on a project, using a development release may be a better choice. By the time you deploy to production, there will probably be a stable release (MongoDB keeps a regular cycle of stable releases every couple of months), and you’ll get to use the latest features. However, you must balance this against the possibility that you would run into server bugs, which could be confusing or discouraging to most new users.
Windows Install
To install MongoDB on Windows, download the Windows zip from the MongoDB downloads page. Use the advice in the previous section to choose the correct version of MongoDB. There are 32-bit and 64-bit releases for Windows, so select whichever version you’re running. When you click the link, it will download the .zip. Use your favorite extraction tool to unzip the archive.
Now you need to make a directory in which MongoDB can write database files. By default, MongoDB tries to use C:datadb as its data directory. You can create this directory or any other empty directory anywhere on the filesystem. If you chose to use a directory other than C:datadb, you’ll need to specify the path when you start MongoDB, which is covered in a moment.
Now that you have a data directory, open the command prompt (cmd.exe). Navigate to the directory where you unzipped the MongoDB binaries and run the following:
$ binmongod.exe
If you chose a directory other than C:datadb,
you’ll have to specify it here, with the --dbpath
argument:
$ binmongod.exe --dbpath C:Documents and SettingsUsernameMy Documentsdb
See the Chapter 8 section for more common
options, or run mongod.exe
--help to see all
options.
Installing as a Service
MongoDB can also be installed as a service on Windows. To install,
simply run with the full path, escape any spaces, and use the
--install option. For example:
$ C:mongodb-windows-32bit-1.6.0inmongod.exe
--dbpath ""C:Documents and SettingsUsernameMy Documentsdb"" --installIt can then be started and stopped from the Control Panel.
POSIX (Linux, Mac OS X, and Solaris) Install
Choose a version of MongoDB, based on the advice in the section Choosing a Version. Go to the MongoDB downloads page, and select the correct version for your OS.
Tip
If you are using a Mac, check whether you’re running 32-bit or 64-bit. Macs are especially picky that you choose the correct build and will refuse to start MongoDB and give confusing error messages if you choose the wrong build. You can check what you’re running by clicking the apple in the upper-left corner and selecting the About This Mac option.
You must create a directory for the database to put its files. By default, the database will use /data/db, although you can specify any other directory. If you create the default directory, make sure it has the correct write permissions. You can create the directory and set the permissions by running the following:
$ mkdir -p /data/db $ chown -R $USER:$USER /data/db
mkdir -p creates the directory and all its
parents, if necessary (i.e., if the /data directory
didn’t exist, it will create the /data directory and
then the /data/db directory).
chown changes the ownership of
/data/db so that your user can write to it. Of
course, you can also just create a directory in your home folder and
specify that MongoDB should use that when you start the database, to avoid
any permissions issues.
Decompress the .tar.gz file you downloaded from http://www.mongodb.org.
$ tar zxf mongodb-linux-i686-1.6.0.tar.gz $ cd mongodb-linux-i686-1.6.0
Now you can start the database:
$ bin/mongod
Or if you’d like to use an alternate database path, specify it with
the --dbpath option:
$ bin/mongod --dbpath ~/db
See Chapter 8 for a summary of the most
common options, or run mongod with --help to see all the possible
options.
Installing from a Package Manager
On these systems, there are many package managers that can also be used to install MongoDB. If you prefer using one of these, there are official packages for Debian and Ubuntu and unofficial ones for Red Hat, Gentoo, and FreeBSD. If you use an unofficial version, make sure to check the logs when you start the database; sometimes these packages are not built with UTF-8 support.
On Mac, there are also unofficial packages in Homebrew and MacPorts. If you go for the MacPorts version, be forewarned: it takes hours to compile all the Boost libraries, which are MongoDB prerequisites. Start the download, and leave it overnight.
Regardless of the package manager you use, it is a good idea to figure out where it is putting the MongoDB log files before you have a problem and need to find them. It’s important to make sure they’re being saved properly in advance of any possible issues.