Install a Tomcat server farm manually

To install a Tomcat server farm step by step, you create the database, write the configuration file, configure JMX, configure the runtime database, and the operations console and administration web applications, and declare users and roles.

To configure a farm of Tomcat servers:

1. Create the administrative services database.

2. Write the configuration file for the farm plug-in.

3. Configure JMX.

4. Configure the MobileFirst runtime database.

5. Install the administrative services application.

6. Install the operations console application.

7. Configure the MobileFirst runtime environments.

8. Declare the users and roles to manage the applications in the operations console.

1. Create the administrative services database.

   MobileFirst databases are shared among the application servers of a farm, which has two consequences:

   • We create this database only once, whatever the number of servers.

   • We cannot use the Derby database in such a topology because this database allows only a single connection at a time.

   For more information for each database, see the following documentation.

   • Set up the DB2 database manually for the MobileFirst Server administration

   • Set up the Oracle database manually for the MobileFirst Server administration

   • Set up the MySQL database manually for the MobileFirst Server administration

2. Write the configuration file for the farm plug-in.

   1. Create an XML file.

      Give it a meaningful name, for example TomcatFarm.xml.

      <?xml version="1.0" encoding="UTF-8"?>
      <Farm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FarmSchema.xsd">
        <TomcatNode ServerID="server id" Hostname="host name address" JMXPortNumber="port number"/>
         .....
      </Farm>

      Where:

      • server id is the unique identifier of the server

      • host name address is the host name of the Tomcat server

      • port number is the RMI port number of the Tomcat server

        The port number must be different for each server that is hosted on the same computer.

      There must be one <TomcatNode> element per server in the farm. For example:

      <?xml version="1.0" encoding="UTF-8"?>
      <Farm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FarmSchema.xsd">
        <TomcatNode ServerID="ServerOne" Hostname="MyHostName" JMXPortNumber="8686"/>
        <TomcatNode ServerID="ServerTwo" Hostname="MyHostName" JMXPortNumber="8687"/>
      </Farm>

      The complete syntax of the elements and attributes of this XML file and the underlying XML schema is documented in Define a server farm.

   2. Copy the configuration file to each computer where Tomcat is installed or on a shared file system that all the servers of the farm can access.

3. Configure JMX.

   We configure JMX for each Tomcat server.

   1. Make sure that the CATALINA_OPTS environment variable sets all these Java properties: First check that the number thaT you set forRMI_port number is not already used on the system.

      -Djava.rmi.server.hostname=localhost
      -Dcom.sun.management.jmxremote.port=RMI_port number -Dcom.sun.management.jmxremote.authenticate=false
      -Dcom.sun.management.jmxremote.ssl=false

   2. Optional: To be able to inspect the MBeans through the jconsole tool of the Java SDK, add the -Dcom.sun.management.jmxremote property.

      Add a setenv file in the Tomcat bin/ directory.

      • For UNIX environments: setenv.sh

        # =========================== setenv.sh ===========================
        # Allow to inspect the MBeans through jconsole
        CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote"
        # Configure JMX.
        CATALINA_OPTS="$CATALINA_OPTS -Djava.rmi.server.hostname=localhost"
        CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.port=RMI_port number"
        CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
        CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false"

      • For Windows environments: setenv.bat

        REM =========================== setenv.bat ===========================
        REM Allow to inspect the MBeans through jconsole
        set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote
        REM Configure JMX.
        set CATALINA_OPTS=%CATALINA_OPTS% -Djava.rmi.server.hostname=localhost
        set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.port=RMI_port number set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.authenticate=false
        set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.ssl=false

4. Configure the MobileFirst runtime database.

   We create this database only once, whatever the number of servers. For more information for each database, see the following documentation.

   • Set up the DB2 databases manually

   • Set up the Oracle databases manually

   • Set up the MySQL databases manually

5. Configure the administrative services application.

   1. Remove the Tomcat_install_dir/webapps/worklightadmin directory.

   2. Copy the administrative services file worklightadmin.war from MF_HOME/WorklightServer to Tomcat_install_dir/webapps/.

   3. Make a backup copy of the Tomcat_install_dir/conf/server.xml file.

   4. Edit the Tomcat_install_dir/conf/server.xml file.

   5. Add the following lines in the <Host> element:

      <Context docBase="worklightadmin" path="/worklightadmin">
        <Resource … />
        <Environment name="ibm.worklight.topology.platform" value="Tomcat" type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.topology.clustermode" value="Farm" type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.admin.serverid" value="<server ID>"
               type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.farm.type" value="File" type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.farm.definition.location" value="farm_plugin_xml_file_location>" 
               type="java.lang.String" override="false"/>
      </Context>

      Where

      • The attributes of the <Resource> element depend on the database. Use the following examples in this documentation:

        • For DB2 databases, see Configure Apache Tomcat for DB2 manually for MobileFirst Server administration.

        • For Oracle databases, see Configure Apache Tomcat for Oracle manually for MobileFirst Server administration.

        • For MySQL databases, see Configure Apache Tomcat for MySQL manually for MobileFirst Server administration.

      • farm_plugin_xml_file_location> is the absolute path to the configuration file that you wrote in step Write the configuration file for the farm plug-in..

      • server ID is a unique identifier for this server. This identifier must match the ServerID attribute of the <TomcatNode> element that you declared in the configuration file for this server.

      Attention: The name of the web application WAR file (worklightadmin.war) must match the context root (/worklightadmin), otherwise ill effects might occur.

6. Configure the operations console application.

   1. Remove the Tomcat_install_dir/webapps/worklightconsole directory.

   2. Copy the worklightconsole.war file to Tomcat_install_dir/webapps/.

   3. Make a backup copy of the Tomcat_install_dir/conf/server.xml file.

   4. Edit the Tomcat_install_dir/conf/server.xml file.

   5. Add the following lines into the <Host> element:

      <Context docBase="worklightconsole" path="/worklightconsole">
         <Environment name="ibm.worklight.admin.endpoint" value="*://*:*/worklightadmin" 
                    type="java.lang.String" override="false"/>
      </Context>

      Attention: The name of the web application WAR file (worklightadmin.war) must match the context root (/worklightadmin), otherwise ill effects might occur.

7. Configure the MobileFirst runtime environments.

   1. Make a backup copy of the Tomcat_install_dir/conf/server.xml file.

   2. Edit the Tomcat_install_dir/conf/server.xml file.

   3. Add the following lines in the <Host> element:

      <Context docBase="<runtime>" path="/<runtime>">
        <Loader className="org.apache.catalina.loader.VirtualWebappLoader" virtualClasspath="${catalina.base}/Worklight/<runtime>/worklight-jee-library.jar" searchVirtualFirst="true"/>
        <Environment name="ibm.worklight.topology.platform" value="Tomcat" type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.topology.clustermode" value="farm" type="java.lang.String" override="false"/>
        <Environment name="ibm.worklight.admin.serverid" value="server_id" type="java.lang.String" override="false"/>
        <Resource … name="jdbc/WorklightDS" … />
        <Resource … name="jdbc/WorklightReportsDS" … />

      Where

      • The attributes of the <Resource> element depend on the database. Use the examples provided in the following documentation.

        • For DB2 databases, see Configure Apache Tomcat for DB2 manually.

        • For Oracle databases, see Configure Apache Tomcat for Oracle manually.

        • For MySQL databases, see Configure Apache Tomcat for MySQL manually.

      • <runtime> is the name of the runtime environment, that is, the name of the MobileFirst WAR file without its extension.

      • <server ID> is a unique identifier for this server. This identifier must match the ServerID attribute of the <TomcatNode> element as declared in the configuration file for this server.

8. Declare the users and roles to manage the applications in the operations console .

   1. Make a backup copy of the Tomcat_install_dir>/conf/tomcat-users.xml file.

   2. Edit the Tomcat_install_dir/conf/tomcat-users.xml file.

   3. Add the following roles and users in the <tomcat-users> element.

      <!-- Define roles and users for the IBM MobileFirst Admin webapps. -->
        <role name="worklightadmin"/>
        <role name="worklightdeployer"/>
        <role name="worklightmonitor"/>
        <role name="worklightoperator"/>
        <user name="admin" password="admin" roles="worklightadmin"/>
        <user name="demo" password="demo" roles="worklightadmin"/>
        <user name="deployer" password="deployer" roles="worklightdeployer"/>
        <user name="monitor" password="monitor" roles="worklightmonitor"/>
        <user name="operator" password="operator" roles="worklightoperator"/>

Parent topic: Install a server farm