Mindquarry Installation Guide

Installing the Mindquarry Collaboration Server on Windows,

Lars Trieloff

Mindquarry GmbH

Alexander Klimetschek

Mindquarry GmbH
Revision History
05/02/2007 Lars Trieloff

Initial creation of the installation guide.

19/02/2007 Lars Trieloff

Added troubleshooting section to the installation guide.

23/02/2007 Lars Trieloff

More detailed information about installing Mindquarry on Suse Linux, with thanks to Hans-Georg Dück, instructions on allowing anonymous repository access.

16/03/2007 Lars Trieloff

Operating system-specific installation instructions, reflects the new Mindquarry Installer,

25/03/2007 Alexander Klimetschek

Updating for 1.1-beta release.

13/06/2007 Alexander Klimetschek

Updating for 1.1 release.

17/06/2007 Alexander Klimetschek

More information about installing and upgrading on windows.

03/07/2007 Alexander Klimetschek

Updating for 1.1.1 release, adding general upgrade description and list of links and property changes for each version.

05/07/2007 Lars Trieloff

Clarifications regarding installation of Apache 2 with XAMMP on Windows, thanks to forum user omminp. Instructions on using Mindquarry with SSL support thanks to forum user wolf.

11/07/2007 Alexander Klimetschek

Updating for 1.1.2 release

23/08/2007 Lars Trieloff

Instructions on setting up the mail server for receiving e-mails

Quick Installation

  1. Install Java

  2. Apache 2, mod_perl, Subversion (available as Mindquarry XAMPP package)

  3. Install Mindquarry

  4. Start Mindquarry

  5. Configure your mail server

  6. Go to http://localhost:8080/ and log in with the username “admin” and password “admin”.

  7. When this works, start Apache 2 and go to http://localhost/ and use Mindquarry

More details for these steps are below.

Note

If you are already using Mindquarry, you should read the upgrade guide, to avoid losing your data. Only if you don't need your old data anymore, it's okay to delete your old installation and install from scratch.

Table of Contents

Installation Prerequisites
Installing Java 6
Installing Apache 2 with Subversion and mod_perl on Windows
Installing the Mindquarry Server on Windows
Configuring Mindquarry
Configuring Apache
Configuring your Mail Server
Using the embedded Mail Server
Starting and Stopping Mindquarry
A. Troubleshooting & FAQ
B. Upgrade Guide
Upgrading (without Migration)
List of releases with links and property changes
Upgrading from 1.0-M1 or 1.1-beta to 1.1 with the Windows Installer

Installation Prerequisites

The Mindquarry Collaboration Server can be installed on any operating system, provided that the following prerequistes are met.

  • Java 5 (or higher) Software Development Kit

  • Apache 2 (comes with the Windows XAMPP installer, see below)

  • Subversion as an Apache module (comes with XAMPP)

  • mod_perl (comes with XAMPP)

  • mod_rewrite (comes with XAMPP)

  • Access to an outgoing mail server, if you want advanced e-mail integration

If you do not already have Java 5 or higher installed, download the JDK 6 from Sun. It is available for Windows, Linux and Solaris.

Procedure 1. Installing Java 6

  1. Download the Java Installer from Sun

  2. Double click the downloaded installer file

  3. Follow the instructions given by the installer

  4. Java is installed

Apache 2 is the HTTP server that is used to provide the Subversion repositories for file sharing. In order to use and install Apache 2 for Mindquarry, the following steps are neccessary:

  1. Download the Mindquarry XAMPP installer

  2. Double-click the downloaded installer file

  3. Follow the instructions given by the installer

  4. Select Install Apache as a service

  5. Apache 2 with Subversion and mod_perl is installed

You can start and stop Apache using the Windows services menu, or from Mindquarry XAMPP start menu entries.

Note

If you do not want to use the Mindquarry XAMPP package, for example because you already have an existing Apache 2 installation, then install Subversion as an Apache module and mod_perl separately.

Installing the Mindquarry Server on Windows

In order to install Mindquarry on Microsoft Windows, the following steps are neccessary.

Note

If you are upgrading, please follow the instructions in the upgrade guide, as your existing data could be overwritten if it is located inside the installation directory.

  1. Download the Mindquarry Installer from the Mindquarry Download site

  2. Double-click the Installer and follow the instructions

Mindquarry is then available as a system service and can be started from the administration panel (it might already be started by the installer).

Note

If XAMPP is already running, restart Apache to reload the new configuration for the Mindquarry Server.

