7 Installing ASAP

This chapter describes how to install Oracle Communications ASAP. Before installing ASAP, read these chapters:

About Installing the ASAP Software

Note:

The term ASAP Server is used throughout this chapter when addressing all ASAP servers collectively.

Oracle recommends that you back up the Oracle WebLogic Server core software and the WebLogic Server domain before installing ASAP. For installation, ASAP must be linked to an as-yet unused WebLogic Server domain. If the ASAP installation fails, and you have not backed up the WebLogic Server domain information, you must recreate the WebLogic Server domain before installing ASAP. See "Creating a Backup of the WebLogic Server."

Note:

Before installing a new version of ASAP, Oracle recommends that you back up all data.

Prerequisites for Installing ASAP

The prerequisites for installing ASAP are:
  • Weblogic Server: Ensure the WebLogic Server domain has been created and the required server instance has been configured.
  • Database Planning: Ensure the required Database client is installed on the Linux VM and also that the Database is up and running.
  • Java: Ensure that you are using Java version 17. Refer to the ASAP Compatibility Matrix for specific minimum update requirements. Also, ensure that you have set the JAVA_HOME_ASAP environment variable.
  • Apache Ant: Ensure that the required version of Ant is installed.

Downloading the ASAP Installation Files

ASAP installation package is offered as a RedHat Package Manager (RPM) package. On Linux systems, you install the ASAP RPM package using the RPM package manager or the DNF.

Leveraging DNF, you can install the ASAP Installer on your Linux machines. DNF installation offers comprehensive traceability, enabling you to track the installation of different ASAP versions and their respective installation locations.

Regardless of the chosen tool, it is recommended that you override the default installation location. This ensures that you can easily access patches and version upgrades in the future. Additionally, overriding the installation location facilitates upgrade preparation and rollback scenarios.

To download the ASAP package installer:
  1. Download the ASAP software for your operating system from the Oracle software delivery website, located at:
     https://edelivery.oracle.com/
  2. Save the downloaded file (for example, ASAP.R7_4_1.Bxxx.linux.tar) to a temporary directory.

Configuring, Backing Up, and Starting WebLogic Before Installing ASAP

To configure, backup, and start the WebLogic server, use the following procedure:

Note:

When you start your WebLogic Server instance, make sure that the ASAP_home/Environment_Profile has not been sourced in your WebLogic server terminal session. This file references environment variables that are incompatible with your WebLogic server. In the context of this procedure, ASAP has not been installed, and this scenario is not possible; however, it can occur after you have installed ASAP.

  1. Archive your WebLogic Server domain. For example,

    cd domain_home/
    tar cf domain_name.tar domain_home/
    

    Where domain_name is the name you want to give your WebLogic Server domain backup file.

  2. Start the WebLogic server. You can use nohup to run your WebLogic server in the background.

    cd domain_home/
    nohup ./startWebLogic.sh &
    
  3. Monitor the nohup.out file to make sure the domain goes into the RUNNING mode.

    tail -f nohup.out
    

    The output from this command should end with the following text when it enters the RUNNING mode.

    <Jul 15, 2014 2:50:29 PM EDT> <Notice> <WebLogicServer> <BEA-000360> <Server started in RUNNING mode>
    
  4. Stop the tail process.

    Ctrl-C
    
  5. Exit from your oracle user session.

    exit
    

Re-Running the ASAP Server Installation

Note:

Oracle recommends a new complete installation in case of a failed installation. Re-running a failed installation will result in another failed installation.

To re-run the ASAP Server installation:
  1. Stop the WebLogic Server:

    cd domain_home/bin
    ./stopWebLogic.sh -U wls_admin_user
    
  2. Remove the old WebLogic domain.

  3. Drop the Database as appropriate.

  4. Remove the installed RPM package by running the following commands:

    #Get the name of the rpm 
    rpm -q asap-installer 
    #Remove the RPM package
    rpm -ev rpm_name 
  5. Remove all the directories and files that were created by ASAP installation by running the following command:
    rm -rf 
  6. Perform a fresh complete installation of ASAP. See Installing an ASAP Demonstration System for the steps involved in performing a fresh complete installation.

