Tutorial

Run two XWiki instances on one machine, sharing a single database and exchanging their events, to see a cluster work from end to end.

1. Install the Standalone (Demo) Distribution twice, in two directories of your own choosing. Everything below is done in both of them.

   ~/xwiki-node1
   ~/xwiki-node2

2. Point both installations at one MySQL database instead of the HSQLDB each of them ships with, since a cluster is first of all a set of nodes sharing their content. In webapps/xwiki/WEB-INF/hibernate.cfg.xml, comment out the HSQLDB block that is active and uncomment the MySQL one that follows it, then adjust the database name, user and password to the ones you created by following Configure MySQL.

   <property name="hibernate.connection.url">jdbc:mysql://localhost/xwiki?useSSL=false</property>
   <property name="hibernate.connection.username">xwiki</property>
   <property name="hibernate.connection.password">xwiki</property>
   <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>

3. Copy the MySQL driver jar into the webapps/xwiki/WEB-INF/lib directory of both installations. The distribution ships the HSQLDB driver only, so without this step neither node starts.

   webapps/xwiki/WEB-INF/lib/hsqldb-*.jar
   webapps/xwiki/WEB-INF/lib/mysql-connector-j-*.jar

4. Enable event distribution in webapps/xwiki/WEB-INF/xwiki.properties, on both nodes, giving the second one node2 as identifier. This tutorial takes the udp channel, which needs no further configuration on a single machine; Enable Event Distribution covers tcp and channel files of your own.

   observation.remote.enabled = true
   observation.remote.channels = udp
   observation.remote.id = node1

5. Start each node on its own ports. The first one needs no argument, since 8080 and 8079 are the defaults; the second takes both a HTTP port and a stop port, the latter being the port stop_xwiki.sh talks to, so that stopping one node never touches the other.

   cd ~/xwiki-node1 && ./start_xwiki.sh
   cd ~/xwiki-node2 && ./start_xwiki.sh -p 8081 -sp 8078

6. If the two nodes do not find each other, force the interface JGroups binds to, passing it through the environment variable the start script reads for JVM options and keeping its memory setting.

   XWIKI_OPTS="-Xmx1024m -Djgroups.bind_addr=127.0.0.1" ./start_xwiki.sh

7. Edit a page on the first node, then load that same page on the second: your edit is already there, with no restart. That is the whole point of the exercise, and Verify a Cluster shows how to read which node answered and that both are members of the channel.

   http://localhost:8080/xwiki/bin/view/Sandbox/
   http://localhost:8081/xwiki/bin/view/Sandbox/

   To put the two nodes behind a single address, continue with Add a Load Balancer, whose example balances exactly these two ports.

Related

• Clustering
• Limitations