Install Application Server

The following instructions describe how to install and set up the Apache Tomcat application server for use by the Content Store.

On your engine-host(s), while logged in as escenic:

  1. Download the latest Tomcat package from http://tomcat.apache.org/. If you are installing on more than one machine and have created the shared folders described in Create Shared File System, then it is a good idea to download these packages to the /mnt/download folder you created. Otherwise, download them to some temporary location of your choice.

  2. Change user to root and unpack the Tomcat package to /opt:

    $ su
    # cd /opt
    # tar -zxvf /mnt/download/apache-tomcat-version-number.tar.gz

    where version-number is the version number of the package you have downloaded.

  3. Create a symbolic link from /opt/tomcat-engine1 to the Tomcat folder, so that it will be easier to upgrade to new versions when necessary, and change the owner of the Tomcat folder to escenic.

    # ln -s /opt/apache-tomcat-version-number /opt/tomcat-engine1
    # chown -R escenic:escenic /opt/apache-tomcat-version-number
  4. Open Tomcat's configuration file file (/opt/tomcat-engine1/conf/catalina.properties) for editing and add the following characters:

    ,${catalina.base}/escenic/lib/*.jar

    to the end of the common.loader property setting.

  5. Download a JDBC driver for the database system you are using. For MariaDB, the driver is called Connector/J and can be downloaded from https://downloads.mariadb.org/connector-java/.

  6. Change user back to escenic and install the driver by copying it to the /opt/tomcat-engine1/lib folder. If you downloaded the MySQL driver package to /mnt/download, then you can do this as follows:

    # su - escenic
    $ cd /mnt/download/
    $ unzip mysql-connector-java-version-number.zip
    $ cp mysql-connector-java-version-number/mysql-connector-java-version-number-bin.jar 
    /opt/tomcat-engine1/lib/
  7. Create the /opt/tomcat-engine1/escenic/lib folder you added to the common.loader path in step 4:

    $ mkdir -p /opt/tomcat-engine1/escenic/lib/
  8. Set up database pooling. For MariaDB, you do this by opening /opt/tomcat-engine1/conf/context.xml for editing and inserting the following resource definition as a child of the root Context element:

    <Resource
      name="jdbc/ECE_DS"
      auth="Container"
      type="javax.sql.DataSource"
      username="user"
      password="password"
      driverClassName="com.mysql.jdbc.Driver"
      maxTotal="200"
      maxIdle="10"
      maxWaitMillis="10000"
      url="jdbc:mysql://database-host/db-name?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=UTF-8"
    />

    Replace database-host, db-name, user and password in the above definitions with the names you have defined earlier (see Install Database).

    Note that the maxTotal and maxWaitMillis attribute names above are only correct if:

    If you are running Tomcat 7, then you will need to change maxTotal to maxActive and maxWaitMillis to maxWait. For general information about the differences between Tomcat 7 and Tomcat 8, see https://tomcat.apache.org/migration-8.html.

    If you are running a Tomcat 8 that has been set up to use Tomcat's own DBCP, then you will also need to change maxTotal to maxActive and maxWaitMillis to maxWait. For information about Tomcat's DBPC, see http://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.html#Introduction.

    The parameter settings shown above are provided only as recommended starting values. They may need to be adjusted to provide optimum performance.

  9. Set up indexing by inserting the following elements in /opt/tomcat-engine1/conf/context.xml as children of the root Context element:

    <Environment
        name="escenic/indexer-webservice"
        value="http://indexer-web-service-host:8080/indexer-webservice/web-service-name/"
        type="java.lang.String"
        override="false"/>
    
    <Environment
        name="escenic/index-update-uri"
        value="http://localhost:8983/solr/solr-core/update/"
        type="java.lang.String"
        override="false"/>
    
    <Environment
        name="escenic/solr-base-uri"
        value="http://localhost:8983/solr"
        type="java.lang.String"
        override="false"/>
    
    <Environment
        name="escenic/head-tail-storage-file"
        value="/var/lib/escenic/head-tail.index"
        type="java.lang.String"
        override="false"/>
    
    <Environment
        name="escenic/failing-documents-storage-file"
        value="/var/lib/escenic/failures.index"
        type="java.lang.String"
        override="false"/>

    where:

    • On an editorial-host, indexer-web-service-host is the host name or IP address of the editorial-host on which the Content Store's internal indexer web service is to run and web-service-name is index.

    • On a presentation-host, indexer-web-service-host is the host name or IP address of the presentation-host on which the Content Store's external indexer web service is to run and web-service-name is presentation-index.

    • The solr-core is usually either editorial or presentation.

    If you are creating a single-host installation, then you can use the host name localhost and the indexer web service name index.

    Make sure that your escenic/solr-base-uri setting in /opt/tomcat-engine1/conf/context.xml is as shown, and does not include a trailing slash (/). If it does, then search will not work.

  10. Open Tomcat's web.xml file (/opt/tomcat-engine1/conf/web.xml) for editing and insert links to the resources you have defined:

    <resource-ref>
      <description>Escenic link</description>
      <res-ref-name>jdbc/ECE_DS</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>
    

    These elements must be inserted as children of the root web-app element: otherwise, position is irrelevant.

  11. Open /opt/tomcat-engine1/conf/server.xml for editing. Somewhere in this file you will find a Connector element that configures connections on port 8080. Make sure that this element contains a URIEncoding attribute, and that it is set to UTF-8. For example:

    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               URIEncoding="UTF-8"/>

    This ensures that Content Store search functionality works for non-Latin characters.