Installing an ASAP Demonstration System

The instructions in this section assume that you are installing all of the ASAP components, including the database, on a single machine. This machine should meet the hardware requirements for Oracle Linux.

The procedure for installing a demonstration system include:

  1. Installing Oracle Linux with the Oracle Validated Package

  2. Preparing the Linux Environment

  3. Downloading and Extracting the ASAP Installation Files

  4. Downloading and Installing the Oracle Database and Client Software

  5. Configuring Database Listener

  6. Creating the Database Instance

  7. Creating Tablespace, Tablespace Users, and Granting User Privileges

  8. Downloading and Installing the WebLogic Server Software

  9. Creating and Configuring a WebLogic Server Domain

  10. Installing ASAP

  11. Configuring ASAP

Installing Oracle Linux with the Oracle Validated Package

Use the following procedure to install Oracle Linux with the Oracle validated software package.

  1. On a Windows workstation, launch Internet Explorer and log in to the Oracle software delivery website.

  2. Select and download the Oracle Linux version required for the x86 64 bit platform (see ASAP Compatibility Matrix).

  3. Install Oracle Linux on an x86 64 bit platform.

  4. Select default installation options until you reach the page where you get the option to customize your installation. Select the Customize now, and click Next.

  5. Select Base System from the left menu.

  6. Select System Tools from the right menu.

  7. Click Optional packages.

  8. Select the Oracle Validated RPM package from the package list, and click Next.

    This package provides the following features:

    • Preconfigured Oracle Linux kernel configuration, suitable for the Oracle database. These kernel configuration attributes are sufficient for an ASAP demonstration system; however, for a production environment or test system, configure your kernel parameters as described in "Setting Linux Kernel Parameters."

    • All Oracle packages required to install and run the Oracle database software.

    • Preconfigured Oracle database user and groups for database installation.

  9. Click Close.

  10. Click Next and continue the installation process.

  11. During the Oracle Linux configuration process, select the following options:

    • Enable the firewall and set SSH, Telnet, and FTP as trusted protocols.

    • Set SELinux to Permissive.

    • Check Enable Network Time Protocol in the Network Time Protocol tab.

Preparing the Linux Environment

Use the following procedure to prepare your Oracle Linux environment. The steps described in this procedure include:

  • Installing the JDK for WebLogic Server

  • Creating a symbolic link to the JDK from Mozilla Firefox to enable the Java plugin

  • Creating an ASAP user and group

  • Configuring a host name for your installation in the /etc/hosts file

  • Creating the directories for your Oracle Database installation

  • Configuring the Oracle user .bashrc file

To prepare the Linux environment:

  1. Log in to Oracle Linux as root.

  2. For more information about the compatible versions, refer to the ASAP Compatibility Matrix.

  3. Change the permissions on the Java installation file:

    chmod a+x jdk_install_file
    

    Where jdk_install_file is the Java installation file.

  4. Move the file to a system-wide location such as /usr/local. For example:

    mv jdk_install_file /usr/local
    
  5. From the new location, install Java SE.

    ./jdk_install_file
    
  6. Create a symbolic link from the /usr/lib/mozilla/plugins directory to Java_home /jre/lib/i386/libnpjp2.so file (where Java_home is the location where you installed the JDK) to enable the Java plugin for Mozilla Firefox. For example:

    cd /usr/lib/mozilla/plugins
    ln -s /usr/local/jdk1.8.x/jre/lib/i386/libnpjp2.so 
    
  7. Create an ASAP user and group as described in "Configuring a UNIX ASAP Group and User."

  8. Determine the IP address for your platform.

    ifconfig
    
  9. Edit the /etc/hosts file and provide a host name for your IP address. For example:

    # Do not remove the following line, or various programs
    # that require network functionality will fail.
    127.0.0.1 localhost.localdomain localhost loopback
    ::1 localhost6.localdomain6 localhost6
    10.156.53.74 testsystem.oracle.us.com testsystem loghost
    
  10. Create and assign permissions to folders in preparation to install your Oracle database. For example:

    mkdir -p /u01/app/
    chown -R oracle:oinstall /u01/app/
    chmod -R 775 /u01/app/
    mkdir /u01/app/oradata /u01/app/fast_recovery_area
    chown oracle:oinstall /u01/app/oradata/u01/app/fast_recovery_area
    chmod 755 /u01/app/oradata /u01/app/fast_recovery_area
    
  11. Edit the Oracle user's .bashrc system setup file using a text editor such as gedit or vi. This example provides common Oracle database environment variables and paths:

    # .bashrc
     
    # Source global definitions
    if [ -f /etc/bashrc ]; then
    . /etc/bashrc
    fi
     
    # User specific aliases and functions
    export ORACLE_SID=ASAP
    export ORACLE_HOME=/u01/app/oracle/product/12.1.3/dbhome_1
    PATH=$PATH:$HOME/bin:/u01/app/oracle/product/12.1.3/dbhome_1/bin/
    export PATH
     
    umask 022

