This section contains information about AppBase Platform Installation and instructions how to perform maintenance and troubleshooting.

Understanding AppBase Installation

AppBase Components

AppBase Platform installation topology

AppBase Software Folder Structure

AppBase Runtime Data Folder Structure

Managing AppBase Services

Stop AppBase Services

Start AppBase Services

Change AppBase Configuration

Push AppBase Configuration changes

Managing Apache ActiveMQ (Linux, External Installation)

Managing Redis (Linux, External Installation)

Managing AppBase Installation

Managing Oracle

Troubleshooting AppBase Installation

Understanding AppBase Installation

Please refer to AppBase Deployment Roles explanation for full list of AppBase Deployment Roles.

There are two main AppBase Installation types:

1. Single VM AppBase Installation – all AppBase Deployment Roles (AppBase Web Applications, AppBase System Web Services, AppBase System Windows Services, AppBase Infrastructure Services, etc) are installed on the same VM. This strategy typically used for Development and NPE (Non Production Environments).

2. Clustered AppBase installation – main AppBase Deployment Roles (AppBase Web Applications, AppBase System Web Services, AppBase System Windows Services) are installed on every VM, AppBase Instrastructure Services are installed on shared VMs (Windows or Linux). This strategy typically used for Production and UAT environments.

Please refer to AppBase Installation Guide for information about AppBase installation.

AppBase Components

Table below provides information about AppBase components, their AppBase deployment roles, log files, etc

¹⁾ Requires additional licenses, please refer to Document Imaging & OCR Licenses

²⁾ Private Perimeter port, please refer to AppBase Platform Installation topology below

³⁾ Tomcat Report Client port

⁴⁾ ActiveMQ service port

⁵⁾ Redis service port

AppBase Platform installation topology

On every VM, we install two instances of AppBase Platform with different Deployment Roles:

1. Public Perimeter – AppBase Web Application and AppBase System Web Services Deployment Roles, exposed for end-user. For Clustered AppBase Installations, Public Perimeter typically placed behind Load Balancer to distribute the load. SSL can be handled either on Public Perimeter (LB passed 443 traffic) or on LB (LB offloads SSL and pass decrypted traffic to Public Perimeter)

2. Private Perimeter – AppBase System Windows Services and AppBase System Web Services (required to serve AppBase System Windows Services), AppBase Java Services, AppBase Capture Windows Services, AppBase Print Windows Services, AppBase OCR Windows Services, AppBase Full Text Search Windows Services. For Single VM Installation Type, this perimeter will also include AppBase Infrastructure Components (ActiveMQ, Redis). Private Perimeter is only required to process background tasks and should never be exposed to end-user.

⁶⁾ server node – AppBase server node name, e.g. srv01, srv02, etc

AppBase Software Folder Structure

Each AppBase installation will have following folder structure on every node (VM)

AppBase Runtime Data Folder Structure

Managing AppBase Services

Assumptions:

Commands below should be executed under account with Administrator privileges.

Commands below should be running on each node (VM) running AppBase.

Commands below are using relative path, make sure that you go to AppBase configuration folder first (refer to AppBase configuration folder in AppBase Software Folder Structure)

Stop AppBase Services

InstallerMain.bat -Command Server-Stop -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME>

or

appbase-stop.bat

where SERVERS_CONFIG_FILE.xml – AppBase configuration file obtained

SERVER_NAME – AppBase server name

Clear AppBase Cache

InstallerMain.bat -Command Server-RemoveCache -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME>

where SERVERS_CONFIG_FILE.xml – AppBase configuration file obtained

SERVER_NAME – AppBase server name

Start AppBase Services

InstallerMain.bat -Command Server-Start -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME>

or

appbase-start.bat

where SERVERS_CONFIG_FILE.xml – AppBase configuration file obtained

SERVER_NAME – AppBase server name

Change AppBase Configuration

1. Update _all_substitutions_common.liquid file in AppBase configuration folder

2. InstallerMain.bat -Command Server-Configure -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME>

or

appbase-configure.bat

where SERVERS_CONFIG_FILE.xml – AppBase configuration file obtained

SERVER_NAME – AppBase server name

Push AppBase Configuration changes

InstallerMain.bat -Command Server-UpdateConfigs -ServerFile <SERVERS_CONFIG_FILE.xml> -Server <SERVER_NAME>

or

appbase-configure.bat

where SERVERS_CONFIG_FILE.xml – AppBase configuration file obtained

SERVER_NAME – AppBase server name

Managing Apache ActiveMQ (Linux, External Installation)

Assumptions:

ActiveMQ is installed to /opt/activemq

ActiveMQ is installed as a daemon running under service account srv_AppBase

Apache ActiveMQ is configured to run as a daemon and will be automatically started when VM is booted up. If you need to perform maintenance, please perform following commands:

