This document is a collection of research notes on using Mindquarry collaborative software. They haven’t been edited or proofread, so there are most certainly a lot of typos and mistakes. Please send your ideas, comments, and corrections to dmpop@openoffice.org. Thank you!

Mindquarry is a collaboration solution geared towards small and medium workgroups. Mindquarry consists of two components: a server and a client. The former provides all the functionality while the latter acts as a bridge between the user’s desktop and the server. Client’s main purpose to keep documents in sync.

• Instead of reinventing the wheel, Mindquarry relies on proven and mature technologies such as Subversion, wiki and more.
• Seamless integration between user’s desktop and web interface. The Mindquarry Desktop Client provides an extremely easy way to keep documents in sync hiding all the intricacies of Subversion. The client supports multiple profiles, which allows the user to work with several Mindquarry servers.
• Tight integration between different Mindquarry’s modules. For example, the user can link wiki pages to document, tasks, and users.
• Extensive use of AJAX makes the web interface act as a desktop application.
• Mindquarry server and client software run on Linux, Mac OS X, and Windows.
• Thanks to intuitive interface and well-thought-out feature set, Mindquarry has a very gentle learning curve. This makes it easier for users to get to grips with Minquarry as well as significantly reduce training costs for the company.
• The main benefit of AJAX is that it eliminates page reloads, making the user experience more seamless and the application more responsive. Basically, it solve several frustrating usability problems like double-clicking on the same button twice and latency between action and response.
• The Activity Timeline is a killer feature from the end-user perspective. Keeping track of document versions is serious challenge even for experienced users. The Activity Timeline uses the timeline metaphor to tackle this challenge and makes the process of finding and retrieving any previous version rather straightforward.

Although installing the server on Ubuntu Feisty Fawn requires quite a few steps, it’s rather straightforward process. Using the following description, you can have Mindquarry up and running in 20 minutes time. The description assumes that you are installing Mindquarry on a freshly installed Ubuntu 7.04 Feisty Fawn, which will act as a local server.

First of all, you have to have to install several packages that Mindquarry relies on. This includes Java, Subversion, Apache server, and a few Apache modules. While you can install this packages using the Synaptic package manager,

Step 1. Install Java SDK (you can also use Automatix to install the latest version of the Java SDK):

sudo apt-get install sun-java5-sdk

Step 2. Install Subversion:

sudo apt-get install subversion

Step 3. Install Apache and Apache modules:

sudo apt-get install apache2 libapache2-svn libapache2-mod-perl2

Once the Apache server and the modules are installed, you will be prompted to restart the server. Do so using the following command:

sudo /etc/init.d/apache2 force-reload

Step 4. Create the required symbolic links:

sudo ln -s /etc/apache2/mods-available/perl.load /etc/apache2/mods-enabled/
sudo ln -s /etc/apache2/mods-available/dav.load /etc/apache2/mods-enabled/
sudo ln -s /etc/apache2/mods-available/dav_svn.load /etc/apache2/mods-enabled/
sudo ln -s /etc/apache2/mods-available/proxy.load /etc/apache2/mods-enabled/
sudo ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/

Step 5. Run the following command to ensure that everything is working properly:

sudo apache2ctl configtest

You should see the message similar to this:

apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1 for ServerName
Syntax OK

