Posted Nov 11 by Edmund Clayton.
Updated Jul 03.

Learn how to install the OpenText AppWorks Gateway version 16.0.1 and upgrade previous versions of the Gateway.

Last activity Jul 03 by Edmund Clayton.
1247 views. 0 comments.

Chapter 1 – Installing and Upgrading the OpenText AppWorks Gateway

The AppWorks Gateway is a simple Apache Tomcat application, which requires JDK 1.8.x and Apache Tomcat 8.0.x. It also needs to connect to a production database such as Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, or SAP HANA. You need to create a schema and an associated schema admin user before installing the AppWorks Gateway.

The AppWorks Gateway stores your users in OpenText Directory Services (OTDS). During the AppWorks Gateway configuration, you can choose to install OTDS or connect to an existing installation of OTDS.

Important: OpenText strongly recommends connecting to an existing installation of Directory Services. Refer to the AppWorks Gateway Release Notes to determine if the version of your Directory Services installation is supported with AppWorks Gateway 16. If you do not have Directory Services installed, OpenText strongly suggests installing a stand-alone version of Directory Services as opposed to installing the embedded version that is built into the AppWorks Gateway. The embedded version of Directory Services is designed for non-production environments only.

If you have AppWorks Gateway 16.x.x installed, see 1.6 – Upgrading AppWorks Gateway 16.x.x.

If you have AppWorks Gateway 1.2.x installed, there is no migration procedure to preserve your current environment. You need to install AppWorks Gateway 16 as a new installation. For details on uninstalling AppWorks Gateway 1.2.x, see 1.7 – Removing AppWorks Gateway 1.2.x.

Important: This article does not replace the OpenText ECM Everywhere or OpenText Tempo Box, Content Server Edition installation guides. The installation guides for these products are available in their respective product directories on the OpenText Knowledge Center.

1.1 – Prerequisites

The AppWorks Gateway requires the following software.

  1. JDK 1.8.x.

  2. Apache Tomcat 8.0.x.
    If you have a previous version of Apache Tomcat installed, you must uninstall your current version and install Tomcat 8.0.x before installing the AppWorks Gateway.

    Important: OpenText strongly suggests installing the AppWorks Gateway and Apache Tomcat on a dedicated server. Do not install OpenText Directory Services or any other OpenText products on the same server.

  3. Database. The AppWorks Gateway requires a database connection.

    For production environments, you will need to create a schema and an associated schema admin user in your Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, or SAP HANA production database.

    Important: If you want to connect the AppWorks Gateway to a PostgreSQL database, you need to add the following line in the C:\Program Files\PostgreSQL\9.4\data\pg_hba.conf file.

    # TYPE  DATABASE  USER  ADDRESS     METHOD
      host  all       all   0.0.0.0/0   md5
    

    For development or testing purposes, you can connect to the built-in Embedded Derby database, which is an open source relational database that is implemented entirely in Java. This database is not intended for production environments.

1.2 – Configuring Apache Tomcat for the AppWorks Gateway

To configure Apache Tomcat for the AppWorks Gateway:

  1. Ensure you have met the prerequisite requirements. For details, see 1.1 - Prerequisites.

  2. Stop the Apache Tomcat service.

  3. Navigate to the <Tomcat_Home>\bin folder.

  4. Double-click Tomcat8w.exe and do the following:

    a. Click the Java tab.

    b. Type -XX:MaxPermSize=512m at the bottom of the Java Options list.

    c. Type 4096 in the Maximum memory pool box.

    d. Click OK.

    'Apache Tomcat' Java options

    Figure 1-1: Apache Tomcat Java options

  5. Optional: If you plan on running SSL, comment out or remove the following tag.

    <Listener SSLEngine="on" className="org.apache.catalina.core.AprLifeCycleListener"/>
    
  6. Start the Apache Tomcat service to make sure your Tomcat installation starts properly with these new settings.

1.3 – Installing the AppWorks Gateway

To install the AppWorks Gateway:

  1. Stop the Apache Tomcat service.

  2. Navigate to the <Tomcat_Home>\conf folder and back-up the server.xml and context.xml files. The AppWorks Gateway installer overwrites these files. Therefore, you must back-up these files to preserve the edits you’ve made previously.

  3. Download the AppWorks Gateway installation package from the AppWorks Gateway Downloads page.

  4. Extract the contents of the appworks_gateway_16.x.x.zip file to the root of the Apache Tomcat folder. For example, C:\Program Files\Apache Software Foundation\Tomcat 8.0.

    Important: OpenText strongly suggests installing the AppWorks Gateway and Apache Tomcat on a dedicated server. Do not install OpenText Directory Services or any other OpenText products on the same server.

  5. Start the Apache Tomcat service.

    Tip: Navigate to the <Tomcat_Home>\logs folder and watch for the gateway.log file to appear. When the log file appears, you can begin configuring the AppWorks Gateway.

1.4 – Defining the Database for the AppWorks Gateway

