Installing Ephesoft Transact 2019.1 -Single-server- Linux – Fresh Silent Installation

Overview

This document provides information on how to install Ephesoft Transact 2019.1 in the following environment:

  • Environment — single-server
  • Operating System — Linux
  • Installation type — fresh silent

The silent-mode installation allows the user to define installation configuration only once and then use it to duplicate the installation on many machines. The config.properties file defines all the details that are required for installation and that the user would normally provide during the interactive installation process.

The following tasks describe how to install Ephesoft Transact 2019.1 for Linux:

# Installation Task General Scope of Activity
1 Complete the Prerequisites Check Prepare for installation by gathering installation resources and verifying that the environment is supported.
2 Run the Ephesoft Transact Installer Provide required configurations in the config.properties file and run the Ephesoft Transact installer in the command line interface.
3 Install the Ephesoft Transact License Obtain and install the Ephesoft Transact license.
4 Install the Ephesoft Transact 2019.1 Hotfix Download and install the Ephesoft Transact 2019.1 hotfix.
5 Start the Ephesoft Transact Service Launch the Ephesoft Transact service.
6 Launch Ephesoft Transact 2019.1 Access Ephesoft Transact application in a browser.

Installation Process

1. Complete the Prerequisites Check

General Prerequisites

  • Supported operating systems:
    • Red Hat Enterprise Linux (RHEL) 7.0, 7.1, 7.2, and 7.3
    • Oracle Linux 7.1, 7.2 and 7.3
    • CentOS 7.0, 7.1, 7.2 and 7.3
    • Ubuntu 16.04 LTS
  • The installation script must be run with super-user permissions, otherwise an error message will be displayed, and the script will exit (use the root user).
  • Ephesoft Transact can be installed with a MariaDB or Oracle database on the Linux platform. If Ephesoft Transact is installed with Oracle, the database must be installed and configured prior to installing Ephesoft Transact.
  • Ephesoft Transact can be installed with LDAP, Microsoft Active Directory or Tomcat. If Transact is installed with Active Directory, MSAD must be already installed and configured prior to installing Ephesoft Transact.

Considerations for Silent Installation

When using the silent installation mode, the following considerations need to be kept in mind:

  • Silent installation requires the same amount of temporary disk space and uses the same temporary storage directories as a standard installation.
  • Silent installation takes the same amount of time as a standard installation.
  • Incorrect entries in the config.properties file can cause installation failures. To help the user determine the cause of a failure, the installer will validate entries before commencing the installation. If there is any incorrect entry, the installer will stop the installation process displaying the invalid entry.
  • Semi-colon or special characters must not be used in the config.properties file.

2. Run the Ephesoft Transact Installer

1. Download the Ephesoft Transact installer and save it on your Linux machine.
2. Unzip the Ephesoft Transact installer by navigating to the folder containing the .zip file and running the unzip command.

3. To install Ephesoft Transact, you need super-user permissions.

3.1. Run the sudo su root command

3.2. Use the chmod 777 command for the install, install-helper and uninstall files to make them executable. Alternatively, you can use the chmod -R 777 * command.

4. Open the config.properties file located in the Response-Files folder in any text editor by running vi or vim or nano command. Alternatively, you can use WinSCP to connect to your Linux server and open the file in any UI text editor app.

5. Edit the values for the parameters in config.properties to reflect required configuration. If using vi editor, run the i command to enter the insert mode to edit the content. All available parameters are explained in the config.properties file and also described below.

The following table further describes configurable properties:

Product, User, SharedFolders, Port, Server Configurations

Configurable property Description
input_product_name Name of the product being installed
input_service_name Service name of the product being installed
input_offline_install_mode This parameter is used to define the type of installation mode you want to use:

n – use online installation

y – use offline installation

If offline installation mode is selected, all dependencies must be already pre-installed and updated on your system. For more information, refer to How to Install Ephesoft on a RedHat 6.5 Server with No Internet Connection.

input_run_application_as_non_root_user This parameter is used to define the user to run the application:

n – run the application as the root user

y – run the application as the non-root user

input_use_existing_user This parameter is used to define whether an existing or a new non-root user will perform installation:

n – create a new non-root user

y – use an existing non-root user

input_application_user Username of the non-root user to run the application
input_application_user_password_required This parameter is used to define whether the password is required for the user:

n – the password is not required

y – the password is required