Downloading and Extracting the ASAP Installation Files

To download the ASAP installation files use the procedure described in "Downloading the ASAP Installation Files" with the following exceptions:

  • Log in to your Oracle Linux workstation with your asap user account.

  • Download the file directly to your Oracle Linux workstation.

  • For this demonstration system, create a new directory called asapinstaller in the /home/asap directory and extract the ASAP installation files in this directory. For example:

    cd /home/asap
    mkdir asapinstaller
    mv ASAP.R7_4_1.Bxxx.linux.tar asapinstaller/
    cd asapinstaller
    tar -xvf ASAP.R7_4_1.Bxxx.linux.tar
    

Downloading and Installing the Oracle Database and Client Software

Use the following procedure to download and install the Oracle database and client software.

  1. Log in as the Oracle user.

  2. Log in to the Oracle software delivery website.

  3. Select and download the Oracle Database version you require for the Linux x86-64 platform. For more information about the compatible versions, refer to the ASAP Compatibility Matrix.

    Note:

    Do not download the client from the Oracle software delivery website.

  4. Use the following command to extract the content from the installation files:

    unzip file_name.zip
    

    Where file_name is the name of the database installation file. There are typically two installation files.

  5. Run the database installer.

    ./database/runInstaller
    
  6. During the installation process select the default options for all fields except for the following:

    1. Install database software only

    2. Single Database Instance

    3. Enterprise Edition

  7. Follow the GUI instructions to finish the installation.

  8. Download and install the client as described in "Downloading and Installing the Oracle Client Software" using the default options for all fields except for the following:

    1. Select the Administrator Installation Type

    2. Enter /u01/app/oracle/product/19.3.0.0/client_1 for the Software Location

    3. Enterprise Edition

Configuring Database Listener

Use the following procedure to configure a database listener.

  1. Run the Network Configuration Assistant (netca).

    netca
    

    The Network Configuration Assistant: Welcome screen appears.

  2. Select Listener Configuration.

    The Network Configuration Assistant: Listener Configuration Listener screen appears.

  3. Select Add.

    The Network Configuration Assistant: Listener Configuration, Listener Name screen appears.

  4. Accept default LISTENER. Click Next.

    The Network Configuration Assistant: Listener Configuration, Select Protocols screen appears.

  5. Select Next to accept the default TCP selection.

    The Network Configuration Assistant: Listener Configuration, TCP/IP Protocol screen appears.

  6. Select Use the standard port number 1521. Click Next.

    The Network Configuration Assistant: Listener Configuration, More Listeners? screen appears.

  7. Select No. Click Next.

    The Network Configuration Assistant: Listener Configuration Done screen appears.

  8. Click Next.

  9. Click Finish.

Creating the Database Instance

