Deploying with Tomcat

This topic shows how to deploy the VoiceXML Connector war file as a Java servlet on Tomcat.

Prerequisite software

You can deploy on any operating system that supports Tomcat10.

Note: For prerequisite versions, see the VoiceXML Connector release notes.

Required software Description
Speech Suite

Required for all deployments.

VoiceXML browser

Required. VoiceXML Connector is tested with the Nuance platform add-on and browsers from Nuance partners.

Tomcat Required.
Java Required.
Dialog service

Access required. Deploy in your cloud (self-hosted) or connect to a Nuance-hosted Dialog service.

The Dialog service must be accessible to VoiceXML Connector, and it requires access to a web server for fetching Mix dialog models. (The Connector does not use the ASR, TTS, or NLU services in the Dialog service. It uses the equivalent services from Speech Suite instead.)

Recommended. Include the optional CCSS service and configure a URN to the artifact server.

Note: When you create a Mix project, the versions of all dialog model components must be compatible with the your versions of the Dialog service, VoiceXML Connector, and Speech Suite. For details see Integrating with Speech Suite in the Nuance Mix documentation.

Recommended software

Recommended software Description
Redis server

Optional. Redis server (Remote DIctionary Server) for persistent data storage. See Redis configuration.

You can share the same data storage server with the Dialog service and VoiceXML Connector.

Log file monitoring

Choose between file-based logging with log4j (the default) or console-based logging with an EFK stack. To set, see Log file configuration.

Components of the EFK stack:

  • Elasticsearch-log storage.
  • Fluentd-log collector.
  • Kibana-web UI for viewing logs.

(Note: VoiceXML Connector logs diagnostic messages but not call events.)

Prometheus

Recommended. Use Prometheus to monitor system runtime performance, detect alerts and fatal alarms, and to collect push metrics.

Grafana

Recommended. Use Grafana to collect and analyze metrics.

Jaegar

Recommended. Use Jaegar for detailed tracing and troubleshooting.

Installation package contents and procedure

  1. Install the prerequisite and optional software (listed above) in any order.
  2. Download the product package from Nuance Network and extract it.
  3. From the War folder, extract vxmlConnector-x.y.z.tar.gz (where x.y.z is the version). Contents:
    Deployment packageContents

    Windows installations.

    vxmlconnector-x.y.z.zip

    war-deployment.bat—Deployment script

    soak-test.bat—Script to confirm correct deployment

    vxml-connector.war—VoiceXML Connector application

    Linux installations.

    vxmlconnector-x.y.z.tar.gz

    war-deployment.sh—Deployment script

    soak-test.sh—Script to confirm correct deployment

    vxml-connector.war—VoiceXML Connector application

    Customize the configuration with required and optional parameters in an application.yaml file to be loaded when the Connector starts. See Configuring Tomcat deployments.
  4. In the Tomcat Configuration Tool on Windows or directly in catalina.sh or catalina.bat, do the following:
    • Change the Java Classpath (CLASSPATH in catalina.sh or catalina.bat) to the Tomcat provided-lib. For example, C:\Program Files\Apache Software Foundation\Tomcat 10.1\lib\config\provided-lib\*
    • Set Java Options (JAVA_OPTS in catalina.sh or catalina.bat) to -DLOG_TYPE=FILE -DLOGFILE_PATH=C:\var\VXML-CONNECTOR\logs\internal -DLOGFILE_NAME=vxml-connector, where DLOGFILE_PATH is the path to the internal logs.
  5. Extract the deployment package for your operating system and run the deployment script.
  6. Provide the Tomcat path when prompted by the script. The script adds the war file to the Tomcat webapps folder.
  7. Provide the path for output log files when prompted by the script. Then provide a filename for the logs. For details, see Log file configuration.

    If you install multiple instances of VoiceXML Connector, use a different filename for each instance (so you can distinguish which instances write which logs). For example, vxml-connector-1, vxml-connector-2, and so on.

  8. The script restarts Tomcat and runs the soak test. Wait for confirmation of a successful installation. If there's a problem, see catalina.out in the Tomcat logs folder.

Updating third-party libraries

The VoiceXML Connector image has dynamic links to third-party libraries. You can update the following libraries at any time. For example, if a security flaw is detected in the current version.

  • com.io7m.xom:xom
  • com.google.code.findbugs:jsr305

Note: After an update, you must re-deploy the new image.

For Tomcat deployments, store the new library in a folder and add that location to CLASSPATH in your setenv file.

# replace <provided-lib-path> with the location of the new library
set CLASSPATH=c:\provided-lib-path\*

Next steps

For configuration details, see Configuring Tomcat deployments.

For instructions on running Mix dialog models from IVR applications, see Invoking VXML Connector from applications.