Deploying the archiver appliance

Create individual Tomcat containers for each web app

The mgmt.war file contains a script deployMultipleTomcats.py in the install folder that will use the information in the appliances.xml file and the identity of this appliance to generate individual Tomcat containers from a single Tomcat install (identified by the environment variable TOMCAT_HOME). To run this script, set the following environment variables

TOMCAT_HOME - This is the Tomcat installation that you prepared in the previous steps.
ARCHAPPL_APPLIANCES - This points to the appliances.xml that you created in the previous steps.
ARCHAPPL_MYIDENTITY - This is the identity of the current appliance, for example appliance0. If this is not set, the system will default to using the machine’s hostname as determined by making a call to InetAddress.getLocalHost().getCanonicalHostName(). However, this makes ARCHAPPL_MYIDENTITY a physical entity and not a logical entity; so, if you can, use a logical name for this entry. Note, this must match the identity element of this appliance as it is defined in the appliances.xml.

and then run the deployMultipleTomcats.py script passing in one argument that identifies the parent folder of the individual Tomcat containers.

$ export TOMCAT_HOME=/arch/single_machine_install/tomcats/apache-tomcat-11.0.12
$ export ARCHAPPL_APPLIANCES=/arch/single_machine_install/sample_appliances.xml
$ export ARCHAPPL_MYIDENTITY=appliance0
$ ./install_scripts/deployMultipleTomcats.py /arch/single_machine_install/tomcats
Using
    tomcat installation at /arch/single_machine_install/tomcats/apache-tomcat-11.0.12
    to generate deployments for appliance appliance0
    using configuration info from /arch/single_machine_install/sample_appliances.xml
    into folder /arch/single_machine_install/tomcats
The start/stop port is the standard Tomcat start/stop port. Changing it to something else random - 16000
The stop/start ports for the new instance will being at  16001
Generating tomcat folder for  mgmt  in location /arch/single_machine_install/tomcats/mgmt
Commenting connector with protocol  AJP/1.3 . If you do need this connector, you should un-comment this.
Generating tomcat folder for  engine  in location /arch/single_machine_install/tomcats/engine
Commenting connector with protocol  AJP/1.3 . If you do need this connector, you should un-comment this.
Generating tomcat folder for  etl  in location /arch/single_machine_install/tomcats/etl
Commenting connector with protocol  AJP/1.3 . If you do need this connector, you should un-comment this.
Generating tomcat folder for  retrieval  in location /arch/single_machine_install/tomcats/retrieval
Commenting connector with protocol  AJP/1.3 . If you do need this connector, you should un-comment this.

Deploy the WAR files onto their respective containers

Deploying/upgrading a WAR file in a Tomcat container is very easy. Each container has a webapps folder; all we have to do is to copy the (newer) WAR into this folder and Tomcat will expand the WAR file and deploy it on startup. The deployment/upgrade steps are

Stop all four Tomcat containers.
Remove the older WAR file and expanded WAR file from the webapps folder (if present).
Copy the newer WAR file into the webapps folder.
Optionally expand the WAR file after copying it over to the webapps folder
- This lets you replace individual files in the expanded WAR file (for example, images, policies etc) giving you one more way to do site specific deployments.
Start all four Tomcat containers.

If DEPLOY_DIR is the parent folder of the individual Tomcat containers and WARSRC_DIR is the location where the WAR files are present, then the deploy steps (steps 2 and 3 in the list above) look something like

pushd ${DEPLOY_DIR}/mgmt/webapps && rm -rf mgmt*; cp ${WARSRC_DIR}/mgmt.war .; mkdir mgmt; cd mgmt; jar xf ../mgmt.war; popd;
pushd ${DEPLOY_DIR}/engine/webapps && rm -rf engine*; cp ${WARSRC_DIR}/engine.war .; mkdir engine; cd engine; jar xf ../engine.war; popd;
pushd ${DEPLOY_DIR}/etl/webapps && rm -rf etl*; cp ${WARSRC_DIR}/etl.war .; mkdir etl; cd etl; jar xf ../etl.war; popd;
pushd ${DEPLOY_DIR}/retrieval/webapps && rm -rf retrieval*; cp ${WARSRC_DIR}/retrieval.war .; mkdir retrieval; cd retrieval; jar xf ../retrieval.war; popd;

