Follow Jeff Sayre on Twitter

Integrating MongoDB Into BitNami’s MAMPStack

By

"Integrating MongoDB into your BitNami MAMPStack is a relatively straightforward process — at least if you are a developer accustomed to building and modifying your dev stacks. Reading this article will take you some time. But, once you fully understand this process, it should take no more than fifteen minutes to install and configure MongoDB to work within your BitNami MAMPStack."

mongoDB-logo

This article is for all you OS X Lion-based Mac developers who use BitNami’s MAMPStack and dream of being able to add a NOSQL database engine, like MongoDB, to the stack. If you are not running Lion, then there is no reason to proceed.

BitNami offers a variety of development and production stacks that make it quick and easy to set up a localhost-based development environment or even provision a production-based server with a full suite of tools. If you are familiar with the better known MAMP, offered by the German company appsolute GmbH, then you should have no issues using BitNami’s version instead.

What are the benefits of using BitNami’s MAMPStack?

First, as of the date of this article, their stack is up to date. It is compiled and built with the most recent, stable versions of PHP, Apache, MySQL, and phpmyadmin. Second, they offer a very easy-to-install PostgreSQL addon module that integrates into the MAMPStack. This provides the opportunity to use an alternative database, even leveraging PHP’s PDO extension to create a truly SQL-agnostic application. It should not be too hard in the future to add support for other open source SQL-based RDBMSs like Percona or even Drizzle. Third, they seem very responsive to their user community.

Why would you want to integrate MongoDB into your MAMPStack?

The days when a RDBMS could be the end all and be all of your backend are over. For more on this point, read part three of my five-part Smartup series, Web 3.0 Smartups: Moving Beyond the Relational Database.

In short, in the Social Web, smartups cannot use a RDBMS as their only backend tool for every job. A RDBMS is not a universal tool. In fact, RDBMSs — MySQL in particular — are overused and often misused.

Let’s Get Started!

Integrating MongoDB into your BitNami MAMPStack is a relatively straightforward process — at least if you are a developer accustomed to building and modifying your dev stacks. Reading this article will take you some time. But, once you fully understand this process, it should take no more than fifteen minutes to install and configure MongoDB to work within your BitNami MAMPStack.

How do I know? Because before posting this article, I deleted my BitNami MAMPStack using the uninstall.app application with which it ships. This deleted all the work I did in integrating MongoDB into the stack. I then reinstalled the stack and repeated the process below. Of course, I had backup copies of the BitNami MAMPStack because there is no need to redownload that. But, I did go through the entire below process. Total time? Thirteen minutes and four point six seconds — and that is with two MAMPStack server restarts. Bam!

Disclaimer: Before you begin, you agree that you have read this disclaimer and the next one and agree with them. You understand that you are entirely on your own with this process. If you are not comfortable with UNIX commands, if you have never worked within Terminal before, if you do not know how the steps listed below will affect your computer, and if you do not know how to fix any issues that may arise out of trying out these steps, then do not proceed. I am not responsible for what happens to your computer as a result of these suggested techniques. You have been warned. Proceed at your own risk.

Disclaimer 2: This process should not be used on production servers. It is only suitable for a development environment running on localhost.

A. Compiling the MongoDB PHP Driver From Source

Grab the very latest version of the MongoDB PHP Driver. Download the tarball version.

(Note: Although you can try installing the driver using PHP’s PECL command, I’ve had spotty luck with that approach in the past when attempting to install MongoDB into a third-party dev stack. The driver did not always get installed in the proper location. Sometimes it got installed in the extension directory of the default version of PHP that ships with OS X. When that happens, you have to uninstall the driver and try reinstalling it into the proper directory. As this has proven unreliable in the past, I find it easiest to compile from source then move the extension into the proper location within the MAMPStack. It just takes a few more minutes but ensures that everything is in its proper place.)

Drag the tarball out of your Downloads folder onto your desktop. Then double click on the mongo-x.x.x.tar tarball to extract the files. This will create the driver folder. Open up Terminal and navigate to that folder. Each line below starting with a “$” indicates a new terminal command. Before beginning, see the notes below the ordered list. Enter these commands one at a time in Terminal:

NOTE: You may need to change the mampstack version number below if you are installing a newer version — in other words, a version that came out after this article was posted or updated. It is currently updated for MAMPStack version 5.3.10-1 and PostgreSQL Module Addon 5.3.10-1.

  1. $ cd /Users/{your_user_name}/Desktop
  2. $ ls
  3. $ cd mongo-x.x.x
  4. $ cd mongo-x.x.x
  5. $ sudo /Applications/mampstack-5.3.10-1/php/bin/phpize
  6. $ ./configure
  7. $ sudo make install

Terminal Notes

Step 1: Replace {your_user_name} with the name of your mac account user. It is the name that appears within the /Users folder.

Step 2: The list command will allow you to double check the MongoDB file folder name which you will enter in the next step.

Step 3: Switch to the directory that contains your MongoDB PHP Driver and associated files. Replace the x.x.x with the version number of the driver which should be the same as that listed for the folder name.

Step 4: This seems like a repeat of above, but if you inspect the folder structure of the driver download, you will see what is going on. This switches into the directory within the downloaded folder that contains the actual driver source files. It is within this directory that you run the compile commands.

Step 5: The phpize command prepares the build environment for PHP extensions — in this case, for building the MongoDB PHP Driver extension (mongo.so). You will be prompted to enter your administrator password. This is your mac user account password (assuming that you are the owner of the mac).

When the screen of output is finished, you will have a compiled MongoDB Driver extension located in the modules directory of the driver folder. Look in /mongo-x.x.x/mongo-x.x.x/modules for the extension named mongo.so. Copy that extension into the following folder in your BitNami MAMPStack directory:

mampstack-5.3.10-1/php/lib/php/extensions

Now you need to add the following to your listed extensions within the php.ini file. In the BitNami MAMPStack, the php.ini file can be found here:

mampstack-5.3.10-1/php/etc

Open the php.ini file in your favorite IDE and add this to the “Dynamic Extensions” section of the file, just below the last active extension:

extension=mongo.so

Save and close the php.ini file.

Now, before continuing on to the next step, if your MAMPStack server is running, stop it and then restart it. Visit your phpinfo page to make sure that the MongoDB PHP Driver has been installed and is active. If you don’t know what a phpinfo page is, visit this link. (I made my PHP Info Page and placed it at root level in the apache2/htdocs folder before I began this process.) Run your phpinfo page and look for the “Configuration” section in the output. Now scroll down until you see “mongo”. Check to make sure the version number is what you expect.

If you do not see “mongo” listed, or the version number is incorrect, you’ll have to start the process again — but first you will need to delete the mongo.so file from BitNami MAMPStack’s PHP extension folder. However, if everything looks fine, you’re ready for the next section below — part two.

B. Adding and configuring the MongoDB Database

In this section, we’ll setup the MongoDB backend and make sure that it is functioning properly.

Follow these simple steps:

  1. Download the most recent, stable OS X 64-bit binary version of MongoDB. Double click the tarball to extract the files.
  2. Create a new folder called “mongo” in BitNami MAMPStack’s root. When you are done, you will have this directory structure: mampstack-5.3.10-1/mongo
  3. Create three subfolders in this newly-created mongo folder, setting their permissions to 775:
    bin
    data
    tmp

    Within the newly-created data directory, add the following subfolder with permissions set to 775 as well:

    db

  4. Install the MongoDB files you’ve just downloaded and extracted into the mampstack-5.3.10-1/mongo/bin. Make sure you install just the contents of the bin folder within the downloaded MongoDB folder and not the bin folder too.
  5. Next, you’ll create a configuration file for mongoDB. This file will tell mongo where to store data, log errors, and which directory to use for temporary stuff. In your favorite IDE, create a new file named mongodb.conf in the root directory of your mongo install ( mampstack-5.3.10-1/mongo ). In that file, add the following:

    Important Note: You can copy the entire text below and paste it into your new, empty mongodb.conf file. However, before saving and closing this file, make sure there are no spaces on the blank lines between the code blocks. If you have even a single space on a blank line — or even after a command line — your Mongo server will not start up as it will believe the line with a space is a command line. It will not know how to interpret this phantom command. So, when attempting to start your Mongo server in step 6 below, if you receive this error, error command line: unrecognized line in ‘ ‘, that means you have a space somewhere in this file. Find it, delete it, and try again. As much as I tried, I could not get the Syntax Highlighter to create the below text without adding an extra space between lines.

    # Store data in default MongoDB directory structure, /data/db/
    dbpath = /Applications/mampstack-5.3.10-1/mongo/data/db
    
    # Set location where all MongoDB errors should be logged.
    # This should create a log file if it does not exist
    logpath = /Applications/mampstack-5.3.10-1/mongo/mongodb.log
    
    # Set location of pid file; this should create one if it does not exist
    pidfilepath = /Applications/mampstack-5.3.10-1/mongo/tmp/mongo.pid
    
    # Only accept local connections
    bind_ip = 127.0.0.1

    Save and close your newly-created mongodb.conf file.

  6. To launch MongoDB server, open up terminal and type the following command all on one line. However, as we have just made significant additions and changes to the basic, out-of-the-box BitNami MAMPStack, you need to restart your BitNami MAMPStack servers to make sure all the changes are picked up.

    Once the MAMPStack servers have restarted, type this into Terminal — place your cursor in the box and copy the entire string as it does extend beyond the margins of the box:

    sudo /Applications/mampstack-5.3.10-1/mongo/bin/mongod --config=/Applications/mampstack-5.3.10-1/mongo/mongodb.conf

    Please note: From now on, this is how you will start your mongod server.

  7. Test your MongoDB install to make sure that the server is running. By default, MongoDB listens to port 27017. You can verify which port MongoDB is listening to by looking up the configuration settings of your MongoDB PHP Driver in the PHP Info page. However, Mongo’s Web-based admin console listens to port 28017. Therefore by visiting “localhost:28017” in your browser, you can see if you have a connection. If you do, you’re all set!

