AgileApps Support Wiki Pre Release

Quick Install Guide

From AgileApps Support Wiki

Overview

This guide is intended for installers who are setting up a version of the platform for application building and testing. A typlical deployment would look something like this:

Simple Deployment.png

Installation Components The key points depicted in the diagram are:

  • The platform is deployed on a single server.
  • Memcached reduces response time by caching data in memory.
    Learn more: Configuring memcached
  • Ehcache reduces response time by caching data in memory.
    Learn more: Configuring Ehcache
  • Background processes import, export, and the quartz scheduler are running on the same server.
  • Document storage (which includes pictures and image files) is managed separately from the database.
  • The database is running on the same server, for ease of deployment.
  • The database is not replicated, as this deployment optimized for small-scale performance.

Additional Resources

  • To create a fully optimized production installation that utilizes database replication and multiple servers, use the Platform Installation Guide
  • To learn more about the latest release, see the ISV Release Notes
  • See also these additional resources for installation and configuration:

Installation Requirements

Hardware Requirements

Application Server
  • CPU - 64-bit Quad-core AMD Opteron 2214 or better is recommended
  • Memory - 8GB on a 64 bit system is recommended
  • Hard disk capacity - 21GB

Software Requirements

Installing MySQL Version 8.0.xx

Operating System
  • RedHat Enterprise Linux Server - Version 7, Version 8 (recommended), or Version 9

Notepad.png

Note: For RedHat Enterprise Linux Server, ensure that you perform the steps mentioned in the Additional Step for RedHat article.

  • SUSE Linux Enterprise Server - Version 11 or Version 12 (recommended)
  • CentOS Linux - Release 7

Notepad.png

Note: You must change the System Locale Language settings to English USA

  • Windows Server 2016
MySQL Server
  • MySQL Version 8.0.xx (i.e 8.0.29) (Community Edition or Enterprise Edition)
  • MySQL Commercial or Community Client
  • MySQL Commercial or Community Server
  • MySQL Commercial or Community libraries
  • MySQL Commercial or Community compatibility libraries
  • MySQL Commercial or Enterprise common files

If you are a platform user, see Configure the MySQL Server.
To know more about MySQL 8 removed functionality, please click here

Notepad.png

Note:

  • The MySQL RDS version 8 certification with the AgileApps version 10.16 is still in progress.
  • The primary difference between MySQL v8 on-premises and MySQL v8 RDS is the restricted access to the parameters on RDS, which requires certain additional configuration steps to complete the setup and data migration.
  • The deprecated ASC or DESC qualifiers for GROUP BY clauses are removed. This impacts the custom SQL used in the application and results in a database syntax error. It is recommended that the application designer reviews the custom SQL used in the application to adopt MYSQL 8.
Libraries Download the third-party libraries and save them in a folder.
You may want to integrate them into the system during the installation.
  • Download mysql-connector-java-8.0.29.jar here

Notepad.png

Note: If mysql j/connector 8 series is used then set below properties in jdbc connection url string

scrollTolerantForwardOnly=true
Example:
Edit below files present in <Install-dir>/profiles/IS_default/configuration/com.softwareagplatform.config.propsloader folder and add scrollTolerantForwardOnly=true in jdbc connection url values in the below listed property files:

  1. com.softwareag.catalina.resource.pid-agileappsRN.properties
  2. com.softwareag.catalina.resource.pid-agileappsQuartz.properties

Installing MySQL Version 5.7.xx

Operating System
  • RedHat Enterprise Linux Server - Version 7, Version 8 (recommended), or Version 9
  • SUSE Linux Enterprise Server - Version 11 or Version 12 (recommended)
  • CentOS Linux - Release 7

Notepad.png

Note: You must change the System Locale Language settings to English USA

  • Windows Server 2016
MySQL Server
  • MySQL Version 5.7.xx (Community Edition or Enterprise Edition)
  • MySQL Commercial or Community Client
  • MySQL Commercial or Community Server
  • MySQL Commercial or Community libraries
  • MySQL Commercial or Community compatibility libraries
  • MySQL Commercial or Enterprise common files

If you are a platform user, see Configure the MySQL Server.

Libraries Download the third-party libraries and save it in a folder.
You may want to integrate them into the system during the installation.
  • Download mysql-connector-java-5.1.24-bin.jar here.
  • Download jta.jar here

Required for Basic Platform Functionality

Mail Server
Mail Server Configuration
  • Choose any postfix, sendmail or so on.
  • Run the mail server on TCP Port 25
    The mail server should always be up and running for the platform functionality to work as expected
  • Test and verify the Mail Server MTA (Mail Transfer Agent) with the following command:
echo "test mail" | mail -s "hello" admin-name@myserviceproviderdomain.com

An email message should be received at the specified address. If the confirmation message does not arrive, check the mail log to discover the cause.

Cache
Memcached 1.4.10 for caching
Memcached requires installation of libevent library version 2.0.16 (An event notification library) for your Operating System. It can be downloaded from http://www.monkey.org/~provos/libevent/. For more information, see Configuring memcached.
Ehcache for caching

Ehcache is available in the Common Tomcat profile. For more information, see Configuring Ehcache.

Web Server
Apache HTTP server 2.2.21 (Optional, but recommended)

The Apache web server can be placed in front of the Tomcat appserver to deliver static content more efficiently.
It is recommended for systems with large numbers of Static Resources and Documents
The following modules must be compiled into Apache during installation:

  • mod_proxy
  • mod_ssl
  • mod_expires
  • mod_headers

For more information, see Installing and Configuring Apache for Use with the Platform.

Java

The installation and operation of the AgileApps Cloud platform requires Java 8. However, the custom code in Java Class continues to be validated against Java 6 syntax as the instrumentation engine responsible for monitoring resource utilization works only on Java 6 byte codes.

Browser Support
Application excluding Process
  • Internet Explorer 11
  • Microsoft Edge
  • Firefox 32 (Minimum requirement)
  • Chrome 48.0.2564 (Minimum requirement)
Process Model
  • Does not support Internet Explorer
  • Does not support Microsoft Edge
  • Firefox 32 (Minimum requirement)
  • Chrome 48.0.2564 (Minimum requirement)

As part of the security processes, the Remember me on this computer option is removed from the browser's login page.

Important:
To edit a Process Model, use Firefox or Chrome. Other browsers may work poorly, or not all.
Accessibility Mode requires Firefox

Required for Additional Functionality

OpenOffice (optional)
OpenOffice 3.2.0 or higher
soffice -headless -accept="socket,host=127.0.0.1,port=8100;urp;" -nofirststartwizard

Notepad.png

Note: If you have a problem with glibc library version incompatibility while installing OpenOffice 3.4.x (for RedHat with version 5.6 and lower), you should download and install OpenOffice 3.20

HornetQ (optional)
HornetQ 2.2.14

The Messaging Server is an optional platform component that:

  • Handles the on-screen notifications to prevent editing collisions when users view the same Case.

Get HornetQ from http://www.jboss.org/hornetq/downloads.html. For more information, see Installing the Messaging Server.

Charting Libraries (optional)

Additional libraries are needed to email a chart or a report. For more information, see Install the Chart Handling Libraries.


Installation

Configuring the MySQL Server

These instructions apply to the version of MySQL specified in the Software Requirements.

Notepad.png

Note: MySQL configuration is a pre-requisite for the AgileApps installation.

Terminology:

MySQL Server
The database server which has MySQL Server software installed, configured, and running.
MySQL Client
Any other computer which connects to the database server and has the MySQL Client software installed, configured, and running.
  • The client connects to the database server to access data, for example, webserver.
Configuration file
my.cnf, a MySQL configuration file that may be edited and used in the MySQL client or MySQL Server installation.
MySQL Settings
Storage Engine
default-storage-engine = innodb
Server System Variables Configuration
It is observed that READ_UNCOMMITTED does not work well with Row-Based Replication. Use one of the following configurations:
a) Either STATEMENT-BASED or MIXED replication with the Transaction Isolation level dictated by business needs.
b) ROW-BASED replication with transaction_isolation = READ-COMMITTED
User Configuration
  • Create a user account with password in MySQL
    The Application Server will use the user details.
  • The user account should have all MySQL privileges enabled on all databases
  • Use the default root account that is created during the installation of MySQL. You can also create a non-root MySQL user to run Agile Apps. For more information, see Creating a non-root MySQL User to Run Agile Apps.
sql-mode Configuration
  • Add the following code to the my.cnf file located in the MySQL Client:
sql-mode="PIPES_AS_CONCAT,ANSI_QUOTES"
  • Add the following code to the my.cnf file located in the MySQL Server:
sql-mode="PIPES_AS_CONCAT,ANSI_QUOTES"
MySQL Configuration for UTF-8 Unicode character set for 5.7 Version
  • Add the following code to the my.cnf file, located in the MySQL Client:
default-character-set=utf8
  • Add the following code to the my.cnf file, located in MySQL Server:
