Wiki source code of Add a Load Balancer
Last modified by Eleni Cojocariu on 2026/10/20 06:45
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Put Apache in front of the nodes of a [[cluster>>doc:documentation.xs.admin.clustering.architecture.WebHome]], so that visitors are spread over them and each visitor keeps reaching the node that holds their session. | ||
| 2 | |||
| 3 | 1. 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##.((( | ||
| 4 | {{code language="none"}} | ||
| 5 | jetty.sessionIdManager.workerName=node1 | ||
| 6 | {{/code}} | ||
| 7 | |||
| 8 | {{code language="xml"}} | ||
| 9 | <Engine name="Catalina" defaultHost="localhost" jvmRoute="node1"> | ||
| 10 | {{/code}} | ||
| 11 | |||
| 12 | [[Configure Tomcat>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]] covers the rest of that file. | ||
| 13 | ))) | ||
| 14 | 1. Enable the Apache modules the balancer is made of, if your distribution does not ship them enabled.((( | ||
| 15 | {{code language="none"}} | ||
| 16 | a2enmod proxy proxy_http proxy_balancer lbmethod_byrequests | ||
| 17 | {{/code}} | ||
| 18 | ))) | ||
| 19 | 1. 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>>doc:documentation.xs.admin.clustering.limitations.WebHome]] calls stickiness a requirement rather than a tuning choice.((( | ||
| 20 | {{code language="apacheconf"}} | ||
| 21 | <Proxy balancer://xwikicluster> | ||
| 22 | BalancerMember http://127.0.0.1:8080 route=node1 | ||
| 23 | BalancerMember http://127.0.0.1:8081 route=node2 | ||
| 24 | ProxySet stickysession=JSESSIONID | ||
| 25 | </Proxy> | ||
| 26 | |||
| 27 | ProxyRequests Off | ||
| 28 | ProxyPreserveHost On | ||
| 29 | ProxyPass /xwiki balancer://xwikicluster/xwiki | ||
| 30 | ProxyPassReverse /xwiki balancer://xwikicluster/xwiki | ||
| 31 | {{/code}} | ||
| 32 | |||
| 33 | The nodes also have to agree on their authentication keys, or each will reject the other's cookies whatever the balancer does: [[Authentication Parameters>>doc:documentation.xs.admin.authentication.parameters.WebHome]] has them. For a single XWiki behind Apache, with no balancing involved, follow [[Use a HTTP Reverse Proxy>>doc:documentation.xs.admin.installation.http-reverse-proxy.WebHome]] instead. | ||
| 34 | ))) | ||
| 35 | 1. 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.((( | ||
| 36 | {{code language="apacheconf"}} | ||
| 37 | LogLevel proxy_balancer:debug | ||
| 38 | {{/code}} | ||
| 39 | ))) | ||
| 40 | 1. 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.((( | ||
| 41 | {{code language="apacheconf"}} | ||
| 42 | <Location "/balancer-manager"> | ||
| 43 | SetHandler balancer-manager | ||
| 44 | Require ip 127.0.0.1 | ||
| 45 | </Location> | ||
| 46 | {{/code}} | ||
| 47 | ))) | ||
| 48 | 1. 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.((( | ||
| 49 | {{code language="none"}} | ||
| 50 | Set-Cookie: JSESSIONID=node01x5l7ovxo53gj1iwmaiw9lwilp25.node1; Path=/xwiki | ||
| 51 | {{/code}} | ||
| 52 | |||
| 53 | [[Verify a Cluster>>doc:documentation.xs.admin.clustering.verify.WebHome]] goes further and proves the nodes replicate, rather than merely answer. | ||
| 54 | ))) |