Additionally you can start and stop Mindquarry from the Start Menu. Mindquarry will run on its own server on port 8080, so make sure you also start Apache to be able to access Mindquarry at port 80 like any other web server. Starting Apache is also neccessary to be able to use the Desktop synchronization.

Configuring Mindquarry

These configuration settings are for advanced use of Mindquarry. When you are using an installer, reasonable default already have been set, so you can skip this section safely.

Note

The Windows Installer will put the data directory right inside the installation dir(directory). This makes the installation much simpler but makes upgrades more difficult as one has to make sure to backup the data directory. When configuring Mindquarry manually, it is recommended to create a separate directory, eg. c:\mindquarry-data, that will be used instead.

All configuration of the Mindquarry Collaboration Server (but not the Apache environment and startup settings) is handled in C:\your-installation-dir\etc\mindquarry-webapplication.properties. This file is a simple list of name-value-pairs. A line starting with a hash (#) is ignored, it contains a comment. All properties are documented. If you would like a more in-depth view of all the configuration, please read through the comments. For upgrading users you will find a list of new properties in each release below.

Most properties are tuned for running Mindquarry out of the box, you only have to configure three settings:

mindquarry.title

How your Mindquarry server is called. Use this to distinguish one Mindquarry installation from another. This could for instance be the name of your company or your workgroup.

mindquarry.repos.uri

The location where Mindquarry's file sharing repositories are located. Usually you need to replace your.mindquarry.server with the actual DNS name of the machine where Mindquarry is installed. With the default Apache and mod_dav_svn configuration, this is the server name + /repos. If your server is called mindquarry.mycompany.com, the value of this variable should be http://mindquarry.mycompany.com/repos

Note

Please note that the URL should not contain a port number (like http://myserver:8080/repos), because your Apache web server runs on port 80 and this is the default port for URLs starting with http://.

mindquarry.server.url

The location where Mindquarry is installed and available from the network via a browser, either through the http:// or the https:// protocol (depending on the configuration). If your server is called mindquarry.mycompany.com, the value of this variable should be http://mindquarry.mycompany.com. Accessing the server must be done via this exact URL - using http://localhost or the IP address instead will break things, because many absolute links inside the web interface are based on this configuration.

Note

The URL is case-sensitive, so Mindquarry will warn you if you entered http://MyMindQuarryServer.com in the configuration, but access it at http://mymindquarryserver.

The following settings can be left unchanged. They depict the data repositories, it is advisable to use a common directory with a large amount of available space eg. C:\mindquarry-data\. An older default (and the windows installer default) depicted to the data directory inside the installation, but this is not recommended since it is easier for upgrading to new versions when the data is seperate from the server binaries. The three settings must have different directories.

mindquarry.jcr.path

Where Mindquarry's data files are stored, eg. file:///c:/mindquarry-data/repo (or - not recommended - file:///c:/path-to-your-installation/data/repo) This path must be absolute and start with file://, it also has to contain slashes (/) instead of backslashes (\) as path separators.

mindquarry.repos.path

Where Mindquarry's file sharing repositories are stored, eg. c:\\mindquarry-data\\docs (it has to contain two backslashes (\\) in the properties file). This path can be relative.

mindquarry.solr.path

Where Mindquarry's search index is stored, eg. c:\\mindquarry-data\\index (it has to contain two backslashes (\\) in the properties file). This path can be relative.

Configuring Apache

If you are using an Installer, the Apache configuration already has been changed to handle Mindquarry, so you can safely skip this section unless you want to run Mindquarry on a virtual host or need more fine-grained configuration tuning.

Apache needs configuration for the following three purposes:

  • Requests to the Mindquarry application should be handled by Mindquarry

  • Requests to the Mindquarry file sharing repository should be handled by Subversion

  • Requests to the Mindquarry file sharing repository should be authenticated by Mindquarry

Example 1. Running Mindquarry on a virtual host

NameVirtualHost *:80
DavLockDB "C:\Program Files\Mindquarry Collaboration Server\data\dav"
PerlRequire "C:\Program Files\Mindquarry Collaboration Server\perl\Mindquarry\Authenticate.pm"
<VirtualHost *:80>
  ServerName your.mindquarry.server
  <Location /repos>
    DAV svn
    SVNParentPath "C:\Program Files\Mindquarry Collaboration Server\data\docs"
    SVNAutoversioning on

    PerlAuthenHandler Mindquarry::Authenticate
    PerlSetVar AuthBase "http://localhost:8080/files/authorise"
    AuthType Basic
    AuthName "Mindquarry Document Repository"
    Require valid-user
  </Location>
  ProxyRequests Off
  <Proxy *>
    Order Allow,Deny
    Allow from all
  </Proxy>
  RewriteEngine On
  RewriteCond %{REQUEST_URI} !^/(repos|error)/(.*)$
  RewriteRule ^/(.*)$     http://localhost:8080/$1 [P,NC]
  ProxyPassReverse /      http://localhost:8080/
</VirtualHost>

In this example only the ServerName directive needs to be changed, all other directives are perfect for a default installation. If you changed the path of the Mindquarry installation, you need to revise the PerlRequire directive. If you changed the mindquarry.repos.path configuration, you have to revise the SVNParentPath directive.

Restart the Apache Web Server to let these settings take effect.


Configuring your Mail Server

This step is not neccessary for basic operation of Mindquarry, but if you rely on using advanced e-mail integration (sending files as attachement to the files section, starting and continuing conversations in the talk section via email), you should read this section. Mail server configuration differs from server to server, in this example we provide instructions for the Postfix mail server.

Mindquarry offers two options for configuring a mail server. If you do not have a mail server running on your Mindquarry server, the best coice is using the embedded mail server. If the server is already used to send and receive e-mails, this leads to a more difficult configuration.

Mindquarry includes an embedded mail server that receives e-mails, parses them and forwards them to the Mindquarry Collaboration Server. The embedded mail server has the same requirements as the Mindquarry Collaboration Server, namely Java 5 or Java 6. In order to get the embedded mail server up and running, following steps are neccessary:

  1. Configure the DNS to use your mail server as the mail exchange (MX) for the domain name your Mindquarry Server is running.

  2. Set the password for the mail user by opening the mindquarry-webapplication.properties file and adding a parameter mindquarry.mail.pwd.

  3. Download and unpack the mindquarry-smtp package from the Mindquarry Download Repository (during development, downloads are available at the Mindquarry Snapshot Repository)

    The package to download is the ZIP file for Windows.

  4. Go to the bin directory. Launch the mindquarry-smtp.bat under Windows.

    You need to provide four arguments to the program: the host name of the mail server, the addess of the Mindquarry Collaboration Server, an username and a password. The synopsis for the command is:

    mindquarry-smtp mailserver serverurl username password

    Example 2. Launching mindquarry-smtp

    # mindquarry-smtp mymindquarry.com http://mymindquarry.com mail m054pw

    Note

    The mailserver parameter should have the same value as the mindquarry.mail.host parameter in the mindquarry-webapplication.properties configuration file.

Starting and Stopping Mindquarry

If you have used the windows installer, you can start and stop Mindquarry through the services administration or simply through the entries in the start menu. In case you used the binary distribution, you issue the following command:

Example 3. Starting Mindquarry under Windows

C:> C:\Program Files\Mindquarry\bin\mindquarry start

Mindquarry can be stopped using the same script with the stop parameter. If you would like to follow the console output, start Mindquarry with the console parameter. This is useful for troubleshooting and might help tracing down problems.

Mindquarry can then be accessed using your web browser at http://localhost/ (this depends on what was set as mindquarry.server.url and the domain name of the server, see the configuration section for more information). Log in as user admin with password admin to create new users and teams. If you do not see this page, you should stop the Mindquarry Collaboration Server, restart it with the console parameter and examine the error output.

A. Troubleshooting & FAQ

Support for Mindquarry is also available from the Mindquarry Support site and the Mindquarry Forum.

A.1.1. Is it possible to run Mindquarry on another port oher than 8080?
A.1.2. After installation of XAMPP and the Mindquarry server, I can go to http://myserver but I can only see the XAMPP welcome page. What's wrong?
A.1.3. How do I allow read-only anonymous access to the Subversion repository?
A.1.4. I cannot synchronize with my desktop client. Accessing http://server/repos/myteam/ and entering correct credentials also don't work. What's wrong?
A.1.5. I want to use Mindquarry with SSL support, but do not have a server certificate signed by a trusted certificate authority. How do I set up Mindquarry?
A.1.1. Is it possible to run Mindquarry on another port oher than 8080?
A.1.2. After installation of XAMPP and the Mindquarry server, I can go to http://myserver but I can only see the XAMPP welcome page. What's wrong?
A.1.3. How do I allow read-only anonymous access to the Subversion repository?
A.1.4. I cannot synchronize with my desktop client. Accessing http://server/repos/myteam/ and entering correct credentials also don't work. What's wrong?
A.1.5. I want to use Mindquarry with SSL support, but do not have a server certificate signed by a trusted certificate authority. How do I set up Mindquarry?
A.1.1.

Is it possible to run Mindquarry on another port oher than 8080?

Yes it is. Just add another parameter to C:\Program Files\Mindquarry Collaboration Server\etc\wrapper.conf, e.g.

wrapper.java.additional.4=-Djetty.port=8889

You need to change the Apache 2 configuration file accordingly.

A.1.2.

After installation of XAMPP and the Mindquarry server, I can go to http://myserver but I can only see the XAMPP welcome page. What's wrong?

Restart the Apache via the XAMPP control panel so that it reloads the configuration added by the Mindquarry installer.

A.1.3.

How do I allow read-only anonymous access to the Subversion repository?

The Mindquarry Authentication perl module has a parameter called AnonymousMethods that specifies a list of HTTP methods that do not require authentication and enable anonymous access. Adding a line like the following allows anonymous read-only access to the repository.

PerlSetVar AnonymousMethods     "GET PROPFIND OPTIONS REPORT"
A.1.4.

I cannot synchronize with my desktop client. Accessing http://server/repos/myteam/ and entering correct credentials also don't work. What's wrong?

If there is not yet a DocumentRoot set in your Apache config (look at Apache's global config files in C:\Program Files\Xampp for Mindquarry\apache\etc - note that our Xampp installation provides a DocumentRoot setting that works) it introduces problems with the authentication, because the perl Authentication handler registered for Location /repos gets different URLs. Set DocumentRoot to some existing directory.

A.1.5.

I want to use Mindquarry with SSL support, but do not have a server certificate signed by a trusted certificate authority. How do I set up Mindquarry?

First you need to configure Apache to use SSL encryption. There is plenty of documentation available at the Apache 2.0 documentation website. Secondly you need to make sure that the value of mindquarry.server.url starts with https://. If you are using a trused certificate, everything is ok by now.

If you are using a self signed certificate, you have to add your certificate to the Java certification store of every client. You can use following command to import the certificate:

# $JAVA_HOME/bin/keytool -importcert -trustcacerts -file YOUR_CERT.cer -keystore lib/security/cacerts -alias YOUR_ALIAS
The default password for the keystore is “changeit”.

B. Upgrade Guide

Here are the short steps when doing a minor upgrade (eg. from 1.1 to 1.1.1) that does not involve a data or backend database migration. For upgrading special versions see the following section(s). There is no updating installer yet - if you re-run a new installer it will overwrite your existing settings and maybe your data, if it is contained within the installation directory.

To upgrade, you will basically have to update the webapps folder with the contents of the new mindquarry-webapplication.war and also update the file etc/mindquarry-webapplication.properties if new properties were added.

  1. Go into your installation directory.

  2. Make a backup of the existing webapps directory, eg. move it to webapps-old.

  3. Download the mindquarry-webapplication-VERSION.war from http://releases.mindquarry.org/com/mindquarry/webapp/mindquarry-webapplication/VERSION/ (see below for the list of versions and links).

  4. Create a fresh new directory webapps.

  5. Copy the downloaded file mindquarry-webapplication-VERSION.war into webapps, rename it to mindquarry-webapplication-VERSION.zip.

  6. Extract mindquarry-webapplication-VERSION.zip in place.

  7. Then remove the file mindquarry-webapplication-VERSION.zip from webapps.

  8. Now download the new properties file mindquarry-webapplication-VERSION.properties from http://releases.mindquarry.org/com/mindquarry/webapp/mindquarry-webapplication/VERSION/ (see below for the list of versions and links).

  9. Add the new properties to your existing properties file -OR- copy your old settings into the new file and replace the existing one in etc/mindquarry-webapplication.properties. For a list of property changes in each release see below. This requires a bit of careful manual work - a simple Java tool called PropDiff can be helpful. Note that properties marked with important are needed for the server to startup and work properly, so make sure these have been set correctly.

  10. Start the new server.

  11. The log file logs/wrapper.log shows whether the start of the new version was successful.

Version1.1
Webapplication Binarymindquarry-webapplication-1.1.war
Webapplication Propertiesmindquarry-webapplication-1.1.properties
Property changes:(none, this list starts with 1.1)
Version1.1.1
Webapplication Binarymindquarry-webapplication-1.1.1.war
Webapplication Propertiesmindquarry-webapplication-1.1.1.properties
Property changes: 
mindquarry.jackrabbit.config(new, important) Set to this value for now: classpath:/com/mindquarry/jcr/jackrabbit/repository.xml
mindquarry.bytes.encoding(new, important) Regards a problem with user password encoding. Only to be set if you have data from previous installations (1.1 or lower). In those the system default encoding was used for encoding passwords in the JCR. If this changed (eg. having a different LANG environment variable or moving data from one system to the other), you could no longer login. In case you are upgrading from 1.1 put the "JVM OutputStream encoding" that is printed out by the Mindquarry server (>= 1.1.1) on startup as value, eg. on Macs it typically would be: mindquarry.bytes.encoding=MacRoman, on Windows mindquarry.bytes.encoding=Cp1252. If you move data from one system to another, find out the default encoding of the old server and set it to the new server. If this value is not set, then UTF-8 is used as the default independent of the system default encoding.
mindquarry.mail.server.user(new) Needed for password reset (and other mail features in the future). Set the user login for your mail server here (mail server address is configured via existing property mindquarry.mail.server)
mindquarry.mail.server.password(new) Needed for password reset (and other mail features in the future). Set the user login password for your mail server here (mail server address is configured via existing property mindquarry.mail.server)
Version1.1.2
Webapplication Binarymindquarry-webapplication-1.1.2.war
Webapplication Propertiesmindquarry-webapplication-1.1.2.properties
Property changes: 
mindquarry.mail.fromAddress(new) The From: address when sending password reset mails
Version1.2-beta
Webapplication Binarymindquarry-webapplication-1.2-beta.war
Webapplication Propertiesmindquarry-webapplication-1.2-beta.properties
Property changes: 
mindquarry.solr.login(removed) obsolete
mindquarry.i18n.path(new) Path for translations. Useful for translators working on a translation or when users want to add another language file without re-installing. Can point to a directory with the translation files (messages_LANG.xml and locales.xml). Standard value is resource://com/mindquarry/i18n
mail.mime.charset(new) must be set to UTF-8 (encoding for outgoing mails)
mindquarry.mail.pwd(new) Password of the mail user used when uploading mails from the mail server to Mindquarry. For more information see the section called “Configuring your Mail Server”.
mindquarry.mail.host(new) hostname of the mail server that receives mails for Mindquarry. The default value is {system-property:mindquarry.mail.host}, this means identical to mindquarry.mail.server. For more information see the section called “Configuring your Mail Server”.
mindquarry.mail.fromAddress(modified) The From: address when sending password reset mails. You can now simply use noreply@{system-property:mindquarry.mail.host} which references the other property mindquarry.mail.host, that typically is identical. But you are free to set what your server requires here.
mindquarry.logo(new, optional) Absolute path to a PNG file with max. 150px width and exactly 36px height that will be shown in the top-left. If in comments, the default will be the built-in Mindquarry logo

If you want to upgrade from our previous release (1.0-M1 or 1.1-beta) to 1.1, follow these steps. You don't have to install the XAMPP package again.

Note

The Windows installer will install the data inside the installation directory. If you run a new installation, this data will get overwritten (or it is simply not available if you install into a new directory). To avoid this, one has to backup the data directory before doing so. But as we needed to change the structure of our repository in 1.1, it is also needed to run a migration tool that will convert your data - before backing up the data and installing the new version.

  1. You will need to use our migration tool if you don't want to lose your data. Note that the migration script requires the old version of the server (1.0-M1 or 1.1-beta) running, so it needs to be applied before the update. How to use the migration tool:

    1. Stop the old server

    2. Make a backup of your data. Backup at least the directory that is specified under mindquarry.jcr.path in your mindquarry-webapplication.properties.

    3. Start the old server again. Make sure that nobody is using the server during the following migration process.

    4. Unzip the migration program and call the following command:

       migrate.bat

    5. Stop the old server. Should the migration tool fail, please do not continue. Restore your backup and visit the Mindquarry forum for help.

  2. Backup the data directory inside your installation directory to a different place outside the installation.

  3. Now download the windows installer 1.1.

  4. Run the installer - you will need to enter the same data as in the previous version (the existing file etc/mindquarry-webapplication.properties in your existing installation directory might help)

  5. Before starting the new server, copy back your data directory into the new installation directory.

  6. Start the new server.

  7. The log file logs/wrapper.log shows whether the start of the new version was successful.