Concerto tutorial

In this page we provide a tutorial for compiling, installing and deploying XWiki Concerto. This tutorial will cover all the steps and will setup two replicated wikis that can be used to test XWiki Concerto capabilities.

Compilation

In order to compile XWiki Concerto you will need to install Maven 2.1.0 M1 or higher (please refer to the Maven hompage for further information)

First of all you have to get XWiki Concerto sources from the public SVN repository:

$ svn co http://svn.xwiki.org/svnroot/xwiki/contrib/sandbox/concerto/

Then configure your Maven settings as described on the XWiki building page.

Change the current directory to concerto and do a

mvn -Dmaven.test.skip=true clean install

The parameter -Dmaven.test.skip will tell Maven to skip all tests, speeding up the compilation process.

You may need to install JLibDiff to your local repository.

You can do so by issuing the following Maven command:

mvn install:install-file -Dfile=./concerto-xwoot/xwootApp/src/main/resources/jlibdiff.jar -DgroupId=fr.loria.ecoo -DartifactId=JLibDiff -Dversion=2.0 -Dpackaging=jar

The building process should last about 5-6 minutes(with tests skipped). If you choose not to skip tests, you should take a break because it could last more that 20 minutes. Once the build is done you will have an installer ready to launch in your local Maven repository:

$HOME/.m2/repository/org/xwiki/concerto/xwiki-concerto-installer/1.0-SNAPSHOT/xwiki-concerto-installer-1.0-SNAPSHOT-standard.jar

The same installer is also available where you have checked out the sources at the following path:

./concerto-installer/target/xwiki-concerto-installer-1.0-SNAPSHOT-standard.jar

Installation

Run the previously built installer using the command:

java -jar xwiki-concerto-installer-1.0-SNAPSHOT-standard.jar

The installation is very straightforward. You just have to specify the target directory where to install XWiki Concerto and accept the provided defaults by always clicking next.

Step 1: Welcome screen.

Step 2: Overview screen.

Step 3: License Agreement screen. You have to accept the license agreement in order to continue.

Step 4: Installation path screen. Select a directory where to install XWiki Concerto.

Step 5: Installation progress screen.

Step 6: Installation complete screen.

In order to have a test setup, repeat the previous steps another time and install another XWiki Concerto in another location.

At the end you will have two directories, let's call them xwc1 and xwc2, on your disk. We will use these installations in order to setup two replicated wikis to play with.

NB: if you're installing XWiki Concerto on a server without any graphical display, you may run an automated installation using the attached XML configuration file {attachment:install.xml} by running the following command after having customized the installation path in the attached XML file:

java -jar xwiki-concerto-installer-1.0-SNAPSHOT-standard.jar install.xml

Configuring the installations

First on all you have to launch the two XWiki Concertos by using the start_xwiki.sh command. You must specify the port number for the second instance otherwise a conflict would happen:

.../xwc1$ ./start_xwiki.sh
.../xwc2$ ./start_xwiki.sh 8181

Now you have two instances running. You can check it by opening a browser at the following addresses: http://localhost:8080/xwootApp and http://localhost:8181/xwootApp

Configuring the first instance on http://localhost:8080/xwootApp

1. The first screen you will see it's the "Bootstrap". You can leave all the parameters as they are (maybe you might want to change the Data serialization folder to a more suitable directory)
2. Then you will have the "Network bootstrap" screen. Since no networks exist, you can click on the "Create" button in order to create a new network
3. The "Group bootstrap" will appear on your screen. Since we are creating a new group, here you must configure the "Create group" part. Pick up a group name and fill the respective fields. If you want the group to be private, click on the "This is a private group" and fill the password fields with this the password you have chosen. Once you are done click on the "Create" button.
4. At this point you must compute a state for your XWiki. Click on the "Compute new state" and wait that the process is over (it can take several minutes)
5. Once the state is computed you will see the page with the (empty) neighbors list. XWiki Concerto is up and running and is waiting for discovering/accepting other peers for replicating content.

Configuring the second instance on http://localhost:8181/xwootApp

1. In the "Bootstrap" screen make sure that you change the port number from 8080 to 8181 in order to correctly associate the replication engine to the right XWiki. You have also to specify a different directory from the one you specified earlier where storing data files. Finally pick up a different
2. In the "Network bootstrap" screen, this time, you have to configure what are the Rendez-vous and Relay peers that will provide seeds for the P2P network. Use for both the "RDV Seeds" and "Relay Seeds" the following address: "tcp://localhost:9701". Make sure that you selected the "Use a custom network" radio button. You must also change the port numbers for in the advanced settings, otherwise they will clash with the ones of the first instance. Once you are done, click on the "Join" button.
3. This time you will have to join an existing group. Click on the "Refresh List" and you will see the group you created in the dropdown combo box. Type the password that you defined for this group and then click the "Join" button.
4. In the "State management" page, click "Ask state from group" in order to import the initial state and wait for the synchronization to terminate (it can take several minutes)
5. Once the process is done you will see the page with the neighbors list and the name of the first instance listed in the panel. If you go to the http://localhost:8080/xwootApp/synchronize.do address, you will see the second instance's name listed in the neighbors list as well.

Testing the replication

1. Go to the first instance WebHome and login as Administrator (login:Admin, password:admin). Change the page and save it.
2. Automatic replication happens every 60 seconds, so changes should be propagated in less than a minute.
3. If you open the Main.WebHome page (http://localhost:8181/xwiki/bin/view/Main/) on the second instance you will see the synchronized content.