Wiki source code of Clustering
Last modified by Michael Hamann on 2026/02/26 10:47
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | XWiki provides an easy way to setup static clustered instances of XWiki based on network events distribution. | ||
| 6 | |||
| 7 | = Features = | ||
| 8 | |||
| 9 | * events synchronization between XWiki instances | ||
| 10 | * multiple clustering channels | ||
| 11 | * possibility to start/stop the clustering channel at runtime | ||
| 12 | |||
| 13 | = Setup = | ||
| 14 | |||
| 15 | == Use a remote Solr instance == | ||
| 16 | |||
| 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. | ||
| 18 | |||
| 19 | == Events distribution between cluster nodes == | ||
| 20 | |||
| 21 | === Enable event distribution === | ||
| 22 | |||
| 23 | To enable event distribution in an XWiki instance go to ##xwiki.properties## file and set the property ##observation.remote.enabled## to ##true##. | ||
| 24 | |||
| 25 | === Setup communication channels === | ||
| 26 | |||
| 27 | You will need a configuration file for each different cluster group you want to setup. Generally there is only one for a simple cluster. | ||
| 28 | |||
| 29 | For this you can either: | ||
| 30 | |||
| 31 | * 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 | ||
| 32 | * create your own configuration file | ||
| 33 | |||
| 34 | ==== Create your own configuration file ==== | ||
| 35 | |||
| 36 | For this go to the ##/WEB-INF/observation/remote/jgroups## folder and add one xml file. | ||
| 37 | |||
| 38 | See [[JGroups documentation>>http://www.jgroups.org/ug.html]] for more details on how to setup JGroups configuration files. | ||
| 39 | |||
| 40 | 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. | ||
| 41 | |||
| 42 | === Start communication channels === | ||
| 43 | |||
| 44 | The name of the xml file matches the identifier of the channel. | ||
| 45 | |||
| 46 | To indicate which channels to start when XWiki starts list them in the property ##observation.remote.channels## of the ##xwiki.properties## file. | ||
| 47 | |||
| 48 | === Choose network adaptor implementation to use === | ||
| 49 | |||
| 50 | 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. | ||
| 51 | |||
| 52 | == Attachments and Deleted Documents == | ||
| 53 | |||
| 54 | {{version since="17.10.0RC1"}} | ||
| 55 | [[Configure S3 as blob store>>documentation.extensions.admin.s3-blob-store.configure-s3.WebHome]] to ensure that attachments and deleted documents are available to all cluster nodes. | ||
| 56 | {{/version}} | ||
| 57 | |||
| 58 | For older XWiki versions or if you cannot use S3 as blob store for another reason, you need to set up a shared file system (e.g., NFS) as attachments and deleted documents located on the file system (located inside the [[Permanent Directory>>Documentation.AdminGuide.Configuration.WebHome#HPermanentDirectory]]) are not clustered. In order for all XWiki instance to access and display them properly in the UI, you need to share the ##store/file## directory using the shared file system. | ||
| 59 | |||
| 60 | 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). | ||
| 61 | |||
| 62 | = Limitations = | ||
| 63 | |||
| 64 | The following limitations currently exist when you use clustering: | ||
| 65 | |||
| 66 | * [[XWIKI-6235>>https://jira.xwiki.org/browse/XWIKI-6235]]: See [[Scheduler Plugin clustering>>extensions:Extension.Scheduler Plugin#HClustering]]. | ||
| 67 | * [[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. | ||
| 68 | |||
| 69 | {{version before="17.10.1"}} | ||
| 70 | * [[XWIKI-21548>>https://jira.xwiki.org/browse/XWIKI-21548]]: Realtime editing doesn't work on a cluster before XWiki 17.10.1. Each node will create a different realtime session, and the collaboration will be with the users that end up on the same cluster node. The current workaround is to [[disable the Realtime feature>>extensions:Extension.Realtime WYSIWYG Editor.WebHome#HEnabling2FDisabling]]. | ||
| 71 | {{/version}} | ||
| 72 | |||
| 73 | = Performances = | ||
| 74 | |||
| 75 | * See [[general performance page>>Documentation.AdminGuide.Performances]] for more ideas. | ||
| 76 | |||
| 77 | = More = | ||
| 78 | |||
| 79 | See the [[Remote Observation Module>>extensions:Extension.Observation Module Remote]] for more details of the event distribution features and extension capabilities. | ||
| 80 | |||
| 81 | 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. |