Use the following procedure to configure a database instance.

  1. Run the Database Configuration Assistant (dbca).

    dbca
    

    The Database Configuration Assistant: Welcome screen appears.

  2. Click Next.

    The Database Configuration Assistant: Step 1 of 12: Operations screen appears.

  3. Select Create a Database.

  4. Click Next.

    The Database Configuration Assistant: Step 2 of 12: Database Templates screen appears.

  5. Select General Purpose or Transaction Processing.

  6. Click Next.

    The Database Configuration Assistant: Step 3 of 12: Database Identification screen appears.

  7. Enter ASAP for the Global Database Name and SID fields.

  8. Click Next.

    The Database Configuration Assistant: Step 4 of 12: Management Options screen appears.

  9. Click Next to accept the default options.

    The Database Configuration Assistant: Step 5 of 12: Database Credentials screen appears.

  10. Select Use the Same Administrative Password for All Accounts.

  11. Enter a Password in the Password and Confirm Password fields.

    Note:

    Mark down the password you used. You will need this password for the procedure described in "Creating Tablespace, Tablespace Users, and Granting User Privileges."

  12. Click Next.

    The Database Configuration Assistant: Step 6 of 12: Database File Locations screen appears.

  13. Click Next to accept the default options for storage type and location of data files.

    The Database Configuration Assistant: Step 7 of 12: Recovery Configuration screen appears.

  14. Click Next to accept the default flash recovery area options.

    The Database Configuration Assistant: Step 8 of 12: Database Content screen appears.

  15. Click Next to accept default options for Sample Schema and Custom Scripts tabs.

    The Database Configuration Assistant: Step 9 of 12: Initialization Parameters screen appears.

  16. Click Finish.

    The Create Database - Summary screen appears.

  17. Click OK to create your database.

  18. Click Exit.

Creating Tablespace, Tablespace Users, and Granting User Privileges

Use the following procedure to create a tablespace, tablespace user, and grant privileges.

  1. From the Unix terminal, log in to the database instance with the sys user account.

    sqlplus sys/password as sysdba
    

    Where password is the password you choose for your sys account (see "Creating the Database Instance").

  2. Run the following command to create your tablespace.

    CREATE TABLESPACE "POOL_TS" LOGGING DATAFILE '/u01/app/oracle/POOLS_TS.dbf' SIZE 6000M REUSE AUTOEXTEND ON NEXT 1000K MAXSIZE UNLIMITED DEFAULT STORAGE (INITIAL 128K NEXT 128K MINEXTENTS 1 MAXEXTENTS 2147483645 PCTINCREASE 0);
    
  3. Create a new user for the tablespace. For example:

    CREATE USER "ASAP_SYS" PROFILE "DEFAULT" IDENTIFIED BY "ASAP_SYS" DEFAULT TABLESPACE "POOL_TS" TEMPORARY TABLESPACE "TEMP" ACCOUNT UNLOCK;
    
  4. Grant privileges to your tablespace user account. For example:

    GRANT CREATE ANY CONTEXT TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE ANY TABLE TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE ANY VIEW TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE SNAPSHOT TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE SYNONYM TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE TABLE TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE USER TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT CREATE VIEW TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT GRANT ANY PRIVILEGE TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT QUERY REWRITE TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT UNLIMITED TABLESPACE TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT SELECT ON "SYS"."V_$PARAMETER" TO "ASAP_SYS" WITH GRANT OPTION;
    GRANT "CONNECT" TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT "DBA" TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT "EXP_FULL_DATABASE" TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT "IMP_FULL_DATABASE" TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT "RESOURCE" TO "ASAP_SYS" WITH ADMIN OPTION;
    GRANT EXECUTE ON SYS.DBMS_LOCK TO "ASAP_SYS" WITH GRANT OPTION;
    GRANT SELECT ON DBA_TABLESPACES TO "ASAP_SYS" WITH GRANT OPTION;
    
  5. Log out of sqlplus.

    exit
    
  6. Log in to the root user account from the Oracle user session.

    su root
    
  7. Copy the ora_system_procs.sh from the ASAP installation directory to the Oracle user account home directory.

    cd /home/asap/asapinstaller/asap_utils/
    cp ora_system_procs.sh /home/oracle
    
  8. Set permissions for the ora_system_procs.sh file.

    cd /home/oracle
    chmod 755 ora_system_procs.sh
    
  9. Log out of the root user session.

    exit
    
  10. As the Oracle user, run the ora_system_procs.sh script.

    cd /home/oracle
    ./ora_system_procs.sh
    
  11. Enter Y and press Enter to continue.

  12. Enter the password you created for your sys database user account (see "Creating the Database Instance") and press Enter.

    Note:

    The script may produce the following error message.

    drop public synonym set_session
    *
    ERROR at line 1:
    ORA-01432: public synonym to be dropped does not exist
    

    Ignore this message.

  13. Become root user.

    su root
    
  14. Copy the Database tnsnames.ora file to your asap user account home directory.

    cp /u01/app/oracle/product/19.3.0/dbhome_1/network/admin/tnsnames.ora /home/asap
    
  15. Change the permissions on the tnsnames.ora file.

    cd /home/asap
    chmod 755 tnsnames.ora
    
  16. Log out of root user.

    exit
    
  17. Log out of Oracle user.

    exit
    

