Running a local sandbox

QMachine (QM) can be installed and run locally, which can be extremely useful for development as well as for deployment behind firewalls.

Prerequisites

QM is developed on Mac and Linux systems, and the Makefile located in the root of the main project’s Git repository contains live instructions for building and testing everything.

To get up and running, you will need GNU Make, a standard POSIX development environment, and Git.

To build and run an API server, you will need MongoDB and either Node.js or Ruby. If you choose the Node.js version, you can use CouchDB, PostgreSQL, Redis, or SQLite instead, but the Makefile assumes Mongo by default.

To build the homepage and/or custom images, you will need ImageMagick.

PhantomJS is used for regression testing and for creating snapshots that can be converted into thumbnails.

Mac OS X

To get started on Mac OS X with your own local sandbox, you will want to install the Homebrew package manager using directions from its website. It will allow you to install all of the software mentioned previously by launching Terminal and typing

$ brew install couchdb imagemagick mongodb node phantomjs postgresql redis

I highly recommend installing Git through Homebrew, as well, but it isn’t required. I prefer Apache’s official CouchDB.app and Heroku’s Postgres.app over the distributions installed by Homebrew because they include convenient launchers that live in the menu bar.

Ubuntu Linux

Ubuntu has a great built-in package manager that we can take advantage of, but package names vary by version. Incantations are forthcoming.

Node.js

First, make sure that you have NPM installed:

$ which npm || echo 'NPM is missing'

If NPM is missing, refer to its documentation for the installation procedure.

Next, check out QM’s source code from GitHub:

$ git clone --recursive https://github.com/qmachine/qmachine.git

Now, select your local copy of the repository as the current directory:

$ cd qmachine/

Finally, start MongoDB and then launch QM on localhost:

$ make node-app

QM defaults to MongoDB for storage, but a different database can be specified explicitly:

$ make node-app db=couch
$ make node-app db=mongo
$ make node-app db=postgres
$ make node-app db=redis
$ make node-app db=sqlite

Ruby

A Ruby implementation of QM is also available in the project repository, and its directions are similar to those for Node.js. If you don’t already use RVM, you should – it’s fantastic and highly recommended.

First, make sure that you have Bundler installed:

$ which bundler || echo 'Bundler is missing'

If Bundler is missing, install it:

$ gem install bundler

Next, check out QM’s source code from GitHub:

$ git clone --recursive https://github.com/qmachine/qmachine.git

Now, select your local copy of the repository as the current directory:

$ cd qmachine/

Finally, start MongoDB and then launch QM on localhost:

$ make ruby-app

QM defaults to MongoDB for storage, but the Ruby version also has experimental support for Postgres, Redis, and SQLite. Thus, possible command-line incantations include:

$ make ruby-app db=mongo
$ make ruby-app db=postgres
$ make ruby-app db=redis
$ make ruby-app db=sqlite