input_application_user_password Valid password for the user
input_application_user_group User group for the user
input_installation_directory Directory to hold installation files of the product
input_change_shared_folder_path This parameter is used to define whether to change the default SharedFolders path or not:

n – use the default SharedFolders path

y – provide a new SharedFolders path

input_changed_shared_folder_path Full path for the directory where you want to install SharedFolders
input_tomcat_port_number Port number to be used by Tomcat
input_change_server_name This parameter is used to define whether the server name needs to be changed:

n – use the default server name

y – change the server name

input_changed_server_name Changed server name

Database Configurations

Configurable property Description
input_database_type The type of database to be configured or installed:

  • MariaDB
  • Oracle
input_new_database_instance This parameter is used to define whether you want to create a new database instance or to use an existing one:

n – create a new database instance

y – use an existing database instance

Properties for MariaDB
input_system_ip_name IP address of the server on which the existing database is located
input_database_username Username to access the existing database instance
input_database_port_number Port number that will be used to access the database
input_database_password Password to access the existing database instance
input_admin_database_username Username for the administrator of three Ephesoft databases (Application, Report, Report Archive)
input_admin_database_password Password that will be used to log in as a database administrator
input_application_database_name Name for the Application database can be changed as needed. By default, ephesoft
input_report_database_name Name for the Report database, can be changed as needed. By default, report
input_report_archive_database_name Name for the Report Archive database, can be changed as needed. By default, report_archive
Properties for Oracle Database
input_new_database_schema This parameter is used to define whether you want to create a new database schema or to use an existing one:

n – use an existing database schema

y – create a new database schema

input_oracle_database_username Username for the user of Oracle database
input_oracle_database_password Password that will be used to access Oracle database
input_oracle_database_server_name Server name for accessing Oracle database
input_oracle_database_port_number Port that will be used to access the Oracle database
input_oracle_database_connection_mode The way to connect to Oracle database:

  1. Oracle SID
  2. Service Name
input_oracle_database_sid Oracle System ID used to uniquely identify database on a system
input_oracle_database_service_name TNS alias used to remotely connect to the database
input_oracle_database_application_db_schema Schema of the Application database, can be changed as needed. By default, ephesoft
input_oracle_database_application_db_password Password that will be used to access the Application database
input_oracle_database_report_db_schema Schema of the Report database, can be changed as needed. By default, report
input_oracle_database_report_db_password Password that will be used to access the Report database
input_oracle_database_report_archive_db_schema Schema of the Report Archive database, can be changed as needed. By default, report_archive
input_oracle_database_report_archive_db_password Password that will be used to access the Report Archive database

Authentication Mode Configurations

Configurable property Description
input_authentication_mode The type of authentication mode you want to use:

1 for Form Authentication

2 for PKI Authentication

Properties for Form HTTP/HTTPS Authentication
input_application_communication_protocol The communication protocol, which will be used for Form Authentication:

1 for HTTP

2 for HTTPS

input_form_https_keystore_cert_path Path to the keystore certificate with SSL information.

Required only if HTTPS is selected.

input_form_https_keystore_cert_password Password for the keystore certificate with SSL information.

Required only if HTTPS is selected.

Properties for PKI Authentication
input_pki_server_cert_path Location of the server certificate.
input_pki_server_cert_password Password for the server certificate.
input_pki_ca_cert_path Location of the certifying authority certificate.
input_pki_ca_cert_password Password for the certifying authority certificate.
input_pki_alias_name Unique string to identify the keystore entry.
input_pki_connector_port_number Number of the PKI connector port.
input_pki_connector_ssl_protocol Protocol that will be used to secure connection between the client and the server.
input_pki_connector_ssl_enabled_protocol Supported versions of selected protocol.
input_pki_connector_chipper_text Algorithm of encryption that will be used between the client and the server.
input_pki_username_retriever One of the user name retriever parameters from the certificate:

1 for CN

2 for PrincipalName

3 for RFC822Name

4 for RegisteredID

User Connectivity Configurations

Configurable property Description
input_connectivity_user_connection The type of connection you want to use for the application.

1 for LDAP

2 for MS Active Directory

3 for Tomcat