Stop Apache ActiveMQ

sudo service activemq stop

Start Apache ActiveMQ

sudo service activemq start

To view list of available queues and consumers, please open Apache ActiveMQ management console at:

http://xxx.xxx.xxx.xxx:8161/admin (u: admin, p: admin)

Log files are located at:

/opt/activemq/data/activemq.log

Managing Redis (Linux, External Installation)

Assumptions:

Redis is installed to /opt/redis

Redis is installed as a daemon running under service account srv_AppBase

Redis is configured to run as a daemon and will be automatically started when VM is booted up. If you need to perform maintenance, please perform following commands:

Stop Redis

sudo service redis stop

Start Redis

sudo service redis start

Log files are located at:

/opt/redis/data/redis.log

Managing AppBase Installation

In order to perform AppBase cold start, please follow steps below:

1. Start ActiveMQ (if ActiveMQ is configured as external service)

2. Start Redis  (if Redis is configured as external service)

3. Start AppBase Components (on every node)

In order to perform AppBase full stop, please follow steps below:

1. Start AppBase Components (on every node)

2. Stop Redis  (if Redis is configured as external service)

2. Stop ActiveMQ (if ActiveMQ is configured as external service)

Managing Oracle

Oracle Database Server can be installed on both Windows and Linux. In this article we will consider management of a database server on Linux.

Please connect to DB server via PuTTY

[root@oracle12 ~]# sudo su - oracle

1. DB server OS status info

To obtain info about DB server OS status please run:

[oracle@oracle12 ~]$ top

detailed see https://www.booleanworld.com/guide-linux-top-command/

2. Restart entire DB server

To restart entire DB server run:

[oracle@oracle12 ~]$ sudo shutdown -r now

3. Using the TNSPING Utility to Test Connectivity from the Client

The TNSPING utility determines whether the listener for a service on an Oracle Net network can be reached successfully.

If you can connect successfully from a client to a server (or a server to another server) using the TNSPING utility, then it displays an estimate of the round trip time (in milliseconds) it takes to reach the Oracle Net service.

If it fails, then it displays a message describing the error that occurred. This enables you to see the network error that is occurring without the overhead of a database connection.

Use the following command to test connectivity:

tnsping net_service_name count

In the preceding command, the following arguments are used:

• net_service_name must exist in tnsnames.ora file or the name service in use, such as NIS.

• count determines how many times the program attempts to reach the server. This argument is optional.

If the net service name specified is a database name, then TNSPING attempts to contact the corresponding listener. It does not actually determine whether the database is running. Use SQL*Plus to attempt a connection to the database.

Following is example of TNSPING

Detailed see in the https://docs.oracle.com/cd/E11882_01/network.112/e41945/connect.htm#NETAG383

4. Using Telnet to Test Port 1521 Functionality

You can run a simple troubleshooting test to make sure the Client can connect to the port. Just try to telnet to the port from the Client (AppBase VM).

To test the functionality of port 1521, use this command from the Client:

Telnet tserv 1521

where "tserv" is the host name of IP of your DB Server.

If telnet is successful, you simply receive the telnet screen and a cursor. On the Terminal Server, Terminal Server Administration will show a blue computer icon with no other information. The Telnet connection will also consume an idle session.

The DB Server should disconnect the connection after a few minutes. Or, you can disconnect using Telnet.

This test tells you that you can connect over the port.

5. Restarting an Oracle Database or Automatic Storage Management Instance

To restart an Oracle Database or Automatic Storage Management instance:

1. If required, run the following command to switch in the oracle user context:
   

   [root@oracle12 ~]# sudo su - oracle

   
   

2. Run the following commands to run sqlplus and connect to DB instance:
   

   [oracle@oracle12 ~]$ sqlplus / as sysdba

   

3. Run the following commands to start the instance:
   

   SQL> STARTUP

   
   After the instance starts, you can exit from SQL*Plus.
   To know more about startup options see https://docs.oracle.com/cd/B19306_01/server.102/b14231/start.htm 

4. Check lsnrctrl status like in 6.4. If required perform lsnrctrl start like in 6.3.
5. Check tnslsnr status like in 6.5 if you have an issue with the previous item processing. If tnslsnr stopped please kill tnslsnr (6.6) and then start listener like in 6.3. 
6. Verify connectivity to Oracle instance from AppBase VM, using sqlplus or sql developer or at least telnet 1521 port like in 4.

6. Working with Oracle Net Listeners

6.1 Getting the List of Oracle Net Listeners

Run the following command to determine the listener name and Oracle home directory for the Oracle Net listener that you want to work:

[oracle@oracle12 ~]$ ps -ef | grep tnslsnr

In this sample output, LISTENER the names of the listener.

[oracle@oracle12 ~]$ more $ORACLE_HOME/network/admin/listener.ora

