Loadbalancing Firstspirit WebApps
on multiple Tomcat Servers
This addendum replaces:
PDF: FirstSpirit Manual for Administrators
Chapters: 4.5.5 External servlet engine and load balancing on multiple servlet engines
This Chapter describes the load balancing configuration on two Apache Tomcat instances, that are installed on hosts called tomcathost1 and tomcathost2. Instead of the now deprecated method with distributing the WebApp files via NFS to each Tomcat instance, this method uses the Tomcat Manager web service which is supported since FirstSpirit 5.0.
Apache httpd with mod_proxy_balancer in version 2.2 is used as the load balancer.
Other http load balancers and servlet engines or application servers can be used as well; in this case, however, session affinity based on the cookie name containing the session ID information must be enabled. Tomcat uses the cookie name JSESSIONID for the session ID.
This configuration provides load balancing only and does not increase fail-safe performance. A session replication or failover between the servlet engines does not occur and is not supported by FirstSpirit 5.0 or 5.1.
Configure the HTTP server and instances of the servlet engines first, as described in Chapters 4.5.2 (Apache HTTP Server with the Tomcat servlet engine) and 4.5.4 (Tomcat servlet engine on a dedicated host).
Next, in the Apache httpd virtual server configuration modify the section "<Proxy balancer" by adding all Tomcat instances as BalancerMember and define the session affinity with the cookie value JSESSIONID:
BalancerMember ajp://tomcathost1:8009 loadfactor=100 route=node1 retry=10 connectiontimeout=10 ping=5 ttl=1800 timeout=1200
BalancerMember ajp://tomcathost2:8009 loadfactor=100 route=node2 retry=10 connectiontimeout=10 ping=5 ttl=1800 timeout=1200
Allow from all
Shut down the FirstSpirit server and add the following line to /opt/firstspirit5/conf/fs-server.conf with the hostname or IP address of the FirstSpirit server itself so that this information can be used as the target address for the TCP connection (FirstSpirit SOCKET) from the WebApps to the FirstSpirit backend system:
Start the FirstSpirit server again.
Shut down each Tomcat instance and modify file tomcat/conf/server.xml at the following line from
<Engine name="Catalina" defaultHost="localhost">
<Engine name="Catalina" defaultHost="localhost" jvmRoute="nodeX">
and replace "nodeX" with the respective servlet engine route identifier entered for each BalancerMember, i.e. node1, node2.
Note, that the Tomcat Manager WebApp is required for this configuration architecture. The Tomcat Manager is usually embedded in the Tomcat Core package. For Tomcat since 6.0.30 and Tomcat 7 a technical user with role manager-script must be enabled in tomcat/conf/tomcat-users.xml. The role manager-gui is not required for FirstSpirit, but it is useful for manual configuration and status check of the Tomcat server. On older Tomcat 6 version before 6.0.30, the role manager-gui has to be used instead of manager-script. On all Tomcat instances the same username and password must be set in tomcat-users.xml.
Start all Tomcat instances again.
Start the FirstSpirit ServerManager (AdminClient) and open the section Server Properties -> WebServers -> Tomcat. The configuration property Tomcat Manager URL must be set to the following entry, i.e. the comma separated list of the Tomcat-Managers URLs of all instances:
Tomcat 6: http://tomcathost1:8080/manager,http://tomcathost2:8080/manager
Tomcat 7: http://tomcathost1:8080/manager/text,http://tomcathost2:8080/manager/text
Now in the ServerManager, section Server Properties -> Web Applications, install the FirstSpirit WebApps fs5root, fs5preview, fs5webedit and fs5webmon and enable them. While installing and enabling each WebApp, check for error messages in firstspirit5/log/fs-server.log.
Now, FirstSpirit can be used via the external load balancer URL, for instance http://fs5.yourdomain.net.
Via the Balancer Manager Web-Interface, the status of each Tomcat instance can be checked and if the connection from the load balancer is available: http://fs5.yourdomain.net/balancer-manager/.
The logfile of each WebApp can be read on the FirstSpirit server filesystem as all information is transferred via the TCP channel. Read the following chapter for more information: 4.6.2 Logging for FirstSpirit web applications.
This method of load balancing for FirstSpirit allows the scaling for usage scenarios with hundreds of concurrent editors. Additional servlet engines instances can even be added seamlessly during normal system operation as only a line with BalancerMember in httpd.conf needs to be added and a Tomcat Manager URL has to be set within the ServerManager and both changes do not require restarting any service. Though removing a servlet engine instance break the user sessions operating via this instance and those users need to log into FirstSpirit again.
If increasing numbers of sessions are observed for each http request without new users connecting, cookie management within the AppServer or other frontend infrastructure components like Web Application Firewalls might be the cause. FirstSpirit is using multiple cookies with same name but different paths, which are following the http standards. Some Web Application Firewalls map the FirstSpirit cookie for path "/" to other paths like "/fs5webedit", too, which then creates problems. As solution for FirstSpirit 5.2 and newer, add the following line to firstspirit5/conf/fs-server.conf which lets the FirstSpirit WebApp override the AppServers default cookie name for the WebApp with context path "/" and add the cookie name FSSESSIONID to your load balancer in addition to JSESSIONID: