Installation

Natural for Ajax uses the Software AG Installer, which you download from the Software AG Empower website at https://empower.softwareag.com/, to copy the distributables for the supported application servers and web containers to your machine. You can then install the distributables on your application server or web container as described in this document. On application servers and web containers, Natural for Ajax consists of a web application (cisnatural.war).

This document provides product-specific instructions for installing Natural for Ajax. It is intended for use with Using the Software AG Installer. That guide explains how to prepare your machine to use the Software AG Installer, and how to use the Software AG Installer and Software AG Uninstaller to install and uninstall your products. The most up-to-date version of Using the Software AG Installer is always available at http://documentation.softwareag.com/ (Empower login required).

Note:
This document does not describe the installation of the additionally required Natural components on a Windows, UNIX or mainframe host, but refers to the corresponding installation documents.

This document covers the following topics:

For important last-minute information, see the readme file that is provided with Natural for Ajax. You can find it in the Natural for Ajax product documentation at http://documentation.softwareag.com/ (Empower login required).

For information on how to activate the preconfigured security settings of Natural for Ajax and how to adapt them to your requirements, see Configuring Container-Managed Security in Client Configuration.

You may find additional technical papers dealing with advanced configuration topics in the Knowledge Center at https://empower.softwareag.com/ (for registered users only).

Installing the Natural for Ajax Distributables with the Software AG Installer

This section provides just a brief description on how to install the Natural for Ajax distributables directly on the target machine using the Software AG Installer GUI. For detailed information on the Software AG Installer, see Using the Software AG Installer.

Start of instruction setTo install the Natural for Ajax distributables

  1. Start the Software AG Installer GUI as described in Using the Software AG Installer.

  2. When the first page of the Software AG Installer GUI (the so-called Welcome panel) is shown, choose the Next button repeatedly (and specify all required information on the shown panels as described in Using the Software AG Installer) until the panel containing the product selection tree appears. This tree lists the products you have licensed and which can be installed on the operating system of the machine on which you are installing.

  3. To install the Natural for Ajax distributables, expand the Natural Products node and select Natural for Ajax.

  4. Choose the Next button.

  5. Read the license agreement, select the check box to agree to the terms of the license agreement, and choose the Next button.

  6. On the last panel, review the list of products and items you have selected for installation. If the list is correct, choose the Next button to start the installation process.

    When the Software AG Installer has completed the installation, you can find the distributables in the <install-dir>/NaturalAjax/AppServer directory. You can now install them on your application server or web container as described below.

Installing Natural for Ajax on JBoss Application Server 7 and WildFly 8

The distributables for JBoss Application Server 7 and WildFly 8 are contained in the directory <install-dir>/NaturalAjax/AppServer/Jboss7-WildFly8.

The following is assumed:

  • <host> is the name of the machine on which JBoss is installed.

  • <port> is the name of the port where JBoss is installed. In a default installation, this is port 8080.

  • <adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 9990.

  • <jboss_home> is the path to the directory in which JBoss or WildFly is installed.

The following topics are covered below:

First-time Installation

Start of instruction setTo install Natural for Ajax

  1. Stop JBoss Application Server or WildFly.

  2. Extract the contents of the file cisnatural.war into a new directory <jboss_home>/standalone/deployments/cisnatural.war.

  3. Add your license file to the directory <jboss_home>/standalone/deployments/cisnatural.war/cis/licensekey.

  4. Add the following security domain definition in the file standalone.xml, under <security-domains>. This file is contained in <application-server-install-dir>/standalone/configuration. 

    <security-domain name="NaturalWebIOAndAjaxRealm" cache-type="default">
</security-domain>

  5. Start JBoss Application Server or WildFly.

  6. To trigger the actual deployment, create a file named cisnatural.war.dodeploy in <jboss_home>/standalone/deployments.

Update Installation

