Posted Apr 28 by Edmund Clayton.
Updated Jun 08.

Learn how to install the OpenText AppWorks Gateway version 16.2.

Last activity Jun 08 by Edmund Clayton.
1119 views. 0 comments.

Chapter 1 – Installing 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.

Before you start, review the AppWorks Gateway Release Notes for 16.2. The Release Notes contain comprehensive information on supported environments, language support, and the compatibility of release 16.2 with other OpenText products.
The Release Notes are available from the Get Started section of the AppWorks Developer website.

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 website.

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.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.

    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
    

    If MySQL is your target database, set the max_allowed_packet_length to a suitable value, for example, 1024 MB.

    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.

    Important: The AppWorks Gateway installation package includes modified versions of the server.xml and context.xml files. If you have customized the server.xml or context.xml files, and you want to retain those changes, you must add them to the versions of the files supplied by the AppWorks Gateway.

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

  4. Extract the contents of the otag-gateway-16.1.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: When you see Server Start in the catalina.out file, you can start to configure 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
    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. If you add the JDBC driver, you must restart the Apache Tomcat service.

    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.1 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.

Top of page



Table of Contents

Your comment

To leave a comment, please sign in.