Downloading and Installing the WebLogic Server Software

Use the following procedure to download and install the WebLogic Server software.

  1. Log in as the asap user.

  2. Log in to the Oracle software delivery website.

  3. Select and download the WebLogic version you require for the Linux x86-64 platform. For more information about the compatible versions, refer to the ASAP Compatibility Matrix.

  4. Change the permissions on the installation.jar file so that your WebLogic Server user can run it. For example:

    chmod a+x fmw_12.2.1.4_wls_lite_Disk1_1of1.zip
    
  5. If you are running X-Windows on a remote display, export the display. For example:

    export DISPLAY=10.15.16.17:0.0.
    
  6. Start the WebLogic installer. For example:

    cd /usr/local/jdk1.8.x/bin/
    ./java -jar /home/oracle/Desktop/fmw_12.2.1.4_wls_lite_Disk1_1of1.zip

    Note:

    Make sure you use ./ before the Java command to use the correct JDK.

  7. Click Next.

  8. Click Next to accept the default Middleware home directory (for example, /home/asap/Oracle/Middleware) and follow the installation instructions.

  9. Select the Custom installation type from the Choose Install Type screen.

  10. Click Next.

  11. Deselect the Coherence Server component from the component list.

  12. Click Next.

  13. Click Next to select the Local JDK (for example Sun SDK 1.8.x (/usr/local/jdk1.8.x)).

  14. Click Next to select the default product installation directory for your WebLogic Server (for example /home/asap/Oracle/Middleware/wlserver_12.2).

  15. Review the Installation Summary, and click Next to start the installation process.

  16. After the installation is complete, deselect Run Quickstart.

  17. Click Done.

Creating and Configuring a WebLogic Server Domain

Use the following procedure to create and configure a WebLogic Server domain.

  1. Log in as the asap user.

  2. Follow the procedure described in "Creating a WebLogic Server Domain" and select the default options except for those described in Table 7-1.

    Table 7-1 WebLogic Server Domain Demonstration System Installation Values

    Installer Screen Fields Value

    Specify Domain Name and Location

    Domain name:

    Domain location:

    basedomain

    /home/asap/Oracle/Middleware/user_projects/domains

    Configure Administrator User Name and Password

    Name:

    User password:

    Confirm user password:

    weblogic

    password

    password

    Select Optional Configuration

    Select only the Administrator Server option. This demonstration system does not require a managed server.

    N/A

    Configure the Administration Server

    Name:

    Listen address:

    Listen port:

    SSL listen port:

    Select SSL enabled.

    AdminServer

    All Local Addresses

    7001

    7002

  3. Configure, backup, and start the WebLogic server as described in "Configuring, Backing Up, and Starting WebLogic Before Installing ASAP."

Installing ASAP

You can install the ASAP Installer RPM package on Linux as an RPM or DNF file. RPM is a widely used utility for software installation on Linux systems. ASAP installer is distributed as an RPM relocatable package for Linux 64 bit architectures. The package will install all the required ASAP core files to the install location. The default install location is /usr/local/asap. You can also specify a custom install location using --prefix option.

Install Using RPM