6.2 Stopping an Oracle Net Listener

To stop an Oracle Net listener:

1. Run the following command to stop default Oracle Net listener:
   

   [oracle@oracle12 ~]$ lsnrctl stop

   
   
   

   Optional

   2. If required, set and check the ORACLE_HOME environment variable to specify the appropriate Oracle home directory for the listener that you want to stop (any you got in the item  6.1 ):
   

   [oracle@oracle12 ~]$ export ORACLE_HOME=/u01/app/oracle/product/12.2.0/dbhome_1
   [oracle@oracle12 ~]$ echo $ORACLE_HOME

   

   3. Run the following command to stop any other Oracle Net listener:

   [oracle@oracle12 ~]$ $ORACLE_HOME/bin/lsnrctl stop LISTENER

   

6.3 Restarting an Oracle Net Listener

To start an Oracle Net listener:

1. Run the following command to restart default Oracle Net listener: 
   

   [oracle@oracle12 ~]$ lsnrctl start

   
   
   

   Optional

   2. If required, set the ORACLE_HOME environment variable to specify the appropriate Oracle home directory for the listener that you want to start (any you got in the item 6.1):
   

   [oracle@oracle12 ~]$ export ORACLE_HOME=/u01/app/oracle/product/12.2.0/dbhome_1
   [oracle@oracle12 ~]$ echo $ORACLE_HOME

   

   3. Run the following command to restart any other Oracle Net listener:

   [oracle@oracle12 ~]$ $ORACLE_HOME/bin/lsnrctl start LISTENER

   

6.4 Checking an Oracle Net Listener status

To review status of an Oracle Net listener:

1. Run the following command to get status of default Oracle Net listener: 
   

   [oracle@oracle12 ~]$ lsnrctl status

   Below sample shows stopped listener status

   
   
   

   Optional

   2. If required, set the ORACLE_HOME environment variable to specify the appropriate Oracle home directory for the listener that you want to get status (any you got in the item 6.1):
   

   [oracle@oracle12 ~]$ export ORACLE_HOME=/u01/app/oracle/product/12.2.0/dbhome_1
   [oracle@oracle12 ~]$ echo $ORACLE_HOME

   

   3. Run the following command to get status of any other Oracle Net listener:
   

   [oracle@oracle12 ~]$ $ORACLE_HOME/bin/lsnrctl status LISTENER

   

6.5 Checking an Oracle Net Listener process tnslsnr status

If you have an issue with listener management e.g. lsnrctl <command> hangs 

so you need to review the status of an Oracle Net listener process tnslsnr. To get the process status run following command:

[oracle@oracle12 ~]$ ps -eo 'tty,pid,comm,state'  | grep tnslsnr

If process tnslsnr is running you gets output like below

If process tnslsnr is stopped then you gets output like below

6.6 Killing an Oracle Net Listener process tnslsnr

If you have an issue with listener management e.g. lsnrctl <command> hangs and tnslsnr stopped (see 6.5) you need to kill tnslsnr to be able to start listener again.

To kill of an Oracle Net listener process tnslsnr run following command:

[oracle@oracle12 ~]$ kill -9 22738

then check tnslsnr status like in 6.5

For more information on managing listeners, see https://docs.oracle.com/cd/B28359_01/server.111/b32009/strt_stp.htm#UNXAR157

7. Stopping an Oracle Database or Automatic Storage Management Instance

To stop an Oracle Database or Automatic Storage Management instance:

1. If required, run the following command to switch in the oracle user context:
   

   [root@oracle12 ~]# sudo su - oracle

   
   

   

2. Run the following commands to run sqlplus and connect to DB instance:
   

   [oracle@oracle12 ~]$ sqlplus / as sysdba

   

3. Run the following command to shut down the instance:
   

   SQL> SHUTDOWN NORMAL

    
   After the instance shuts down, you can quit SQL*Plus.
   To know more about shutdown options see https://docs.oracle.com/cd/B19306_01/server.102/b14231/start.htm

8. Troubleshooting Oracle start

1. When starting AppBase, the software might report Oracle "ORA-12541: TNS:no listener", "ORA-12505: TNS:listener does not currently know of SID given in connect descriptor" errors.

   In this case please perform the following steps:

   a) Start an Oracle DB server like in 5.

   b) Check lsnrctrl status like in 6.4. If required perform lsnrctrl start like in 6.3.

   c) Check tnslsnr status like in 6.5 if you have an issue with the previous item processing. If tnslsnr stopped please kill tnslsnr (6.6) and then start listener like in 6.3. 

   d) Verify connectivity to Oracle instance from AppBase VM, using sqlplus or sql developer.

Troubleshooting AppBase Installation

1. When executing Oracle queries, the software might report ORA-03113 error. Please refer to Configuring Oracle Listener for instruction how to fix this.