Wiki source code of Clustering

Last modified by Ludovic Dubost on 2023/11/08

Hide last authors
Vincent Massol 8.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
Silvia Macovei 3.3 5 XWiki provides an easy way to setup clustered instances of XWiki based on network events distribution.
Thomas Mortagne 1.1 6
Silvia Macovei 3.3 7 = Features =
Thomas Mortagne 1.1 8
9 * events synchronization between XWiki instances
10 * multiple clustering channels
Manuel Smeria 4.5 11 * possibility to start/stop the clustering channel at runtime
Thomas Mortagne 1.1 12
Silvia Macovei 3.3 13 = Setup =
Thomas Mortagne 1.1 14
Thomas Mortagne 14.1 15 == Use a remote Solr instance ==
Thomas Mortagne 13.1 16
Vincent Massol 20.2 17 XWiki stores a lot of information in Solr cores (e.g. Events, Indexed content), so like with the database you will need to make sure that all cluster members use the [[same Solr instance remotely>>extensions:Extension.Solr Search API#HSetuparemoteSolrserver]] instead of each having its own embedded instance.
Thomas Mortagne 13.1 18
Silvia Macovei 3.3 19 == Enable event distribution ==
Thomas Mortagne 2.1 20
Silvia Macovei 3.3 21 To enable event distribution in an XWiki instance go to ##xwiki.properties## file and set the property ##observation.remote.enabled## to ##true##.
Thomas Mortagne 2.1 22
Silvia Macovei 3.3 23 == Setup communication channels ==
Thomas Mortagne 2.1 24
Thomas Mortagne 17.1 25 You will need a configuration file for each different cluster group you want to setup. Generally there is only one for a simple cluster.
Thomas Mortagne 2.1 26
Thomas Mortagne 17.1 27 For this you can either:
Thomas Mortagne 2.1 28
Thomas Mortagne 17.1 29 * use one of the files provided by jgroups ("tcp", "udp", etc. it's generally enough for most use cases and certainly a lot simpler) which can be customized through system properties
30 * create your own configuration file
31
Vincent Massol 18.1 32 === Create your own configuration file ===
Thomas Mortagne 17.1 33
34 For this go to the ##/WEB-INF/observation/remote/jgroups## folder and add one xml file.
35
Thomas Mortagne 5.1 36 See [[JGroups documentation>>http://www.jgroups.org/ug.html]] for more details on how to setup JGroups configuration files.
Thomas Mortagne 2.1 37
Vincent Massol 5.2 38 If you have IPv6 on your server, you are also advised to read [[this IPv6 article>>https://community.jboss.org/wiki/IPv6]]. Defining ##-Djava.net.preferIPv4Stack=true## when launching the JVM is probably your best bet in most cases. If your really want to use IPv6 for your channels, you should probably upgrade JGroup to version 2.10.0.GA and use a JVM 6 at least.
Denis Gervalle 4.1 39
Silvia Macovei 3.3 40 == Start communication channels ==
Thomas Mortagne 2.1 41
42 The name of the xml file matches the identifier of the channel.
43
Manuel Smeria 4.5 44 To indicate which channels to start when XWiki starts list them in the property ##observation.remote.channels## of the ##xwiki.properties## file.
Thomas Mortagne 2.1 45
Silvia Macovei 3.3 46 == Choose network adaptor implementation to use ==
Thomas Mortagne 2.1 47
Manuel Smeria 4.5 48 By default only JGroups implementation is provided, but it's possible to add more. See the [[Remote Observation Module>>extensions:Extension.Observation Module Remote#HAddcustomnetworkadaptor]] for more details.
Thomas Mortagne 2.1 49
Vincent Massol 18.1 50 == Shared filesystem ==
51
52 Attachments and deleted documents located on the file system (located inside the [[Permanent Directory>>Documentation.AdminGuide.Configuration.WebHome#HPermanentDirectory]]) are not clustered and in order for all XWiki instance to access and display them properly in the UI, you'll need to set up a shared filesystem (e.g. NFS) and share the ##store/file## directory.
53
54 Note that you must not share the whole Permanent Directory or this will lead to problems (such as causing file contentions when several instances try to read/write to some of them which have locks on).
55
Vincent Massol 8.3 56 = Limitations =
Vincent Massol 8.1 57
58 The following limitations currently exist when you use clustering:
59
Ludovic Dubost 24.1 60 * [[XWIKI-6235>>https://jira.xwiki.org/browse/XWIKI-6235]]: The Scheduler feature is not cluster-aware and thus each node of XWiki runs its own scheduler and thus the same scheduler jobs will execute on all nodes. The workaround is to disable the Scheduler plugin on all nodes except on one (i.e remove ##com.xpn.xwiki.plugin.scheduler.SchedulerPlugin## from the ##xwiki.plugins## configuration value in ##xwiki.cfg##). Note that this creates a [[SPOF>>https://en.wikipedia.org/wiki/Single_point_of_failure]] and if the node containing the active Scheduler is down, the scheduled jobs won't execute.
Vincent Massol 22.1 61 * [[XWIKI-14722>>https://jira.xwiki.org/browse/XWIKI-14722]] & [[XWIKI-1516>>https://jira.xwiki.org/browse/XWIKI-15164]]: Attachments and deleted documents located on the file system (located inside the [[Permanent Directory>>Documentation.AdminGuide.Configuration.WebHome#HPermanentDirectory]]) are currently not clustered. See above on setting up a shared filesystem to work around this.
Vincent Massol 18.1 62 * [[XWIKI-11441>>https://jira.xwiki.org/browse/XWIKI-11441]] If a node is down and Events happen, these Events won't be propagated to the node when it comes back up. For example, imagine you install an Extension on a node of the cluster while another node is down. When that node is restarted, the Extension won't be installed on it.
Vincent Massol 20.1 63 * [[XWIKI-15113>>https://jira.xwiki.org/browse/XWIKI-15113]]: Some potential performance issues when saving large documents, as the Annotation updates (updates events and updates the annotations that are impacted by a document content change, to update the selection and context to match the new document content) will run on all nodes in the cluster instead of just once.
Vincent Massol 21.1 64 * [[WEBSOCKET-7>>https://jira.xwiki.org/browse/WEBSOCKET-7]]: Realtime editing currently doesn't work on a cluster. Each node will create a different realtime session, and the collaboration will be with the users that end up on the same cluster node.
Vincent Massol 8.1 65
Thomas Mortagne 9.1 66 = Performances =
67
68 * You may want to [[configure SOLR to use an external SOLR instance>>xwiki:Documentation.AdminGuide.Performances.WebHome||anchor="HStandaloneSolr"]] instead of having each node maintain its own SOLR index (even though that would work fine but you'd be less performant since each node would do the same work)
Thomas Mortagne 11.1 69 * See [[general performance page>>Documentation.AdminGuide.Performances]] for more ideas.
Thomas Mortagne 9.1 70
Silvia Macovei 3.3 71 = More =
Thomas Mortagne 2.1 72
Vincent Massol 4.3 73 See the [[Remote Observation Module>>extensions:Extension.Observation Module Remote]] for more details of the event distribution features and extension capabilities.
Thomas Mortagne 2.1 74
Ecaterina Moraru (Valica) 7.1 75 Follow the [[test clustering tutorial>>Documentation.AdminGuide.Clustering.DistributedEventClusterSetup.WebHome]] for a complete tutorial on how to setup a simple cluster between two instances of XWiki on the same server.

Get Connected