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:
|
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:
|
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/*