To define the database for the AppWorks Gateway:

  1. In a browser, type <https://Tomcat_Host:port>/gateway to view the AppWorks Gateway.

  2. In the Step 1: Database Configuration section, from the Select Database Vendor list, select a database and provide the required information.

    In production environments, select Microsoft SQL Server, MySQL, Oracle, Oracle RAC, PostgreSQL, SAP HANA, or Custom Connection String.

    In development environments, select Embedded Derby. The Embedded Derby database is recommended because no configuration is necessary. The Embedded Derby database is not intended for production environments.

    Important: After the installation is complete, you cannot alter the AppWorks Gateway database connection. Therefore, make sure you are connecting to the database you intend to use for your production environment.

    Important: Depending on the database type you choose, you may need to download the JDBC driver JAR file and place it in your C:\\Program Files\Apache Software Foundation\Tomcat 8.0\lib folder for the version of the database you intend to connect to.

    Caution: The Custom Connection String option is intended for experienced database administrators only and must be used with caution.

    When connecting to an Oracle RAC database, do the following:

    a. In the Username and Password boxes, type the username and password of an admin user in your database.

    b. In the Load Balance area, choose if you would like to enable client side load balancing.

    c. In the Cluster Host box, type the virtual cluster name that you chose when you created the RAC database.

    d. In the Port box, type the port. The default port for Oracle is 1521.

    e. In the Service Identifier box, type the virtual service name that you chose when you created the RAC database.

    See Figure 1-2. This information is added to the opentext.properties file, which is located in the C:\Program Files\Apache Software Foundation\Tomcat 8.0\config folder. The information will appear encrypted in this file.

    Connecting to an Oracle Database

    Figure 1-2: Connecting to an Oracle RAC Database

  3. Click Configure Database Connection and wait for a confirmation that the connection is established.

  4. Proceed to Configuring OTDS for the AppWorks Gateway next.

1.5 – Configuring OTDS for the AppWorks Gateway

To configure OTDS for the AppWorks Gateway:

  1. In the Step 2: OTDS Configuration section, you can choose to connect to an existing installation of OTDS or install and connect to a built-in OTDS instance. Follow the proper procedure for your environment below. The built-in OTDS instance is not intended for production environments. Therefore, in development environments, you should select Install with AWG.

    Important: Once you configure AppWorks Gateway to use an OTDS instance, this setting cannot be changed. Moving from an embedded OTDS instance to an external OTDS instance or vice versa is not supported. In addition, moving to a different OTDS instance after the AppWorks Gateway is configured is also not supported.

Connecting to an existing OTDS installation

To connect to an existing OTDS installation, do the following:

  1. In the Select OTDS Configuration list, select Connect to existing OTDS server.

    Important: AppWorks Gateway 16 requires OpenText Directory Services 16 for oAuth and two-factor authentication, but OTDS 10.5 can be used if you don't wish to use oAuth or two-factor authentication. Earlier versions of OTDS will not work.

  2. Complete the required information.

    The Gateway Admin Username and Password defines the AppWorks Gateway administrative user account that will be created in Directory Services. The default Gateway Admin Username is otag. The password you choose will depend on your OTDS global password policy. Be default, the password is alphanumeric with 8 characters.

    OTDS server url requires the URL of the Tomcat server that is running OTDS. Do not use http://localhost:8080.

    OTDS Administrative Account Username and Password require the credentials for an OTDS Admin user.

    Resource Name and Gateway User Partition Name creates an AppWorks Gateway Resource and User Partition in OTDS with the names provided. The default names are OTAG and otag respectively.

    Note: If you have other AppWorks Gateway installations that connect to the OTDS installation, ensure that the Gateway Admin Username, Gateway User Partition Name, and Resource Name are unique for each installation.

    Connect to an existing OTDS server

    Figure 1-4: Connect to an existing OTDS server

  3. Click Configure OTDS. The configuration is complete when you are prompted to sign in to the AppWorks Gateway again.

  4. Proceed to Final steps to complete the AppWorks Gateway configuration below.

Installing the built-in OTDS Instance

To install the built-in OTDS instance, do the following:

  1. In the Select OTDS Configuration list, select Install with AWG.

  2. Complete the information as required.

    The Gateway Admin Username and Password defines the AppWorks Gateway administrative user account that will be created in OTDS. The default Gateway Admin Username is otag.

    OTDS admin user password defines the password for the OTDS administrative user. The password you choose must be alphanuermic. The OTDS administrative username is otadmin@otds.admin.

    During the OTDS configuration, an AppWorks Gateway Resource and User Partition are created and named OTAG and otag respectively.

    Install OTDS with AppWorks Gateway

    Figure 1-3: Install OTDS with AppWorks Gateway

  3. Click Configure OTDS. The configuration is complete when you are prompted to sign in to the AppWorks Gateway again.

  4. When the AppWorks Gateway sign in page appears, open a second browser and go to the Directory Services Web Client at https://Tomcat_Host:port/otds-admin/.

  5. Sign in as the OTDS admin user using otadmin@otds.admin as the username and the password you defined in the OTDS admin user password box in step 2.

  6. In the left pane, click Partitions.

  7. Verify that the otag partition is available.

  8. Proceed to Final steps to complete the AppWorks Gateway configuration below.

