With some help from Lars, I managed to get Mindquarry up and running straight from the SVN repository (this is where the development code resides). I did this to have a look at the development status of the upcoming 1.1 release.

It’s a cool feeling to live on the bleeding edge and to see daily improvements to our software immediately. Wanna do the same? Here’s a foolproof how-to which is intended to also help those who are not really familiar with the command line. A much more concise how-to is available in the Mindquarry documentation. Those of you familiar with Java development might want to take look there to switch to the fast lane.

Operating system

I run Mac OS X 10.4.9, but I guess this brief tutorial will also help you on any other unixish operating system.

Terminal aka command line aka shell

Let’s wake up the sleeping monster: the terminal window. You can do so by typing “terminal” into the spotlight window and by choosing the “Terminal” program as displayed in the screenshot below:

Let the monster relax a bit in the background and proceed with the following tasks.

Installing Subversion client

Install Subversion to access the development code and to download it to your computer. Luckily, Lars pointed me to this easy to install .dmg Subversion package by Martin Ott.

Installing Maven

Below you will see how to download the source code onto your computer with the Subversion client, but first, you must download and install Maven to later be able to build the Mindquarry application from that source code. Installing Maven is actually quite simple.

Get the .zip package from the Maven download page, and place it e.g. in your personal directory. Unzip the archive (I use The Unarchiver) and move it to /usr/local/maven-2.0.6 by issuing the following command in the terminal (the monster you woke up – remember?):

sudo mv ~/maven-2.0.6 /usr/local/maven-2.0.6

That’s all!

Easy access to Maven and Subversion via command line

I made sure that I can conveniently access Subversion on the command line with just typing svn instead of providing the full path to the executive binary. Same goes for Maven with the mvn command.

Type into the terminal window:

nano -w ~/.profile

This will open a simple text editor within the terminal window. There you enter (you can copy&paste from here):

export PATH="/usr/local/maven-2.0.6/bin:/usr/local/bin:$PATH"

Press CTRL+X and confirm with Y that you want to save the file. You can check if all worked out well by issuing the following command in the terminal window:

echo $PATH

… which should display a text containing the above given paths.

Getting the code

Before you type something into the terminal window which should just have popped up, you create the directory where you want to put the Mindquarry SVN code which you will download as the next step. For example, create a directory called mindquarry-code in your Documents folder.

Now, change to the newly created folder in the terminal window. For example by entering

cd ~/Documents/mindquarry-code/

The ~ indicates your home directory, where your personal folders on your Mac reside.
Type the following into the terminal window and execute it by pressing the return key to obtain the Mindquarry source code:

# svn co https://www.mindquarry.org/repos/mindquarry-collaboration-server/trunk/ mindquarry-code

Note the https: Make sure you have it included, otherwise you won’t be able to get the code. You will most likely be asked to accept a SSL certificate after execution – please do so.

Simply wait until all the code has been downloaded, then proceed as follows.

Building Mindquarry with Maven

To build the application with Maven, change to this directory in the terminal window:

cd ~/Documents/mindquarry-code

Issue this command and wait until execution is done (which might take a while):

mvn install

Now you are done with building.

Configuring Mindquarry and your environment

You just need to do one thing to configure Mindquarry properly before running it. Copy the properties file to the folder above. In detail this is in the terminal window:

cd ~/Documents/mindquarry-code/mindquarry-webapp/mindquarry-webapplication

Then:

cp mindquarry-webapplication.properties/config.template .

The cp command – you guessed it right – copies the file to the current directory.

Open the properties file with

nano -w mindquarry-webapplication.properties

and make sure that the following properties are declared as shown

mindquarry.jcr.path=file:/var/mindquarry/jcr

mindquarry.solr.path=/var/mindquarry/solr

mindquarry.repos.path=/var/mindquarry/svn

If you are just building from SVN to try out Mindquarry and do not want to develop the code, then I recommend you let Mindquarry run in production mode, which is much faster. To do so, change the following property:

org.apache.cocoon.mode=prod

Just like before, press CTRL+X and confirm with Y to save the file.

In case you actually plan to develop Mindquarry, then keep this property as it is. When running Mindquarry in development mode, it needs quite some RAM because pages need to be build repeatedly upon request. Hence, to make sure that Mindquarry runs sufficiently fast on your system, raise the amount of memory it has available. To do so, create the respective file by entering to the terminal window:

nano -w ~/.mavenrc

There, add these two lines (copy&paste from here):

#!/bin/sh
MAVEN_OPTS="-Xmx512m $MAVEN_OPTS"

Press CTRL+X and confirm with Y to save the file.

Running Mindquarry

Create the directory /var/mindquarry, because Mindquarry needs it to run properly. Do so by typing into the terminal window:

sudo mkdir /var/mindquarry

You will be prompted for your password and then the folder will be created.

To make sure the folder is accessible for Mindquarry, issue the following command in the terminal:

sudo chmod 777 /var/mindquarry

Now comes the fun part because you will soon be able to play with the hot hot Mindquarry development version. Make sure the terminal is ready for execution in the right folder by issuing this command:

cd ~/Documents/mindquarry-code/mindquarry-webapp/mindquarry-webapplication

Now you can start Mindquarry with:

mvn jetty:run

Wait until you see the following information appear in the terminal window:

[INFO] Started Jetty Server
[INFO] Starting scanner at interval of 15 seconds.

Now open your browser with this URL: http://localhost:8888 and login with username “admin” and password “admin”. Enjoy!

Remember that you are playing with fire, because you installed development code which is usually work in progress and can thus be highly unstable.

Stopping Mindquarry

To stop Mindquarry, press CTRL+C in the terminal window.

Updating from SVN

The good thing is of course that you can now repeatedly update the source code to get the very latest changes and then build and run Mindquarry again. Simply follow these three steps and you’ll be a part of bleeding-edge Mindquarry development:

1. Issue the command svn up from within the ~/Documents/mindquarry-code/ directory (by now, you know that with cd you can switch to this directory in the terminal window).
2. Type mvn clean install from within the folder ~/Documents/mindquarry-code
3. Enter mvn clean package jetty:run from within ~/Documents/mindquarry-code/mindquarry-webapp/mindquarry-webapplication

To really be sure that all the potential JavaScript updates work, empty the cache of your browser.