Wiki source code of Cluster Architecture
Last modified by Eleni Cojocariu on 2026/10/20 06:45
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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>>doc:documentation.xs.admin.clustering.load-balancer.WebHome]] in front of the nodes spreads the visitors between them. | ||
| 2 | |||
| 3 | == Why the nodes have to talk to each other == | ||
| 4 | |||
| 5 | 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. | ||
| 6 | |||
| 7 | 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. | ||
| 8 | |||
| 9 | {{plantuml}} | ||
| 10 | @startuml | ||
| 11 | !theme bluegray | ||
| 12 | skinparam nodesep 30 | ||
| 13 | skinparam ranksep 40 | ||
| 14 | |||
| 15 | node "Load balancer" as LB | ||
| 16 | |||
| 17 | package "Cluster" { | ||
| 18 | node "XWiki node 1" as N1 | ||
| 19 | node "XWiki node 2" as N2 | ||
| 20 | } | ||
| 21 | |||
| 22 | package "Shared by every node" as SHARED { | ||
| 23 | database "Database server" as DB | ||
| 24 | node "Solr server" as SOLR | ||
| 25 | folder "Attachment storage" as FS | ||
| 26 | } | ||
| 27 | |||
| 28 | LB --> N1 | ||
| 29 | LB --> N2 | ||
| 30 | N1 <-[norank]-> N2 : local events,\nre-emitted on the other node | ||
| 31 | N1 --> SHARED | ||
| 32 | N2 --> SHARED | ||
| 33 | @enduml | ||
| 34 | {{/plantuml}} | ||
| 35 | |||
| 36 | Event distribution is only the agreement layer. Everything a node stores outside the database has to be shared as well, and [[Shared Resources>>doc:documentation.xs.admin.clustering.shared-resources.WebHome]] lists what to point where. [[Enable Event Distribution>>doc:documentation.xs.admin.clustering.enable-event-distribution.WebHome]] is the procedure that turns it on, and [[Limitations>>doc:documentation.xs.admin.clustering.limitations.WebHome]] covers what a cluster still does not do for you. | ||
| 37 | |||
| 38 | == Channels == | ||
| 39 | |||
| 40 | 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. | ||
| 41 | |||
| 42 | 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. | ||
| 43 | |||
| 44 | == Network adaptors == | ||
| 45 | |||
| 46 | 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>>doc:extensions:Extension.Observation Module Remote]] describes the component to implement in its "Add custom network adaptor" section. |