Final steps to complete the AppWorks Gateway configuration

  1. Navigate to the <Tomcat_Home>\logs folder and open the gateway.log file to see the status of the configuration.

  2. If you deployed the AppWorks Gateway in a non-SSL environment, you will see the following error in the gateway.log file.

    ** HTTP 403 encountered during resource authentication. This is likely  
    to be because OTDS is not configured to permit authentication traffic 
    across unsecured (non-SSL/TLS) transports. If this is a development 
    environment, you may work around this security feature by ensuring OTDS 
    has the System Attribute "directory.auth.EnforceSSL=false". **
    

    a. Sign into the Directory Services Web Client at https://Tomcat_Host:port/otds-admin/ and click System Attributes in the left pane.

    b. Click Add and then add directory.auth.EnforceSSL=false in the respective fields that display.

    c. Click Save.

  3. Sign in to the AppWorks Gateway as the OTAG administrative user. The OTAG administrative user is the user you defined in the Gateway Admin Username and Password fields in step 2.

1.6 – Upgrading AppWorks Gateway 16.x.x

Use this procedure if you are upgrading from AppWorks Gateway 16.x.x.

If you have AppWorks Gateway 1.2.x installed, there is no migration procedure to preserve your current environment. You need to install AppWorks Gateway 16 as a new installation. For details on uninstalling AppWorks Gateway 1.2.x, see 1.7 – Removing AppWorks Gateway 1.2.x.

To upgrade AppWorks Gateway:

  1. Stop the Apache Tomcat service that hosts the AppWorks Gateway installation.

  2. Back up the database that is associated with the AppWorks Gateway installation.

  3. Back up the Apache Tomcat directory where AppWorks is installed.

  4. Navigate to the <Tomcat_Home>/conf directory, and rename the server.xml file to, for example, server.bak.

    This step is only required if you have made custom changes to the server.xmlfile. The upgrade overwrites the server.xml file in the <Tomcat_Home> /confdirectory.

  5. Navigate to the <Tomcat_Home> directory and do the following:

    a. Delete the gateway folder.

    b. Delete the contents of the following folders:

    • work

    • temp

    • tmp

    • logs

  6. Extract the contents of the AppWorks Gateway_16.0.x.zip file into the root of the Apache Tomcat folder. For example, <C:\\Program Files\Apache Software Foundation\Tomcat 8.0>.

  7. If you have made custom changes to the server.xml file, use the server.bak back up file to retain those changes in your upgraded installation.

  8. Start the Apache Tomcat service.

  9. In a browser, type <https://Tomcat_Host:port>/gateway to view the AppWorks Gateway. After signing in, all of your applications and settings should be present.

1.7 – Removing AppWorks Gateway 1.2.x

To remove AppWorks Gateway 1.2.x:

If you have AppWorks Gateway 1.2.x installed, there is no migration procedure to preserve your current environment. You need to install AppWorks Gateway 16 as a new installation. First, follow the steps below for removing AppWorks Gateway 1.2.x. Then install the latest version of AppWorks Gateway.

  1. Sign into the Directory Services Web Client at https://Tomcat_Host:port/otds-admin/. In the left pane, click Resources and rename the OTAG resource. When you have completed the installation you can delete the renamed resource.

  2. In the left pane, click Partitions and rename the otag partition. When you have
    completed the installation, you can delete the renamed partition.

  3. Sign into your database management tool and create a new database scheme for AppWorks Gateway 16 to use.

    Note: If you created a database scheme for AppWorks Gateway 1.2.x, do not delete the scheme until your 16.x.x installation is complete and you have confirmed that it works as expected.

  4. Stop the Apache Tomcat service.

  5. The safest way to uninstall the AppWorks Gateway 1.2.x is to reinstall Apache Tomcat. If you reinstall Apache Tomcat, make sure you reconfigure Tomcat for the AppWorks Gateway 16. For details, see 1.2 - Configuring Apache Tomcat for the AppWorks Gateway. However, if you have other software installed in Tomcat and you would prefer not to uninstall it, do the following:

    a. Make sure you have a backup of the following files:

    • gateway.war that is located in the <Tomcat_Home>/webapps folder.

    • opentext.properties that is located in the <Tomcat_Home>/conf folder.

    b. Navigate to the <Tomcat_Home>/conf folder and delete the existing opentext.properties file.

    c. Navigate to the <Tomcat_Home>/webapps folder and delete the existing gateway.war file and gateway folder.

    d. Navigate to the <Tomcat_Home>/temp folder and delete all of the files in the folder.

    e. Navigate to the <Tomcat_Home>/tmp folder and delete all of the files in the folder.

    f. Navigate to the <Tomcat_Home>/lib folder and delete delete any AppWorks Gateway 1.2.x libraries.

    g. Navigate to the <Tomcat_Home>/work/Catalina/localhost folder and delete all of the files in the folder.

  6. You can now install AppWorks Gateway 16. For details, see 1.3 - Installing the the AppWorks Gateway.

Top of page


Table of Contents

Your comment

To leave a comment, please sign in.