Chapter 2

Mongrel2 is designed to build on most modern Unix systems, specifically Linux and Mac OSX. It is written in C (not Ruby) and uses fairly vanilla C and standard libraries, except for one piece that implements the internal coroutines. Other than this, you should be able to compile and install Mongrel2 with nothing more than make all install after you’ve installed all the dependencies.

Now, if when I said dependencies you started to groan at having to install software to use my software. Well, my friend, welcome to the future. You said you don’t want people reinventing the wheel, right? Great. That means you need to install software for my software to work. It’s either that or wait 10 years for me to build everything from scratch like some arrogant jackass.

We good now? Great, let’s get started.

2.1 Install Dependencies

To get everything working you will need the following dependencies:

If you install these things in this order, then everything should be good.

Since every system is different, it is difficult to tell you exactly how to install required packages for your OS, but here’s how I did it on my computer:

Source 1: Installing Dependencies on ArchLinux
  # install ZeroMQ
  tar -xzvf zeromq-2.1.7.tar.gz
  cd zeromq-2.1.7/
  sudo make install
  # install sqlite3
  sudo pacman -S sqlite3

If you run into parts that your OS is missing, which is likely on Debian and SuSE systems, then you’ll have to go and figure out how to install it.

Some distributions (like Ubuntu) split “dev” and “runtime” packages. In order to build mongrel2 on these distros, you must install both. The package libsqlite3-dev contains sqlite3.h, which Mongrel2 needs during compilation, the package sqlite3 is needed for the unit tests.

Other pieces known to be missing on ubuntu-like systems:

For the lazy, the command is: sudo apt-get install uuid-runtime sqlite3 libsqlite3-dev

2.2 Getting Mongrel2

If everything went well, you should be able to grab the Mongrel2 source and try building it. There’s two ways you can get the source code to Mongrel2:

  1. Install Git and check out the source.
  2. Grab the source .zip or tar.bz2 release and install it from there.

2.2.1 Using the .tar.bz2 File

The easiest way to build Mongrel2 is to use the .tar.bz2 file from the main page downloads section. Simply download it and you’re done.

2.2.2 Using git

If you like living on the edge then here’s how to follow the development source tree while we work on it:

First, get git running on your system, through your package manager or fetch the proper sources or binaries from the Git Download page.

Once you have git you can then get the Mongrel2 source and open it up:

Source 2: Cloning the Mongrel2 Source
  git clone
  cd mongrel2

Make sure you do this in order (just like with every set of instructions you follow) or else you’ll get errors.

In order to stay up-to-date with all the changes, remember to periodically update your checkout (make sure you’re in the latest version before reporting a bug!). It’s as simple as git pull. And remember to rebuild and install afterwards!

2.3 Building And Installing

Once you have the source ready to go you can build it and then install it with one command: make all install

There is no ./configure for Mongrel2 since we avoid too many OS specific differences or shield those away with good feature checks in the code.

If you want to install to a different location than the default /usr/local, use PREFIX=/path/to/somewhere make all install instead.

The end result of this should be:

  1. Mongrel2 builds and compiles without errors.
  2. All the unit tests run.1
  3. The m2sh binary gets installed.
  4. The mongrel2 binary gets installed.

If any of these stages fail, then you can simply try to fix them and then run: make clean all && sudo make install, which will do everything all over again.

2.3.1 Other platforms than Linux

If you aren’t running Linux, chances are good this standard procedure will not work for you.

The Makefile lists several targets for various platforms. As of writing this, there are:

So, for example, you would probably install zeromq and sqlite3 as ports and then compile it like so:

Source 3: Installing Mongrel2 on FreeBSD
  # install ZeroMQ
  cd /usr/ports/devel/zmq
  make install
  # install sqlite3
  cd /usr/ports/databases/sqlite3
  make install
  # install mongrel2
  cd /where/you/extracted
  gmake freebsd install

2.4 Testing The Installation

When you are done, you probably want to make sure that it installed correctly. There’s a test configuration file in tests/config.sqlite that you can use to try it out:

Source 4: First Test Run
  mkdir run
  mkdir logs
  mkdir tmp
  m2sh servers -db tests/config.sqlite
  m2sh start -db tests/config.sqlite -host localhost

That’s it! Just hit CTRL-c for now and we’ll get into playing with this setup later.

2.5 Up Next

You now should have a working Mongrel2 system installed and the m2sh configuration interface ready to go. In the rest of this manual we’ll be simply learning how to do more with Mongrel2, like making our own configs, writing handlers, and other fun stuff.

1Please tell us about failures.