To install ASAP using RPM:

  1. Login to the host machine where you want to install ASAP.

  2. Navigate to the directory where the ASAP installation package (ASAP.R7_4_1.Bxxx.linux.tar ) is extracted.

  3. Run the following command to install ASAP:
    • To install in the custom path:
      sudo rpm -ivh --prefix=/path/to/desired/installationdir /path/to/rpm/asap-installer-7.4.1-Bxxx.x86_64.rpm
    • To install in the default path (/usr/local/asap):
      sudo rpm -ivh /path/to/rpm/asap-installer-7.4.1-Bxxx.x86_64.rpm

    ASAP files are installed with the user:group that is used to log in to the machine.

  4. Run the following command to set the environment variable TNS_ADMIN:
    export TNS_ADMIN=/path/tnsnames.ora/file
  5. Set the JAVA_HOME_ASAP environment variable by using the following command:
    export JAVA_HOME_ASAP=/path/to/Java17
  6. The installer logs are found in ASAP_home/installer_logs. The database configuration logs are found in the ASAP_home directory.

Install Using DNF

When attempting to install a new version of the ASAP installer RPM package, DNF automatically handles the process of either downgrading or upgrading to the specific version. For example:
  • If ASAP installer build version B2566 is already installed and an older version, say version B2559 is being installed, DNF will replace or downgrade the existing version B2566 to version B2559.

  • Conversely, if build version B2559 is already installed and a newer version, say B2577 is being installed, DNF will replace or upgrade the existing version B2559 to version B2577.

To accommodate multiple versions of the ASAP installer, installroot option can be utilized with the dnf install command. This allows specifying a custom directory location. For example:
#install the RPM package using the dnf command 
$ sudo dnf install --installroot=/path/to/desired/installationdir/ /path/to/rpm/asap-installer-7.4.1-Bxxx.x86_64.rpm

Note:

Using DNF incurs a disk cost, as a new root file system is created for each custom location. Approximately 2.5 GB of disk space is required per location when using DNF.

Configuring ASAP

You can configure ASAP using:
  • Silent Mode
  • Console Mode

Configuring ASAP Using Silent Mode

In Silent mode, you can configure ASAP automatically by providing all the parameters in a configuration file. A sample can be found on ASAP_home/config directory as sampleASAPconfiguration.properties file. You can rename the file and provide all the configuration parameters. When the configureASAP script is run, the parameters are read from the configuration file provided as input to the script and set up accordingly.

To automatically configure ASAP in the silent mode, run the configureASAP script located at ASAP_home/scripts directory:

configureASAP -properties /path/to/configuration/properties –d

where -d indicates the demo or silent mode. The values for all the parameters are read from the properties file, provided as input, to the configureASAP script in above command. See "Sample Configuration File" for the details on the parameters in the sample configuration file.

Configuring ASAP Using Console Mode

You can configure ASAP in the console mode by running the following command:
configureASAP -properties /path/to/configuration/properties
In the console mode, you must configure passwords in the command line when prompted for and rest of the parameters are read from the properties file. A sample can be found on ASAP_home/config directory as sampleASAPconfiguration.properties file. You can rename the file and provide all the configuration parameters. When configureASAP script is run, the parameters are read from the configuration file, provided as input to the script and set up accordingly. Oracle recommends that you use console mode for configuring ASAP. See "Sample Configuration File" for the details on the parameters in the sample configuration file.

Troubleshooting a Failed ASAP Installation

This section explains how to troubleshoot error messages that you may encounter during an unsuccessful ASAP installation.

Java Heap Space Exception Prevents ASAP Installation

A Java heap exception may be caused because the physical memory, CPU speed, or the quantity of CPUs is less than the minimum requirements. The JVM, which is initiated by the ASAP installer to deploy the EAR file, runs out of memory and returns the Java heap space exception in the log.

Ensure that your system meets or exceeds the minimum requirements, as outlined in "ASAP Server Hardware Requirements."

If you discovers a Java heap space exception in the installation log after a failed ASAP installation:

  1. Open the deployWbApp script file in the ASAP_home/scripts/ directory.

  2. Update the deployWbApp script by adding the following option:

    -Xmx128m
    
  3. Restart the installer by using the following command:

    java -Xmx128m -Xms128m weblogic.Deployer -adminurl WL_url -username WL_username -name WL_name -targets server_name -source EAR_file_path -upload -deploy