I'm new here

Loadbalancing Firstspirit WebApps on multiple Tomcat Servers

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:

<Proxy balancer://fsajp>

  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

  ProxySet stickysession=JSESSIONID

  ProxySet lbmethod=byrequests

  ProxySet timeout=30

  Order Allow,Deny

  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

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:

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:



Dear Holger Isenberg,

any reason why the NFS approach is handled as DEPRECATED?

The reason for not describing any more the approach with distributing the folder firstspirit5/web over NFS to each Tomcat instance, is the complicated and error-prone configuration of the required local symlinks for the folders "preview_cache".

With FirstSpirit 5.0 and newer, much more project specific modules are used which required to create a project specific WebApp for each project, i.e. a copy of the fs5preview WebApp and the fs5webedit WebApp with name fs5webedit_PROJECTID and fs5preview_PROJECTID. For each WebApp folder a symlink pointing to a local "preview_cache" folder must be created and must be created again after each FirstSpirit update.

Technically, the method via NFS can still be used with FirstSpirit 5.0 and 5.1, but we don't recommend it any more as the approach via the Tomcat Manager as described above replaces it.

If Tomcat Manager cannot be used because of security concerns, a Webserver of type "Generic" instead of "Tomcat" can be configured via the FirstSpirit Server Manager. The type "Generic" requires 3 Beanshell scripts which deploy the WebApp.jar file to each of the WebApp server instances, or uninstall it or check its status.