Installing Roth

Notice: These instructions are for Tomcat. Theoretically Roth should work with JBoss and GlassFish as well, but that has not be tested.

Minimum Requirements

These instructions assume that the following are already installed.

• MySQL 5.7+/8+
• Java 11 (suggest OpenJDK 11)
• Tomcat 9

Required JARs

(not included in zip file; see lib_requirements.zip)

• MySQL (Download)
  • mysql-connector-java-...-bin.jar
• JSTL (Download)
  • taglibs-standard-spec-1.2.5.jar
  • taglibs-standard-impl-1.2.5.jar
• Mail (optional; only needed if using Roth's Email class) (Download)
  • javax.mail-1.6.2.jar
• String Manipulation (optional; only needed if using Roth's JsonUtil class)
  • commons-text-1.6.jar (Download)
  • commons-lang3-3.9.jar (Download)
• PDFBox (optional; only needed if using Roth's PDF wrapper classes) (Download)
  • pdfbox-2.0.15.jar
  • fontbox-2.0.15.jar
  • xmpbox-2.0.15.jar
• POI (optional; only needed if using Roth's Excel classes -- Still under development) (Download)
  • poi-3.17.jar
  • poi-ooxml-3.17.jar
  • poi-ooxml-schemas-3.17.jar
  • commons-codec-1.10.jar
  • commons-collections4-4.1.jar
  • commons-logging-1.2.jar
  • junit-4.12.jar
  • log4j-1.2.17.jar
  • xmlbeans-2.6.0.jar

Installation

Copy roth-lib.jar and all other needed JARs (from above list) to Tomcat's lib folder.
Copy Roth.war, RothDeveloper.war, and RothInstaller.war to Tomcat's webapps folder.

Create a MySQL user account (for the rest of these instructions, it is assumed that the username is 'rothusr' and the password is 'rothpwd' -- I would suggest choosing your own username and password), and run the following grant statements:

:::sql
CREATE DATABASE roth;
GRANT ALL PRIVILEGES ON roth.* TO 'rothusr'@'%';

(please note that for better security, you should change the above statement to restrict the allowed user connection to a specific host; for example 'localhost' if MySQL and Tomcat are on the same server)

Tomcat Configuration

server.xml

Within the Engine section make sure that your Realm looks like this:

:::xml
<Realm className="org.apache.catalina.realm.LockOutRealm">
  <Realm className="com.roth.realm.RothRealm"/>
</Realm>

Within the Host section, make sure that one of the following Valves is not commented out. Use the SingleSignOn valve for use in a lone tomcat node. Use the ClusterSingleSignOn valve for use in a cluster.

:::xml
<Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
     or 
<Valve className="org.apache.catalina.ha.authenticator.ClusterSingleSignOn"/>

context.xml

Add the roth resource:

:::xml
<Resource name="roth" type="javax.sql.DataSource" 
          auth="Container"
          driverClassName="com.mysql.jdbc.Driver" 
          url="jdbc:mysql://localhost:3306/roth" 
          username="rothusr" password="rothpwd" 
          maxWaitMillis="10000" maxIdle="30" maxTotal="100"/>

web.xml

Add the rothTemp environment variable:

:::xml
<env-entry> 
    <env-entry-name>rothTemp</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>${catalina.base}/temp/</env-entry-value> 
</env-entry>

Important: You may instead choose to add the resource to server.xml with a resource link in context.xml. The difference is that if the resource is defined in server.xml, then the same resource will be used by all contexts (applications) running in that Tomcat instance, and if the resource is defined in context.xml, then each context running in that Tomcat instance will have it's own resource. What this means is that if a resource limits to 25 connections, the server.xml method would use at most 25 connections, where the context.xml method would use up to 25 connections per context (5 contexts would result in up to 125 connections).

Start Tomcat

Now, start the Tomcat server and test by pointing your browser at http://localhost:8080/RothInstaller to get to the installation page. It should read "Non Installed". Click on the "Install Roth" button to create the database tables. After installing, you will be automatically redirected to the Roth home page.

Additional Information

If using RothDeveloper with Oracle, you will need to add this startup argument to Tomcat:

:::script
-Doracle.jdbc.useFetchSizeWithLongColumn=true

Read here for more information, caveats, and other ways to implement this feature: https://docs.oracle.com/cd/E11882_01/appdev.112/e13995/oracle/jdbc/OracleDriver.html