Installing Ephesoft Transact 2019.1 – Single-server – Linux – Fresh 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 normal

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 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 app in a browser.

Installation Process

1. Complete the Prerequisites Check

  • 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

An internet connection is required as some software will need to be updated or installed from the OS repository during the Ephesoft Transact installation.

  • 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 2019.1 can be installed with MariaDB, or Oracle database. If Transact is installed with Oracle, the database must be installed and configured prior to installing Ephesoft Transact.
  • Ephesoft Transact 2019.1 can be installed with LDAP, Microsoft Active Directory, or Tomcat. If Ephesoft Transact is installed with Active Directory, MSAD must be already installed and configured prior to installing Transact.

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. To gain super-user permissions, run the sudo su root command. Next, use the chmod 777 command for the install, install-helper, and uninstall files to make them executable, or use the chmod -R 777 * command.

Note: If the installation process is started without obtaining the super-user permissions, one of the following messages will be displayed depending on the OS:

  • “Permission Denied”
  • “Please run Ephesoft installation script with super user permissions”

4. To start the installation process, use the ./install command. Next, select n as we are not using silent installer.

5. The installer will check the internet connection. The installation will be interrupted if an internet connection is unavailable as some software requires update or installation from the OS’s repository during the Ephesoft Transact installation. The installer will then proceed to confirm the Linux operating system.

6. Confirm you want to proceed as a root user by selecting n.

This message can differ slightly depending on the prior commands:

  • “Ephesoft Application will run as <current user>. Do you want to change it?”
  • “Ephesoft Application will run as root. Do you want to change it?”

If you want to change the user, select y and provide required information.

The following table further describes the configurable properties:

Configurable property Description
New user name Username for a new user to run the application
Password Valid password for a new user to run the application
Primary group Primary user group for a new user, which will give them required permissions (read, write, and execute):

  • If the group exists, the new user will be added to it
  • If the group doesn’t exist, it will be created with the provided name

7. Enter the path for the target installation directory. By default, it is /opt. You can change the directory or confirm the default option by clicking Enter.

8. Since this is a fresh installation, confirm that you need to install the SharedFolders instance by selecting n.

9. Specify where to install the SharedFolders. By default, it is /opt/Ephesoft. If you would like to designate another folder, answer y here and provide the location. Otherwise leave n and click Enter.

10. Confirm the server name that will be saved in the properties files. By default, the hostname is automatically identified, however, you can manually change the IP address, if needed.

Note: To confirm your server name, run the hostname command.

11. Select the database. MariaDB is shipped with the Ephesoft Transact installer. For Oracle, you need to have an Oracle database already installed and configured.

Available database options are explained below:

MariaDB

  • Select MariaDB by pressing 1 and clicking Enter.
  • To create a new database, press y. If you are using existing database, press n and provide required details as explained below.
  • Press y if you need to change any details, otherwise select n to continue.

The following table further describes the configurable properties:

Configurable property Description
Database port number Port number that will be used to access the database
Password for the root user Password that will be used to log in as a root user
Ephesoft admin username Username for the administrator of three Ephesoft databases (Application, Report, Report Archive)
Admin password Password that will be used to log in as a database administrator
Application database name Name for the application database can be changed as needed. By default, ephesoft
Report database name Name for the Report database can be changed as needed. By default, report
Report archive database name Name for the Report Archive database can be changed as needed. By default, report_archive

Oracle DB

  • Select Oracle by pressing 2 and clicking Enter.
  • To create a new database schema, press y. If you are using an existing Oracle schema, press n and provide required details as explained below.
  • Press y if you need to change any details, otherwise select n to continue.
  • Run the database patch by pressing y. The database patch is mandatory for a single-server installation. In case of multi-node installation, the database patch must be run only on the first server, and the n option can be selected for all remaining servers in the cluster.

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

The following table further describes the configurable properties:

Configurable property Description
Oracle hostname/IP Hostname/IP for accessing Oracle database
Username Username for the user of Oracle database
Password Password that will be used to access Oracle database
Port Port that will be used to access the Oracle database
Connection mode Oracle SID – Oracle System ID used to uniquely identify database on a system

Service Name – TNS alias used to remotely connect to the database

Application DB Schema Schema of the Application database, can be changed as needed. By default, ephesoft
Application DB Schema Password Password that will be used to access the Application database
Report DB Schema Schema of the Report database, can be changed as needed. By default, report
Report DB Schema Password Password that will be used to access the Report database
Report Archive DB Schema Schema of the Report Archive database, can be changed as needed. By default, report_archive
Report Archive DB Schema Password Password that will be used to access the Report Archive database

12. Select Authentication mode.

13. Select Application Protocol.

14. Enter the port number for the Tomcat server.

If any changes are needed, press y and update the details. Otherwise, click n to continue.

15. Select the User Connection type. LDAP and Tomcat are shipped with the Ephesoft Transact installer. If you want to use Microsoft Active Directory, MSAD must be already installed and configured by the user prior to installing Ephesoft Transact.

Available user connection types are explained below:

LDAP:

  • Select LDAP by pressing 1 and clicking Enter.
  • Provide required details as explained below.
  • Press y if you need to change any details, otherwise select n to continue.

The following table further describes the configurable properties:

Configurable property Description
Connection URL Valid URL to connect to LDAP server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Connection Name Valid username to connect and access LDAP server (the username of the user responsible for interacting with the server).
Connection Password Valid password to connect and access LDAP server (the password of the user responsible for interacting with the server).
User Base Relative path under which all the users’ information will be located. This attribute defines where to look for a user.
User Search Search string for searching users.
User Subtree 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.
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.
Role Name Role name defines which attribute is used for a role.
Role Search Search string for searching roles.
Role Subtree 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.
Super admin group name Group name for users with super admin privileges like access to the entire functionality of Ephesoft. The users in the group will be called super admin users and they can assign the user roles from the Ephesoft UI > System Configuration > Access Manager screen to the other users who belong to different groups and are not part of the super admin group.

MS Active Directory

  • Select MS Active Directory by pressing 2 and clicking Enter.
  • Provide required details as explained below.
  • Press y if you need to change any details, otherwise select n to continue.

The following table further describes the configurable properties:

Configurable property Description
Connection URL Valid URL to connect to Active Directory server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Connection Name Valid username to connect and access Active Directory server (the username of the user responsible for interacting with the server).
Connection Password Valid password to connect and access Active Directory server (the password of the user responsible for interacting with the server).
User Base The relative path under which all the users’ information will be located. This attribute defines where to look for a user.
User Search Search string for searching users.
User Subtree 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.
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.
Role Name Role name defines which attribute is used for a role.
Role Search Search string for searching roles.
Role Subtree 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.
MS AD 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.

Super admin group name Group name for users with super admin privileges like access to the entire functionality of Ephesoft. The users in the group will be called super admin users and they can assign the user roles from the Ephesoft UI > System Configuration > Access Manager screen to the other users who belong to different groups and are not part of the super admin group.

Tomcat

  • Select Tomcat by pressing 3 and clicking Enter.
  • Press y if you need to change any details, otherwise select n to continue.

16. Install Tesseract by pressing y and provide registration details.

17. The installation process will continue automatically to install and upgrade other applications used by Ephesoft Transact such as LibreOffice, Ghostscript, ImageMagick, Nuance, and POCO.

Note: If installation process is interrupted at any point due to internet connectivity issues, you can restart the installation process by running the same ./install command. To check the installation logs and see the installation status, you can use the following command:

tail -f /var/log/install-ephesoft.log

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 or warning is received, you will need to open the firewall ports to connect to Ephesoft Transact.

Clicking on the Administrator or Operator icon and selecting any item in the available 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

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 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 the 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 installation. 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 installation process.

In Ubuntu, Ephesoft installation will turn the firewall (ufw) on after install. At the end of the installation, 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/*