Start of instruction setTo update Natural for Ajax

  1. Start JBoss Application Server or WildFly.

  2. Create a backup copy of your sessions.xml file, which is located in <jboss_home>/standalone/deployments/cisnatural.war/WEB-INF.

  3. Create a backup copy of your license file, which is located in <jboss_home>/standalone/deployments/cisnatural.war/cis/licensekey.

  4. Create backup copies of all modified configuration files, which are located in <jboss_home>/standalone/deployments/cisnatural.war/cis/config.

  5. Create backup copies of previously created projects, which are located in <jboss_home>/standalone/deployments/cisnatural.war.

  6. Open your web browser and enter the following URL: 

    http://<host>:<adminport>/console

    This opens the Administration Console.

  7. Select cisnatural.war in the list of installed applications.

  8. Choose Remove.

  9. Deploy the cisnatural.war file for the new version of Natural for Ajax as in a first-time installation.

  10. Restore the files that you have backed up in steps 2, 3, 4 and 5.

  11. Open your web browser and enter the following URL: 

    http://<host>:<port>/cisnatural/index.html

  12. Regenerate the HTML pages.

    We recommend using the Ant generation script to regenerate the HTML pages. See Generating HTML Pages Using the Command Line. Alternatively, you can use the Layout Manager and Style Sheet Editor tools to manually regenerate the files.

Installing Natural for Ajax on IBM WebSphere Application Server

The distributables for IBM WebSphere Application Server are contained in the directory <install-dir>/NaturalAjax/AppServer/WebSphere.

Natural for Ajax is installed using the Administration Console of IBM WebSphere Application Server.

The following is assumed:

  • <host> is the name of the machine on which the application server is installed.

  • <port> is the name of the port where the application server is installed. In a default installation, this is port 9080.

  • <adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 9060.

The following topics are covered below:

First-time Installation

Start of instruction setTo install Natural for Ajax

  1. Make sure the application server is running.

  2. Open your web browser and enter the following URL: 

    http://<host>:<adminport>/ibm/console

    This opens the Administration Console.

  3. Deploy the web application cisnatural.war.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. On the Enterprise applications page, choose Install.

    3. Select WebSphere/cisnatural.war as the path to the new application. Then choose Next.

    4. Choose Next. If additional information is required, you will be prompted.

    5. On the Select installation options page, choose Next. You will then install with the default options.

    6. On the Map modules to servers page, select a cluster and server, select Natural for Ajax and choose Apply. Then choose Next.

    7. On the Map virtual hosts for Web modules page, select a virtual host, select Natural for Ajax and choose Next.

    8. On the Map context roots for Web modules page, enter "cisnatural" as context root and choose Next.

    9. On the Summary page, choose Finish.

    10. On the next page, choose Save.

  4. Configure the application.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. Select cisnatural.war.

    3. On the Configuration page, select Class loading and update detection.

    4. On the General Properties page, enter a value for Polling interval for updated files (for example, 300 seconds).

    5. On the General Properties page under Class loader order, select Classes loaded with local class loader first (parent last).

    6. Choose OK.

    7. On the next page, choose Save.

    8. Back on the Enterprise applications page, select cisnatural.war.

    9. On the Configuration page under Modules, select Manage Modules.

    10. On the Manage Modules page, click the Natural for Ajax link.

    11. On the General properties page under Class loader order, select Classes loaded with local class loader first (parent last).

    12. Choose OK.

    13. On the next page, choose Save.

  5. Deploy the license file.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. On the Enterprise applications page, select cisnatural.war and choose Update.

    3. On the Preparing for the application update page, choose Replace or add a single file.

    4. In the Specify the path beginning… field, enter "cisnatural.war/cis/licensekey/<licensekeyfilename>".

    5. In the Specify the path to the file field, browse for your license key file.

    6. Choose Next.

    7. On the Updating application page, choose OK.

    8. On the next page, choose Save.

  6. Start the application.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. On the Enterprise applications page, select cisnatural.war and choose Start.

Update Installation

