Cluster Architecture
Explanation
An XWiki cluster is a set of XWiki instances serving the same wiki: they run on different servers, share one database server, and distribute their events to each other over the network, so that every node reflects what the others did. A load balancer in front of the nodes spreads the visitors between them.
Why the nodes have to talk to each other
Pointing two XWiki instances at one database is almost a cluster, but not quite. XWiki caches the documents it reads: an instance that saves a document invalidates its own cache, and the other instance goes on serving the copy it already has. Everything XWiki derives from documents and keeps in memory drifts apart the same way.
Inside a single instance, every change raises a local event and the listeners for that event update what they hold. Remote observation extends that across the network: each node sends its local events to the other members of its channel, and those re-emit them locally, so the listeners that invalidate caches, send notifications or index content also run on the nodes where nothing happened.
Event distribution is only the agreement layer. Everything a node stores outside the database has to be shared as well, and Shared Resources lists what to point where. Enable Event Distribution is the procedure that turns it on, and Limitations covers what a cluster still does not do for you.
Channels
Nodes exchange their events over a channel, a group of nodes that see each other's events. One channel is enough for a simple cluster; a node can join several when separate groups have to be kept in agreement independently of each other.
A channel starts when the node boots, but it can also be started and stopped while the wiki is running, which takes a node out of its group without restarting it. A node whose channel is stopped neither sends nor receives events, so what it holds in memory drifts from the rest of the cluster until the channel is back.
Network adaptors
The transport itself is a component, chosen per node by the observation.remote.networkadapter property of xwiki.properties, whose value is the hint of a network adaptor. XWiki ships a single one, jgroups, which is also the default, so a channel is in practice a JGroups channel described by a JGroups configuration file. Other adaptors can be written: the Remote Observation Module describes the component to implement in its "Add custom network adaptor" section.
FAQ
Why is it called a static cluster?
Because its members come from configuration: you install and configure each node yourself, and XWiki never adds or removes one in response to load.
Is one of the nodes the master?
No. Every node runs the same wiki and distributes its own events to the others, so none of them is in charge. The one task that does need a single node is scheduled jobs, which Limitations explains.