Step 6. Download the latest binary package of Mindquarry server for your platform (in this case, the latest release for the 32-bit platfom is (mindquarry-launcher-1.1-linux_x86_32.bin) and install it using the following command:

sudo sh /home/dmpop/mindquarry-launcher-1.1-linux_x86_32.bin

The installer asks you a few questions. Press Enter to accept the default settings.

Verifying archive integrity... All good.
Uncompressing Mindquarry Collaboration Server 1.1.....
Welcome to the Mindquarry Installer
In the following process the installer will check installation
prerequisites, ask for basic configuration parameters and install the
Mindquarry collaboration server on your system

Java 5 is installed. Good enough.
mod_perl2 and LWP::UserAgent are installed
Subversion has been found

Where should Mindquarry be installed? Press RETURN for default [/opt/mindquarry]

Where should Mindquarry keep its data? Press RETURN for default [/opt/mindquarry/data]

What is the name of your Mindquarry instance? [Mindquarry]

What is the hostname of your Mindquarry Installation? [localhost]

Where is your Apache2 configuration file located [/etc/apache2/httpd.conf]

Which user should run the Mindquarry Server? [root]

  - Copying Mindquarry installation files
  - Patching Mindquarry configuration files
  - Changing ownership of Mindquarry installation directory
  - Changing ownership of Mindquarry data directory
  - Raising open files limit for user root
  - Including Mindquarry configuration into Apache configuration file%%


Mindquarry is installed. You can start the Mindquarry server by running
/opt/mindquarry/bin/mindquarry start

Step 7. Before you can actually start the Mindquarry server, you have to restart Apache:

sudo /etc/init.d/apache2 restart

At this point, you will most likely get the following error message:

* Forcing reload of web server (apache2)...
Syntax error on line 1 of /opt/mindquarry/etc/apache.conf:
Invalid command 'DavLockDB', perhaps misspelled or defined by a module not included in the server configuration

To fix the problem, install the libapache-mod-dav module:

sudo apt-get install libapache-mod-dav

Add then a symbolic link:

sudo ln /etc/apache2/mods-available/dav_fs.load /etc/apache2/mods-enabled/

And restart the Apache server:

sudo /etc/init.d/apache2 restart

Step 8. Finally, you have to increase the limit of opened files:

sudo su
ulimit -n 10000

Step 9. Finally, you can the Mindquarry server (note that you still has to be in the “sudo su” root mode):

/opt/mindquarry/bin/mindquarry start

Step 10. Point your browser to http://localhost:8080, and you should see Mindquarry in all its beauty. Login using the default admin/admin user name and password.

If you try to create a new user or team, you may get the 404 Page Not Found error. To fix the problem open the mindquarry-webapplication.properties configuration file:

gksudo gedit /opt/mindquarry/etc/mindquarry-webapplication.properties

Then change the following line:

mindquarry.server.url=http://localhost

to

mindquarry.server.url=http://localhost:8080

Restart the Mindquarry server, and you are back in business.

The Teams module is designed to manage users and teams. As an example, let’s create a team called Writers, then create the Author, Editor, and Proofreader users, and add them to the team.

There are three things you need to do as soon as you log in to Mindquarry server. You have to change the default administrator password and account info, add users, and create at least one team. To change the administrator account details and password, click on the Edit your user profile button in the upper-right corner of the window. This opens the Change User Profile windows, where you can change the default data.

Populating Mindquarry with users is equally easy. Click on the Team tab, and press the New User button. Fill out the required fields, and press the Create User button.

Next step is to create a team, which is also an easy thing to do. Basically, teams allow you to group users, and it’s up to you what criteria to use when grouping users into teams. For example, you can group users either by project or by function.

To create a team, press the New Team button, enter the required information, and press the New Team button. Once the team has been created, you have to add users to it. Press the Members button, add the users you want to the group, and press Save.

• On the first login, you need to change the default administrator settings
• You also have to add users to Mindquarry
• Teams are used to group users either by projects or by function

The Mindquarry Client is a utility that acts as a bridge between your desktop and the Mindquarry server. The client does two important things:

• it keeps documents on your computer in sync with the Mindquarry server
• it allows you to keep tabs on tasks

There are two ways to install the Mindquarry Desktop Client on your computer. When you log in to the Mindquarry server, there is the Desktop Client link. Click on it, and the latest version of the client will be automatically downloaded, installed, and launched on your machine. Alternatively, you can download the latest release of Mindquarry Desktop Client from the Mindquarry’s website, and run it manually. To do this unpack the downloaded .tar.gz file in your home directory, rename the resulting folder to mindquarry-desktop-client, and launch it from terminal using the following command:

java -jar mindquarry-desktop-client/mindquarry-desktop-client.jar

Once the Mindquarry Desktop Client is up and running, you have to configure a server profile containing information about your Mindquarry server the client needs in order to connect to it. To do this, right-click on the client’s icon in the Panel, choose Options, and navigate to Common Settings → Server Profiles. Press the Add Profile, give the new profile a name, and press OK. Use the credentials of an existing Mindquarry user to fill out the Your Login ID and Password fields, and enter the server URL in the URL of the Mindquarry Server field (in this case, it’s http://127.0.0.1:8080). Finally, you have to specify a path to a folder that will contain your workspaces. A workspace is an equivalent of a team in the Mindquarry server. For example, if you have the Writers team on the server, the specified folder on your computer will have a directory with the same name containing all the team’s documents. Every time you add or modify a document in the Writers workspace, the client automatically syncs the changes with the respective team on the server. Press OK to save the setting and close the dialog window.

Now perform a sync operation; Right-click on the client icon in the Panel and choose Synchronize. If everything works properly, the folder you’ve specified in the server profile will be populated with the workspaces. If you get an error message, try the following fix. Stop the Mindquarry server:

/opt/mindquarry/bin/mindquarry stop

Then run the following command:

sudo chown -R www-data /opt/mindquarry

Start the server and try to sync again.

While the client sits most of the time in the background and keeps files and documents in sync, it also allows you to manage the tasks. Click on the client’s icon in the Panel, and you see all the existing tasks in the pop-up window. To add a new task press the New Task button. This open Edit Task dialog window, where you can specify the task’s details, such as name, status, priority, and due date. Press OK to close the window and save the task.

The Files module is probably the most important part of the Mindquarry collaboration suite. However, the Files module is not a conventional document repository. In fact, it’s primary function is not even to store documents. The Files module does two important things:

• it ensures that the documents stay in sync across multiple desktops
• it keeps track of all changes made to every shared document

The Files module is based on Subversion (http://subversion.tigris.org/) a powerful and mature version control system used by many open source software developers. Subversion allows the developers and users to track any changes made to a file in a so-called repository, a directory that is “watched” by Subversion. The File module in Mindquarry hides all the inner workings of Subversion and makes it extremely easy to use. You don’t even need to know how the system works, but understanding the basics can help you to avoid problems and troubleshoot issues if they occur. So let’s take a look at what makes Mindquarry’s Files module tick.

Once you’ve created a team (for example, Writers) and added users to it, each user must install the Mindquarry Desktop Client to link her desktop with the Mindquarry server. When the user runs the client for the first time, it creates a workspace with the team’s name (in this case, Writers). Now if he user puts, say, an OpenOffice.org Writer document in that folder, the document will be propagated to other team users’ desktops. Whenever any of the team users modify the document, the changes are automatically propagated during the syncing operation. More importantly, each time the users perform a sync, the Mindquarry server makes a copy of of the modified document. This means that all changes made to the documents are recorded, and the users can always retrieve a previous version of the document.

Most of the time, you don’t have to think about behind-the-scenes stuff. Simply use the Mindquarry Desktop Client to run a synchronization operation each time you add or modify a document in the workspace, and you’ll be fine. There is just one important thing you have to keep in mind, though. When you are syncing modified documents, the client prompts you to enter a message. It’s a good idea to use this feature to describe the changes you made to the document. This makes it significantly easier to locate the version of the document you need.

While the Mindquarry Desktop Client makes it extremely easy to keep documents and files in sync, the File module of the Mindquarry server offers a few clever features that can help you to stay abreast of the changes and manage document versions.

The Activity Timeline, a unique and nifty tool that presents all document changes as a timeline. Every time you sync a modified document, Mindquarry places a mark on the timeline. Click on the mark, and you see brief description of changes (this is why it’s a good idea to add a description during syncing). If you click on the Show files link, the file list above the Activity Timeline will display the file versions from the given date. This way you can view the previous versions of a documents and roll back to an earlier edition of a file, if necessary.

Another way to keep track of changes is to use the Recent Changes section, which provides a list of changes grouped by users. This can come in handy when you want to see changes to a document of file done by a particular user. Clicking on a version of the document displays it on the Activity Timeline.

Using an RSS feed in the Files module, you can keep track of changes in real time without even logging in to the Mindquarry server. Simply subscribe to the feed using your favorite RSS reader, and you can stay abreast of all document-related activities.

• The Mindquarry Desktop Client keep all the documents on multiple desktops in sync
• The Mindquarry server keeps the copies of all document versions
• The Activity Timeline allows users to quickly locate any earlier version of a particular document
• The Recent Changes section displays all document changes grouped by users
• Users can keep tracks of changes by subscribing to the Files RSS feed

When you create a team, Mindquarry conveniently creates a wiki for it. But to make the most of Mindquarry’s Wiki module, you should understand the basic principles of a wiki.

A wiki is a website that usually has the following properties:

• Anyone can edit pages.
• Instead of HTML, a wiki uses an easy-to-use markup, which makes it easy for users to edit pages.
• The system keeps all previous versions of the pages, so the users can easily undo any changes.
• Anyone can add a new page by simply adding a link to it. If the page doesn’t exist the wiki creates it automatically.

Here’s how wiki works. Users visit the wiki, reading the pages. When a user sees something that’s wrong or needs fixing, she can just do that. Each change made by the users is recorded. The wiki records the difference between the old and the new revision of the page, and lists the change on a special page, traditionally called Recent Changes. This is where regular visitors check for new recent changes. If they see something they disagree with, they can discuss it, move it, or undo it. That’s how spam is reverted, too.

Not only can existing pages be edited easily, new pages can be added just as easily. Edit an existing page, add a link to a new page, and save. The link to the new page will allow you to edit the new page. Thus, all pages are automatically linked and the web of pages grows organically.

While the Mindquarry’s Wiki module follows these basic rules, it adds a few clever twists of its own. First of all, only team members can add and edit wiki pages. All the editing done in the graphical mode, which means that you don’t have to fiddle with markup. Instead, all the formatting functions are available through the buttons on the main toolbar. In other words, you work with a wiki page in Mindquarry as with a document in a conventional word processor. If you prefer to work in the “raw code” mode, you can switch to it by pressing on the HTML Source button. Unlike a conventional wiki, the Wiki module in Mindquarry uses standard HTML, which has two major advantages: you don’t have to learn yet another set of markup rules, and you can easily import HTML pages into the wiki. Better yet, many word processors such as OpenOffice.org Writer allows you to save text documents in the HTML format ready to be imported into the wiki.

Each wiki in the Wiki module contains the default start page, which acts as a starting point. To edit it, press the Edit button. This opens the page in the editing mode. The main toolbar contains the buttons that allow you to quickly apply formatting to the selected text. Most of these buttons are self-explanatory, but the Insert link button feature deserves a closer look since it offers a rather novel approach to the whole linking concept. When you select a text fragment and press the Insert link button, the system displays a dialog windows containing different linking options. The Web tab, for example, allows you to quickly add a link to different domains (.com, .org, and .net), or to a Wikipedia article. To see how this works in practice, type and select the word “monkey”, press the Insert link button, switch to the Web tab, and choose the Wikipedia option. This automatically inserts a link to the Wikipedia article on monkeys. In a similar manner, you can add links to documents, tasks, other wiki pages as well as teams and users. The clever part is that Mindquarry uses the selected text to find and display the related resources. For example, when you select the word “chapter”, the system finds and displays all documents, wiki pages, and tasks containing the word (for example, “Chapter1.odt”, “Research notes for Chapter III”, “Finish Chapter IV”). Of course, you don’t have to link to any of the existing resources: instead, you can choose to create an empty wiki page. to do this, click on the Wiki tab in the linking dialog window, and choose the Create a new wiki page option. You can also create a new wiki page by simply pressing the New Page button in the main window.

Similar to the Files module, the Wiki part features the Activity Timeline, which maps all the versions of the currently viewed wiki page. You can use the timeline to go back and view the previous versions of the page. To do this, click on the dot on the timeline representing an earlier version of the page, and click on the Show Wiki page in the pop-up window.

The Recent Changes section provides a list of all modified pages, and you can subscribe to wiki’s RSS feed to keep track of changes in the Wiki module. Finally, you can generate a PDF version of any wiki page by clicking on the PDF icon.

Using the Search field you can search the existing wiki pages. The search feature support query operators, including AND, OR, NOT. Note that these operators must be in uppercase. If you don’t specify any operators, the system uses the default AND operator, which searches for all words specified in the search query. You can use parentheses to group query terms and quotation marks to search for exact phrases.

• Mindquarry creates a wiki for each team
• Users can easily edit wiki pages using buttons in the main toolbar
• Wikis in Mindquarry offers unique linking options: you can add links to documents, tasks, external URLs, and other resources
• The Wiki module features the Activity Timeline that maps all previous versions of the currently viewed wiki page
• Any page in the wiki can be saved as PDF, and user can subscribe to the wiki RSS feed
• The Search feature allows users to search wiki pages using operators

Although Mindquarry doesn’t offer a dedicated calendar, it features a rather impressive Tasks module. For starters, the module is heavily AJAXified, which makes it more like a desktop application than a web-based task manager. More importantly, however, it provides an ingenious way to manage the tasks. In a traditional task manager, when you create a new task, you have to fill out a number of mandatory and optional fields. In Mindquarry, you can on-the-fly choose what fields to use. When you create a new task, you have an option to insert additional fields or remove the existing ones by pressing the appropriate Fields buttons. For example, if you want to add a detailed description of the task, press the Description field button, and the Description field is added to the task form (including a WYSIWYG tool bar for rich formatting). Need to assign the task to a particular user? Press the People button and select the user you want from the drop-down list. To remove a field from the task form, press the appropriate button. By adding and removing fields from the task form, you can customize each task, so it contains only relevant information.

* Dependencies is another useful feature that allows you to link tasks.

The Tasks module includes yet another useful feature. If you have hundreds of tasks in your system, keeping track of them can be a bit of a challenge. To solve this problem, the Tasks module allows you to create a filter that displays only tasks that meet the specified rules. Better yet, you can save the filter for later use. For example, you can create a filter that displays only low-priority tasks assigned to you and save it as “Things I have to do some time”. Since you can add as many rules as you need, you can create rather advanced filters. But that’s not all. The Tasks module provides RSS feeds, so you track the tasks using your favorite RSS reader. You can export the tasks into a PDF file.

The Tasks module also generates a calendar file you can subscribe to using any iCal-compatible calendar application. For example, you can use Mozilla Sunbird (a standalone calendar tool) or Lightning (a calendar extension for Thunderbird email client) you can subscribe to your teams tasks by setting up a new network calendar. To do this, choose File → New Calendar, and select the On the Network option. In the Tasks module in Mindquarry, right-click on the Calendar icon in the Alternative versions section, and copy the calendar link (in Firefox, choose the Copy Link Location command). Return to the Sunbird (or Lightning) calendar, press the Next button, select the iCalendar (ICS) option, and enter the copied calendar link into the Location field. Press Next, give your calendar a name, and press OK. You should then see the list of tasks in the Tasks pane of the Sunbird/lightning calendar.

http://en.wikipedia.org/wiki/Mindquarry

http://www.mindquarry.com/docs/user/index.html

http://www.mindquarry.org/mindquarry/docbook/features.html

http://www.mindquarry.com/docs/dev/architecture/index.html

http://weblogs.goshaky.com/weblogs/mindquarry/entry/collaboration_2_0_first_steps

http://weblogs.goshaky.com/weblogs/mindquarry/entry/collaboration_2_0_first_steps1

http://www.mindquarry.com/community/articles/elements-collaboration