It is possible to deploy the 4 WAR files on other servlet containers or to use other industry standard provisioning software. The details here are guidelines for Tomcat. If you generate scripts for industry standard provisioning software and are willing to share them, please add them to the repository and contact the collaboration.

Stopping and starting the individual Tomcats

Running multiple Tomcats on a single machine using the same install requires two environment variables

CATALINA_HOME - This is the install folder for Tomcat that is common to all Tomcat instances; in our case this is $TOMCAT_HOME
CATALINA_BASE - This is the deploy folder for Tomcat that is specific to each Tomcat instance; in our case this is
- ${DEPLOY_DIR}/mgmt
- ${DEPLOY_DIR}/etl
- ${DEPLOY_DIR}/engine
- ${DEPLOY_DIR}/retrieval

If you are using Apache Commons Daemon, then two bash functions for stopping and starting a Tomcat instance look something like

function startTomcatAtLocation() {
    if [ -z "$1" ]; then echo "startTomcatAtLocation called without any arguments"; exit 1; fi
    export CATALINA_HOME=${TOMCAT_HOME}
    export CATALINA_BASE=$1
    echo "Starting tomcat at location ${CATALINA_BASE}"
    pushd ${CATALINA_BASE}/logs
    ${CATALINA_HOME}/bin/jsvc \
        -server \
        -cp ${CATALINA_HOME}/bin/bootstrap.jar:${CATALINA_HOME}/bin/tomcat-juli.jar \
        ${JAVA_OPTS} \
        -Dcatalina.base=${CATALINA_BASE} \
        -Dcatalina.home=${CATALINA_HOME} \
        -cwd ${CATALINA_BASE}/logs \
        -outfile ${CATALINA_BASE}/logs/catalina.out \
        -errfile ${CATALINA_BASE}/logs/catalina.err \
        -pidfile ${CATALINA_BASE}/pid \
        org.apache.catalina.startup.Bootstrap start
        popd
}

function stopTomcatAtLocation() {
    if [ -z "$1" ]; then echo "stopTomcatAtLocation called without any arguments"; exit 1; fi
    export CATALINA_HOME=${TOMCAT_HOME}
    export CATALINA_BASE=$1
    echo "Stopping tomcat at location ${CATALINA_BASE}"
    pushd ${CATALINA_BASE}/logs
    ${CATALINA_HOME}/bin/jsvc \
        -server \
        -cp ${CATALINA_HOME}/bin/bootstrap.jar:${CATALINA_HOME}/bin/tomcat-juli.jar \
        ${JAVA_OPTS} \
        -Dcatalina.base=${CATALINA_BASE} \
        -Dcatalina.home=${CATALINA_HOME} \
        -cwd ${CATALINA_BASE}/logs \
        -outfile ${CATALINA_BASE}/logs/catalina.out \
        -errfile ${CATALINA_BASE}/logs/catalina.err \
        -pidfile ${CATALINA_BASE}/pid \
        -stop \
        org.apache.catalina.startup.Bootstrap
        popd
}

and you’d invoke these using something like

stopTomcatAtLocation ${DEPLOY_DIR}/engine
stopTomcatAtLocation ${DEPLOY_DIR}/retrieval
stopTomcatAtLocation ${DEPLOY_DIR}/etl
stopTomcatAtLocation ${DEPLOY_DIR}/mgmt

and

startTomcatAtLocation ${DEPLOY_DIR}/mgmt
startTomcatAtLocation ${DEPLOY_DIR}/engine
startTomcatAtLocation ${DEPLOY_DIR}/etl
startTomcatAtLocation ${DEPLOY_DIR}/retrieval

Remember to set all the appropriate environment variables:

JAVA_HOME
TOMCAT_HOME
ARCHAPPL_APPLIANCES
ARCHAPPL_MYIDENTITY
ARCHAPPL_SHORT_TERM_FOLDER or equivalent
ARCHAPPL_MEDIUM_TERM_FOLDER or equivalent
ARCHAPPL_LONG_TERM_FOLDER or equivalent
JAVA_OPTS - This is the environment variable typically used by Tomcat to pass arguments to the VM. You can pass in appropriate arguments like so
```
export JAVA_OPTS="-XX:+UseG1GC -Xmx4G -Xms4G -ea"
```
LD_LIBRARY_PATH - If you are using JCA, please make sure your LD_LIBRARY_PATH includes the paths to the JCA and EPICS base .so’s.

A sample startup script using these elements is available here. Please modify to suit your installation.