Properties for Both LDAP/MSAD
input_realm_super_admin_group_name Name of the super-admin group.
input_realm_connection_url Valid URL to connect to LDAP and Active Directory server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
input_realm_connection_name Valid username to connect and access LDAP and Active Directory server (the username of the user responsible for interacting with the server).
input_realm_user_password Valid password of the user responsible for interacting with the server.
input_realm_user_base Relative path under which all the users’ information will be located. This attribute defines where to look for a user.
input_realm_user_search Search string for searching users.
input_realm_user_sub_tree This attribute defines the search scope. Set to true to search the entire subtree rooted at the user base entry. Set to false to request a single-level search including only the top level.
input_realm_role_base Relative path under which all the roles information will be located. This attribute defines where to look for a role corresponding to a user.
input_realm_role_name Role name defines which attribute is used for a role.
input_realm_role_search Search string for searching roles.
input_realm_role_sub_tree This attribute defines the search scope. Set to true to search the entire subtree rooted at the Role base entry. Set to false to request a single-level search including only the top level.
Properties Specific to MSAD
input_msactivedirectory_group_search_filter This attribute helps to filter search results and can have the following operators: |(OR), &(AND) and !(NOT). For example, ((!(cn=a*))(|(cn=ephesoft*)(&(cn=b*)))

This parameter is optional and can be left empty.

Other Configurations

input_install_tesseract This parameter is used to define whether Tesseract will be installed on your system or not:

n – skip installation of Tesseract

y – install Tesseract

input_existing_shared_folder This parameter is used to define whether you want to use existing SharedFolders:

n – do not use existing SharedFolders

y – use existing SharedFolders

input_existing_shared_folder_path Path for existing SharedFolders if the value of the previous parameter is y
input_database_patch_enable This parameter is used to define whether to run the database patch:

n – do not run the database patch

y – run the database patch

The database patch is mandatory for a single-server installation. In case of a multi-node installation, the database patch is run only on the first server, and the n option can be selected for all remaining servers in the cluster.

If you select n for a single server, the installation process will continue, however, there could be errors when running database queries.

input_upgrade_application This parameter is used to define whether the application is being upgraded from an older version:

n – do not upgrade the application

y – upgrade the application

input_forcefully_stop_running_server This parameter is used to define whether to stop the Ephesoft server during the upgrade:

n – do not stop the server. If Ephesoft server is running then this will exit the script

y – stop the Ephesoft server if Ephesoft server is running while upgrade is in process

input_install_multiserver This parameter is used to define whether Ephesoft Transact is installed in a multi-server environment:

n – single-server environment

y – multi-server environment

input_mounted_sharedfolder_path Full path for the mounted SharedFolders
input_user_registration_name Product registration info: user name
input_user_registration_company Product registration info: company name
input_user_registration_department Product registration info: department name
input_user_registration_street Product registration info: street
input_user_registration_city Product registration info: city
input_user_registration_state Product registration info: state
input_user_registration_country Product registration info: country

6. Save the updated config.properties file without changing its name in the Response-Files folder. If using vi editor, press ESC to exit from the insert mode and use the :wq command to save and close the file.
7. Navigate to the folder with the unzipped Ephesoft Transact installer and start the silent installation process by running the ./install -silentinstall -product command.

All required details will be picked up by the installer from the config.properties files.

If you want the installation process to run in the background without displaying details in the terminal, you can configure the silent installer as a custom installer as described in the Appendix below.

3. Install the Ephesoft Transact License

1. Navigate to /opt/Ephesoft/Dependencies/licensing and send the details.properties file to licenses@ephesoft.com.

Be sure to note that your installation is a Linux installation and advise the Ephesoft licensing team of the number of CPU cores on the server. If you are not sure how many CPU cores your server has, type nproc in the terminal and it will give you the number of cores as an output.

2. The Ephesoft licensing team will send you a file named ephesoft.lic. Save it to the following folder: /opt/Ephesoft/Dependencies/license-util/ephesoft-license-installer/

3. Navigate to the folder /opt/Ephesoft/Dependencies/license-util/ephesoft-license-installer, and run the ./install-license.sh file to install the Ephesoft Transact license.

Important: You need to have super-user permissions to install the Transact license.

The license is installed.

4. Install the Ephesoft Transact 2019.1 Hotfix

Once Ephesoft Transact is installed and licensed, you need to install the Ephesoft Transact 2019.1 hotfix, which includes important updates and improvements.
Important: This hotfix must be installed to ensure proper Ephesoft Transact functionality.

To install the hotfix:

1. Download the 2019.1_Fix_Pack.zip file, save it to a temporary location and unzip it.
2. Copy the extracted dcma-batch-*, dcma-util-*, dcma-recostar-*, gxt-core-*, gxt-review-validate-* JAR files to the <Ephesoft Installation Directory>\Application\WEB-INF\lib\HOT-FIXES directory.
3. Back up the existing reviewValidate and bm folders present in the <Ephesoft Installation Directory>\Application\ directory.
4. Copy the extracted reviewValidate and bm folders to the <Ephesoft Installation Directory>\Application\ directory.

For more information, refer to Ephesoft Transact 2019.1 Hotfix.

5. Start the Ephesoft Transact Service

1. Run the sudo service ephesoft start command.
2. You can open the catalina.out file in the /opt/Ephesoft/JavaAppServer/logs/ folder to track the service start-up process. For that, run the following command: tail -f catalina.out (the screenshot below shows extracts from the log file).

6. Launch Ephesoft Transact 2019.1

Open your browser and access the application using the following URL:

http://<server name>:<port number>/dcma/home.html.

If any connection error/warning is received, you will need to open the firewall ports to connect to Ephesoft Transact.

Clicking on the Administrator or Operator icon will take you to the login screen. The username is ephesoft and the password is demo.

Note: If you installed Ephesoft Transact with Active Directory, use the username and password provided for AD.

Once you have authenticated, you have completed the installation and configuration with your choice of database and authentication type.

Appendix

Configuring Silent Installer as a Custom Installer

The silent installer can also be configured as a custom installer. In the custom installer, the Linux admin can create pre-processing and post-processing script. In pre-processing and post-processing script, the user can populate the config.properties file, and execute the silent installation script command as a background process. It is recommended to execute the installation script as background process to skip the trail logs in the terminal.

For example, the Linux admin can use the following script to install Ephesoft Transact in the background silently:

In this script, the user can check if the process is finished via $pid or using the installation.log file which is created in the present working directory as soon as the silent installation process is finished. In case of the successful installation, the installation_status property will be set as success and in case of any error or exception this property will be set as failure in the log file with the error message.

Ephesoft Transact Service Overview and Commands

A Linux service is an application (or set of applications) that runs in the background waiting to be used or to complete essential tasks. By default, the Ephesoft Transact service is added to the start-up. This means that Ephesoft Transact will be in the running state if the user reboots the system. If required, the user can disable the Ephesoft Transact service by running the disable command.

All commands that can be used to manage the Ephesoft Transact service are defined below:

Sr. No. Command Description
1 start Starts the Ephesoft service.
2 stop Stops the Ephesoft service.
3 restart First stops the service and then starts the service.
4 status Tells the status of the Ephesoft service.
5 disable Disables the service and removes it from start-up.
6 enable Enables and adds the service to start-up.

To run the command, use the following pattern:

service ephesoft [command]

Important: Ephesoft service should be run with super-user permissions.

Ephesoft Transact server commands as seen in the terminal:

1. service ephesoft start

2. service ephesoft stop

3. service ephesoft restart

4. service ephesoft status

5. service ephesoft disable

6. service ephesoft enable

Troubleshooting

  • If the Ephesoft Transact installer stops with an error during any step of the installation process, please send the following files to Ephesoft Support at tickets@ephesoft.com and include the distribution and version of Linux on which you are installing.

/var/log/install-ephesoft.log

/etc/Ephesoft/ephesoft.conf (only root user has access to this folder, if the file does not exist, send only the first file)

  • If you do not have root or sudo permissions on the server, please contact your system administrator for permissions and instructions.
  • If installing SharedFolders directory on a remote server/NAS/SAN, please advise your system administrator to mount the share locally to your server and use the path they provide during the install. You can contact support for assistance if you run into issues with this. Persistent mount of the share on the local server will be necessary for Ephesoft to function.

Notes:

Although Ephesoft Transact may support other Ubuntu and RHEL based distributions, we have not tested them all. Please contact support at tickets@ephesoft.com before attempting an installation so that we can advise you of any changes that may need to be made during the install process.

In Ubuntu, Ephesoft installation will turn the firewall (ufw) on after install. At the end of the install, if you want ufw turned off, please remember to turn it off again with the command sudo ufw disable.

When shutting down the Ephesoft Transact service in Ubuntu, use the command sudo /opt/Ephesoft/JavaAppServer/bin/shutdown.sh.

After you install Ephesoft Transact and before you run the application for the first time, run the following commands (dos2unix is installed by Ephesoft):
sudo dos2unix /opt/Ephesoft/JavaAppServer/conf/*
sudo dos2unix /opt/Ephesoft/JavaAppServer/bin/*