character-set-server=utf8
collation-server=utf8_general_ci
The character set defines how records can be alphanumerically ordered (or grouped, sorted, filtered, indexed). The list of supported languages is determined by the character set available at the server level. Hence, the UTF-8 Unicode character set configuration is required as part of MySQL configuration.
To specify character settings at MySQL configuration time:
For MySQL Version 5.7, see https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
MySQL Configuration for UTF-8mb4 Unicode character set for MySQL 8.0 Version

Notepad.png

Note: For MySQL configuration v5.7 to v8 upgrade, refer Upgrading to MySQL v8.

  • Add the following code to the my.cnf file, located in the MySQL Client:
default-character-set=utf8mb4
  • Add the following code to the my.cnf file, located in MySQL Server:
character-set-server=utf8mb4
collation-server=utf8mb4_0900_ai_ci
The character set defines how records can be alphanumerically ordered (or grouped, sorted, filtered, indexed). The list of supported languages is determined by the character set available at the server level. Hence, the UTF-8 Unicode character set configuration is required as part of MySQL configuration.

Notepad.png

Note: If user does not specific in my.cnf or my.ini file then default MySQL 8 character set and collation are utf8mb4 and utf8mb4_0900_ai_ci taken by server.

To specify character settings at MySQL configuration time:
For MySQL Version 8.0, see http://dev.mysql.com/doc/refman//8.0/en/charset-applications.html
max_allowed_packet Configuration
  • Add max_allowed_packet = 64M to my.cnf or my.ini
For MySQL Version 5.7, see https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
For MySQL Version 8.0, see https://dev.mysql.com/doc/refman/8.0/en/charset-applications.html
  • Restart the MySQL server to implement the changes
regexp_time_limit Configuration

The regular expression limit is expressed as the maximum permitted number of steps performed by the match engine, and thus affects execution time only indirectly. It is defined in milliseconds.

  • Add regexp_time_limit=2048 to my.cnf or my.ini
For MySQL Version 5.7, see https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
For MySQL Version 8.0, see https://dev.mysql.com/doc/refman/8.0/en/charset-applications.html
  • Restart the MySQL server to implement the changes
Populate the Timezone Tables
The platform uses MySQL's timezone tables for timezone conversions. These tables are not automatically populated when MySQL is installed, so it necessary to do so after installation.
Run the following program to initialize the MySQL timezone tables:
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
where /usr/share/zoneinfo is the standard Linux location for the time zone files. (Your system may differ.)
For MySQL Version 5.7, see https://dev.mysql.com/doc/refman/5.7/en/mysql-tzinfo-to-sql.html
For MySQL Version 8.0, see https://dev.mysql.com/doc/refman/8.0/en/mysql-tzinfo-to-sql.html

Installing and Upgrading the Application Server

New Installations

  1. Review the Installable Version Release Notes.
  2. Ensure that the Hardware Requirements are met.
  3. Ensure that the Software Requirements#Required for Installation are met.
  4. Configure the MySQL Server so it is ready for use.
  5. Ensure that all database servers and web servers are configured to be in the same timezone, regardless of where they are geographically located.
  6. Use the standard SoftwareAG webMethods installer to install the platform of your choice.
    Learn more:
    From the webMethods documentation page consult the respective Installation document.
  7. For the very first server that is installed, Start the Application Server to verify that everything is working.
  8. For subsequent servers, Configure Backend Services before startup.
  9. Install the Platform License
  10. Once installed, proceed to Configuring the Application Server

Upgrades

Warn.png

Important:
These are instructions are for version 10.5 and later.
If you are upgrading to 10.5, use the 10.5 Upgrade Process, instead.

  1. If you have not already done so:
  2. Use the standard SoftwareAG installer to install the 10.5 platform.
    Learn more: In webMethods documentation page see the 9.9 Installation document.
  3. Start the Application Server
  4. When done, proceed to Configuring the Application Server


Configuration

Configuring the Application Server

  1. As described in Software Requirements#Required for Basic Platform Functionality:
    • Configure an email server to enable email-based collaboration.
    • To improve performance, install and memcached for caching. (You will configure it in a moment).
    • Add the Apache HTTP server to further improve performance.
  2. All backend services are enabled by default. But they will cause performance problems if they are running on the customer-facing application server, and errors can result if they are running on multiple servers. After installing the platform, therefore, it is important to disable all backend services that are not required on the current server.
    Learn more: Managing Backend Services
  3. As described in Software Requirements#Required for Additional Functionality:
  4. Additionally:

Notepad.png

Note:
When making changes to an existing server, restart the server to read in the new values.


