Add a Load Balancer
Last modified by Eleni Cojocariu on 2026/10/20 06:45
Steps
Put Apache in front of the nodes of a cluster, so that visitors are spread over them and each visitor keeps reaching the node that holds their session.
- Name each node for its servlet container, because that name is what ends up in the session cookie and lets Apache send a visitor back to the same node. In the standalone distribution, add the property to a file of the start.d directory; under Tomcat, set jvmRoute on the Engine element of conf/server.xml. A node that is given no name answers node0.
jetty.sessionIdManager.workerName=node1<Engine name="Catalina" defaultHost="localhost" jvmRoute="node1">Configure Tomcat covers the rest of that file.
- Enable the Apache modules the balancer is made of, if your distribution does not ship them enabled.
a2enmod proxy proxy_http proxy_balancer lbmethod_byrequests - Declare the nodes as a balancer, and send the wiki to it. The stickysession setting is the whole point: Apache reads the route at the end of the JSESSIONID cookie and routes the request to the member whose route matches, for as long as the session lasts. Sessions live in the node that created them, which is why Limitations calls stickiness a requirement rather than a tuning choice.
<Proxy balancer://xwikicluster> BalancerMember http://127.0.0.1:8080 route=node1 BalancerMember http://127.0.0.1:8081 route=node2 ProxySet stickysession=JSESSIONID </Proxy> ProxyRequests Off ProxyPreserveHost On ProxyPass /xwiki balancer://xwikicluster/xwiki ProxyPassReverse /xwiki balancer://xwikicluster/xwikiThe nodes also have to agree on their authentication keys, or each will reject the other's cookies whatever the balancer does: Authentication Parameters has them. For a single XWiki behind Apache, with no balancing involved, follow Use a HTTP Reverse Proxy instead.
- Raise Apache's log level for the balancer while you are setting it up: it then writes the member it chose for each request into the error log.
LogLevel proxy_balancer:debug - Add the balancer manager if you want to see the nodes rather than read logs. It reports which members are up and how the requests are spread, and it can put a member offline, which is how a node is drained before being stopped. Reach it at the /balancer-manager path of the server, and keep it closed to everyone else.
<Location "/balancer-manager"> SetHandler balancer-manager Require ip 127.0.0.1 </Location> - Reload Apache and open the wiki. Every response now carries the route of the node that answered at the end of the session cookie, and it stays the same for the rest of the session, while a visitor arriving with no session may be sent to either node.
Set-Cookie: JSESSIONID=node01x5l7ovxo53gj1iwmaiw9lwilp25.node1; Path=/xwikiVerify a Cluster goes further and proves the nodes replicate, rather than merely answer.