To learn more about starting and stopping the MongoDB server (Mongod), see this resource.

(Note: You could install MongoDB into your /usr/local/ directory and then symlink the binaries out of the /usr/local/mongo/bin folder to the BitNami MAMPStack. However, the idea in this method is to keep all the applications bundled under the same master folder — your BitNami MAMPStack. That way, uninstalling the stack is very simple. You just delete the BitNami MAMPStack folder from your /Applications directory. The method presented here also makes it easy to move this application setup to another machine. Finally, although it is normally not an issue, with this method you do not have to worry about potential problems when upgrading your OS.)

C. Download and install phpMoAdmin

We are almost finished! If you’ve successfully completed parts one and two above, congratulations! You have integrated MongoDB to run inside of your BitNami MAMPStack. This last step will provide you with a tool to manage MongoDB.

Just as you use phpmyadmin to administer and manage your MySQL databases, MongoDB has several database admin tools written in PHP. We’re going to be installing phpMoAdmin. Grab the most recent stable version.

Once you’ve downloaded a copy, unzip it if it did not automatically unzip. Next, create a new folder within Apache’s htdocs folder called phpmoadmin. Copy the moadmin.php file into this new folder.

Done! You now can access this very simple, but useful MongoDB admin tool by visiting “localhost:8080/phpmoadmin/moadmin.php” in your browser.

Alternatively, you can use MongoHub or RockMongo to administer your MongoDB backend. I suggest checking all three out and deciding which one you like best.

Why are we using phpMoAdmin? It offers the most recently-updated version out of the three and it is simple to install as it is a single, small file. For this article, it is sufficient. However, the other tools may provide better GUIs and a stronger set of features. So, you should check them out and decide which one you like best.

Don’t Forget to Give Thanks!

That’s it!

You can further expand your BitNami MAMPStack by setting up VHOSTs in your Apache config file, but that is beyond this article. If you’re interested in that, see the documentation in the /apache2/manual folder.

Finally, please remember to give back to the open source community as it provides you with high-quality, powerful software with many freedoms — and often free as in cost, too. Share this article, write your own, create a version of this article for Linux distros or Windows, volunteer time to an open source project, contribute bug fixes, thank BitNami for their services, or donate to help fund an open source project. Free and Open Source Software (FOSS) needs your support!

Now go out there and create the next, greatest Smartup!

More resources

Article Comments

  1. Gustavo says:

    With your help i just added mongo to my bitnami lampstack.
    I even added mongo to ctlscript in bitnami’s folder :)

    Thanks a lot!

Leave a Reply

Share on Twitter
Share on Facebook
Share on FriendFeed
Share on LinkedIn
Share on StumbleUpon
Share on Digg
Share on Delicious
Share on Technorati
Add to Google Bookmarks

Archives