Start of instruction setTo update Natural for Ajax

  1. Create a backup copy of the Natural for Ajax application and the contained user projects.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. On the Enterprise applications page, select cisnatural.war and choose Export. The application is exported as the file cisnatural_war.ear.

    3. On the Export Application EAR files page, choose cisnatural_war.ear to download it from the application server.

    4. Extract the web application cisnatural.war from the exported archive.

  2. Copy user projects and modified configuration files from the exported old version of cisnatural.war to the new version.

    1. Unpack the exported old cisnatural.war using a zip tool.

    2. Unpack the new cisnatural.war using a zip tool.

    3. Copy the sessions.xml file, which is located in cisnatural.war/WEB-INF, from the old version to the new version.

    4. Copy the license file, which is located in cisnatural.war/cis/licensekey, from the old cisnatural.war to the new cisnatural.war.

    5. Copy all modified configuration files, which are located in cisnatural.war/cis/config, from the old cisnatural.war to the new cisnatural.war.

    6. Copy all user projects, which are located in cisnatural.war, from the old cisnatural.war to the new cisnatural.war.

    7. Repack the new cisnatural.war to a web application using a zip tool.

  3. Uninstall the old version of Natural for Ajax.

    1. Open the tree node Applications > Application Types > WebSphere enterprise applications.

    2. On the Enterprise applications page, select cisnatural.war and choose Uninstall.

    3. On the Uninstall Application page, choose OK.

    4. On the next page, choose Save.

  4. Install the new version of Natural for Ajax as in a first installation.

Installing Natural for Ajax on Apache Tomcat

The distributables for Apache Tomcat are contained in the directory <install-dir>/NaturalAjax/AppServer/Tomcat.

Natural for Ajax is installed using the Tomcat Manager.

The following is assumed:

  • <host> is the name of the machine on which Apache Tomcat is installed.

  • <port> is the name of the port where Apache Tomcat is installed. In a default installation, this is port 8080.

  • <tomcat> is the path to the directory in which Apache Tomcat is installed.

Note:
In Apache Tomcat 7 and 8, the Tomcat Manager limits the size of a web application to be deployed by default to 50MB. Before installing on Apache Tomcat 7 or 8, increase the values of <max-file-size> and <max-request-size> in the configuration file <tomcat>/webapps/manager/WEB-INF/web.xml to at least 80MB.

The following topics are covered below:

First-time Installation

Start of instruction setTo install Natural for Ajax

  1. Start Apache Tomcat.

  2. Open your web browser and enter the following URL: 

    http://<host>:<port>/manager/html

    This opens the Tomcat Manager.

  3. Deploy the web application file cisnatural.war:

    • Under Select WAR file to upload select the path to the file cisnatural.war.

    • Choose Deploy.

  4. Copy the license file into the directory <tomcat>/webapps/cisnatural/cis/licensekey (you have to create the directory if it does not yet exist).

  5. In the Tomcat Manager, look for the application Natural for Ajax and choose Reload.

Update Installation

Start of instruction setTo update Natural for Ajax

  1. Shut down Apache Tomcat.

  2. Create a backup copy of your sessions.xml file, which is located in <tomcat>/webapps/cisnatural/WEB-INF.

  3. Create a backup copy of your license file, which is located in <tomcat>/webapps/cisnatural/cis/licensekey.

  4. Create backup copies of all modified configuration files, which are located in <tomcat>/webapps/cisnatural/cis/config.

  5. Create backup copies of previously created projects, which are located in <tomcat>/webapps/cisnatural.

  6. Start Apache Tomcat.

  7. Open your web browser and enter the following URL: 

    http://<host>:<port>/manager/html

    This opens the Tomcat Manager.

  8. Select cisnatural.war in the list of installed applications.

  9. Choose Undeploy.

  10. Deploy the new version of Natural for Ajax as in a first-time installation.

  11. Shut down Apache Tomcat.

  12. Restore the files that you have backed up in steps 2, 3, 4 and 5.

  13. Start Apache Tomcat.

  14. Open your web browser and enter the following URL: 

    http://<host>:<port>/cisnatural/index.html

  15. Regenerate the HTML pages.

    We recommend using the Ant generation script to regenerate the HTML pages. See Generating HTML Pages Using the Command Line. Alternatively, you can use the Layout Manager and Style Sheet Editor tools to manually regenerate the files.

Verifying the Installation

It is assumed that http://<host>:<port> is the URL of your application server or web container.

Start of instruction setTo verify the installation

  1. Enter the following URL in your web browser:

    http://<host>:<port>/cisnatural/index.html

    This opens a page from where you can access the logon page, the development workplace and the configuration tool.

  2. Click on the link for the logon page.

    This opens the Natural logon page. The installation is now complete.