Configure the Service Provider Settings

Accessing the Application Server

After the application server has been started:

1. Access the Service Provider URL: http://{yourDomain}/networking/Service?t=1&targetpage=ViewPort.jsp:
Where:
  • {yourDomain} is the platform domain. For example: yourcompany.com
  • Default username and password: Use the credentials you typed into the Software AG installer.

Notepad.png

Note: These credentials are only applicable to the on-premise fresh installations of AgileApps and not for AgileApps cloud.

The platform will request that you change your password after you login the first time.
2. Setup the Service Configuration with these required parameters:
Configure the Service Settings and specify Service and Domain names:
Parameter Description Typical Value
Service Name Name of the service provider Financiocorp Services
Prefix for Service Domain Optional subdomain name

Allowed characters: a-z, A-Z, 0-9, - (alphanumeric, plus hyphen)

Example: service

Service Domain The Domain Name part of the URL mydomain.com
Domain URL

Read Only
Automatically populated as:

Prefix + Service Domain

service.mydomain.com


Set Up the Initial Tenant

At this point, you are working with the tenant administration interface. The next step is to create a tenant. Logging into that tenant brings up the application interface, where you can build, load, and run applications. (It also makes recovery easier, should you make a mistake. For example, were to you "delete all", you could always create a new tenant, since the underlying platform would be unaffected.)

Creating a Tenant

  1. After Login, create a new tenant from a web browser using the URL as follows:
  2. https://yourdomain.com/networking/Service?t=2308
    Where yourdomain.com is the name of your domain


You are now ready to begin application development or install an existing application for testing.
See the Welcome page for links to additional information on those subjects.

Application Server Operations

Server Restart Sequence

When an installation employs memcached or the Messaging Server, it is important to follow this sequence when restarting servers: 

# STOP THE MESSAGING SERVER, if one is running:
/etc/init.d/messaging stop
{hornetq-folder}/bin/stop.sh

# STOP ALL APPLICATION SERVERS
# On each server:
{install-dir}/profiles/IS_default/bin/shutdown.sh

# STOP ALL memcached SERVERS
# On each server:
/bin/memcached -d stop

# START ALL memcached SERVERS
# On each server:
/bin/memcached -d start -p {port} -u {user} -m {MB_of_memory}
   # Typical values:
   #    Port: 11211,  User: root,  MB of memory: 25

# START ALL APPLICATION SERVERS
# On each server:
{install-dir}/profiles/IS_default/bin/startup.sh

# START THE MESSAGING SERVER, if you're running one:
{hornetq-folder}/bin/start.sh
/etc/init.d/messaging start
Considerations
  • Stopping application servers ensures that they aren't adding entries to the cache.
  • Stopping memcached makes sure that the cache is flushed.
  • Those two steps can occur in either order. It is the next two for which order is critical:
  • Restarting memcached first makes sure that a clean copy of the cache is available.
  • When the application servers come up, they use the clean cache.

Start the Application Server

  1. Login as root
  2. {install-dir}/profiles/IS_default/bin/startup.sh

Restart the Application Server

  1. Login as root
  2. {install-dir}/profiles/IS_default/bin/restart.sh

Stop the Application Server

To stop the application server, you kill the Apache Tomcat container it's running in.

  1. Login in as root
  2. {install-dir}/profiles/IS_default/bin/shutdown.sh

Accessing the Application Server

After the application server has been started:

1. Access the Service Provider URL: http://{yourDomain}/networking/Service?t=1&targetpage=ViewPort.jsp:
Where:
  • {yourDomain} is the platform domain. For example: yourcompany.com
  • Default username and password: Use the credentials you typed into the Software AG installer.

Notepad.png

Note: These credentials are only applicable to the on-premise fresh installations of AgileApps and not for AgileApps cloud.

The platform will request that you change your password after you login the first time.
2. Setup the Service Configuration with these required parameters:
Configure the Service Settings and specify Service and Domain names:
Parameter Description Typical Value
Service Name Name of the service provider Financiocorp Services
Prefix for Service Domain Optional subdomain name

Allowed characters: a-z, A-Z, 0-9, - (alphanumeric, plus hyphen)

Example: service

Service Domain The Domain Name part of the URL mydomain.com
Domain URL

Read Only
Automatically populated as:

Prefix + Service Domain

service.mydomain.com


Creating a Tenant

  1. After Login, create a new tenant from a web browser using the URL as follows:
  2. https://yourdomain.com/networking/Service?t=2308
    Where yourdomain.com is the name of your domain
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=Quick_Install_Guide&oldid=21551"