Transact

⌘K
  1. Home
  2. Transact
  3. Install and Upgrade
  4. Transact 2020.1.02
  5. Linux Installation Guide 2020.1.02

Linux Installation Guide 2020.1.02

Introduction

This document describes how to install Ephesoft Transact 2020.1.02 in the following environments:

  • Environment types — single or multi-server
  • Operating System — Red Hat Enterprise Linux (RHEL) 7.5 or 7.6

Note: Ephesoft Transact 2020.1.02 is only supported for these Linux distributions. Do not run the yum update command, as this updates RHEL to an unsupported version. Refer to How to Update to a Previous Version of RHEL for more information.

  • Installation types — normal or silent

Installation Overview

The process of installing Ephesoft Transact 2020.1.02 follows this general sequence of tasks.

Installation Task General Scope of Activity
Prerequisites  Prepare for the installation by gathering installation resources and verifying that the environment is supported.
Download and Run the Ephesoft Transact Installer  Run the Ephesoft Transact installer in the command line interface.
Select Normal or Silent Install Determine if you are performing a normal or silent installation and follow the steps for your selected option.
License and Launch Ephesoft Transact 2020.1.02 Perform these steps to complete the install for Ephesoft Transact 2020.1.02.

Prerequisites

Perform these steps to prepare for successful software installation and startup:

  1. Determine if you need to perform a single-server or multi-server installation.

Important: Installation steps unique to a multi-server installation are identified where applicable.

  1. Verify that your database version is supported. Refer to Platform Configuration and Third-Party Integrations and reference the 2020.1 table for additional information.
  2. The following database information is required when you run the installer:
    • Username and password
    • Database connection parameters

Important: The Ephesoft Transact 2020.1.02 installer does not install any database management systems (DBMS). You will need to install and configure any relevant DBMS prior to installing Ephesoft Transact 2020.1.02. If you’re installing Ephesoft Transact for the first time using MariaDB, reference Install and Migrate to MariaDB for Linux for additional information.

  1. Verify that internet connectivity is available for this installation.
nm-online

Note: The installation will be interrupted if an internet connection is unavailable, as some software requires updates or installation from the operating system’s repository.

  1. If you are installing Ephesoft Transact with Microsoft Active Directory (MSAD), MSAD must already be installed and configured prior to installing Ephesoft Transact.
  2. Verify that you have super-user (root) permissions. If you are not a super-user, execute the following command to gain super-user permissions.
sudo su root

Important: The installation script must be run with super-user permissions, or an error will occur, and the script will exit.

  1. Refer to How to Manually Install Microsoft’s TrueType Core Fonts and complete the steps for your Linux distribution.

Important: Ephesoft Transact requires Microsoft’s TrueType Core (msttcore) fonts to be installed when converting PDF to TIFF files. The msttcore fonts must be installed on the same processing server(s) as Ephesoft Transact.

User Instructions

Download and Run the Ephesoft Transact Installer

Perform these steps to run the Ephesoft Transact 2020.1.02 installer.

  1. Refer to the Downloads page for information on how to obtain the Ephesoft Transact installer.
  2. Unzip the Ephesoft Transact installer by navigating to the folder containing the .zip file and execute the following command:
unzip Ephesoft_Transact_2020.1.02_Linux.zip

If unzip is not installed, use the following command:

sudo yum install unzip

Figure 1. Execute the unzip command

  1. Run the following command to make the files executable:
chmod 777 install install-helper uninstall

This is illustrated in Figure 2, below.

Figure 2. Execute the cmod 777 Command

  1. Run the following command to start the installation process:
./install

Figure 3. Execute the ./install Command

Important: If the Ephesoft Transact installer stops or fails during any step of the upgrade process, contact Ephesoft Support at tickets@ephesoft.com and provide the following files and details:

    1. Your distribution and version of Linux.
    2. var/log/install-ephesoft.log
    3. /etc/Ephesoft/Ephesoft.conf
    • Only the root user has access to this folder. If the file does not exist, send only the first file.
    1. You will be prompted to decide if you want to install Ephesoft Transact as a silent installer (figure 4).
    • If you are performing a normal install, select n and proceed to Normal Install.
    • If you are performing a silent install, select y and proceed to Silent Install.

Figure 4. Execute the ./install command

Normal Install

  1. The installer will check the internet connection.
  2. After the installer runs a check on the Linux operating system, you will be prompted to change the detected operating system. In most cases, users select the operating system detected by the installer. Select n to keep the detected operating system.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-316.png

Figure 5. Installer Detects Operating System

  1. While you must be the root user to install Ephesoft Transact, you do not have to be the root user to run the application. You will be prompted to decide whether to run Ephesoft Transact as either root or non-root user with one of the following:
    • “Do you want to run Ephesoft Application as a non-root user?”
    • “Ephesoft Application will run as root. Do you want to change it?”
    • “Ephesoft Application will run as <current user>. Do you want to change it?”
  1. Select n for any option to proceed as a root user.
  2. Select y to change the user and provide the required information, as prompted by the installer.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-318.png

Figure 6. Change to non-root user

The following list further describes the configurable properties:

    • New username: 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 doesn’t exist, it will be created with the provided name.
  1. Input the path for the target installation directory. The default option is /opt. We recommend keeping the default directory, but you can change the directory by editing the text line if needed.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-319.png

Figure 7. Installation path

  1. Press the Enter key to confirm the listed path. The installer will extract the Ephesoft tar file and copy the Ephesoft folder to the installation directory. This may take some time.

Important: Never install Ephesoft Transact in the /home directory for a user, or in the /root, /bin, /etc, /sbin, /usr, or /boot directories.

Create SharedFolders

  1. You will be prompted to determine whether you want to use an existing instance of SharedFolders. If you are installing on a single-server environment, or if you are installing the first server in a multi-server environment, you will need to install SharedFolders for Ephesoft Transact to function properly.

Important: For Ephesoft Transact to function properly, SharedFolders must be accessible on the local server. If you are installing the SharedFolders directory on a remote server (network path)/NAS/SAN, advise your system administrator to mount the share locally to your server and use the path they provide during the installation.

    1. Press n if you are installing on a single-server environment, or if you are installing the first server in a multi-server environment.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-320.png

Figure 8. Install SharedFolders

    1. Press y if you are installing the second or subsequent server in a multi-server environment.
  1. You will be prompted to specify where to install SharedFolders. The recommended option is the default /opt/Ephesoft.
    1. Select n to keep the default /opt/Ephesoft option.
    2. Select y to designate a different folder and provide the chosen location. For single server installation, enter a local server directory path. For a multi-server installation, enter the path of a shared location.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-321.png

Figure 9. Change SharedFolders Path

  1. Press the Enter key to confirm the chosen folder.
  2. Confirm the server name that will be saved in the Properties files. The default server name is the OS hostname, which is automatically identified by the installer.

Note: If you want to confirm your hostname, run the following command:

hostname

This will display the current hostname of your Linux system.

    1. Select y to change the default server name.

Important: If you change the server name it must be to a fully qualified domain name (FQDN) that your Ephesoft Transact users will have access to. This allows browsers to resolve images correctly. For example, if your Linux hostname is server01 but you want users to access Ephesoft Transact via http://transact.ephesoft.com, change the server name to transact.ephesoft.com.

    1. Select n to keep the default server name.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-322.png

Figure 10. Default Hostname Selected

Select and Set Up the Database

You will be prompted to select the database type you want to use. This section will explain the available options for MariaDB and Oracle.

The following screen displays:

Figure 11. Select Database Type

MariaDB Configuration

Note: The installer does not install MariaDB as part of the installation process. You will need to configure the database for MariaDB prior to running the Ephesoft Transact installer. The installer allows you to connect to an existing MariaDB server during the installation of Ephesoft Transact. For the latest information about MariaDB version support and MariaDB installation, refer to these documents:

Follow these steps when setting up an existing MariaDB database during the installation of Ephesoft Transact.

  1. Select MariaDB by typing 1 and pressing the Enter key.

Figure 12. Provide MariaDB Details

  1. Provide the required details, as explained in the table below.
Maria DB property Description
system IP The hostname/IP address on which MariaDB is installed.
database username Enter root.

This is the username for the administrator of the three Ephesoft databases (ephesoft, report, and report_archive).

Admin password This is the password you created when installing MariaDB. This password will be used to log in as a database administrator.
application database name Default database name is ephesoft. This name can be changed as needed.

Important: Do not include special characters besides underscore “_”.

report database name Default report database name is report. This name can be changed as needed.
report archive database name Default report archive database name is report_archive. This name can be changed as needed.
database port number Default port number is 3306. This is the port that will be used to access the database.

Note: In the table above, the configurable properties are listed exactly how they display on the screen.

  1. Press y to change any details. Otherwise, press n to continue.

Figure 13. Change Details or Continue

  1. You have successfully configured MariaDB. Proceed to Run or Decline the Database Patch.
Oracle Database Configuration
  1. Select Oracle by typing 2 and pressing the Enter key.
    • Press y to create a new database schema. You will be prompted to configure several properties for the database. See the table below for details on configurable properties.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-324.png

Figure 14. Select Oracle DB

    • Press n to use an existing database. Provide the required details, as explained in the table below.
Oracle schema property Description
oracle hostname/IP Hostname/IP for accessing the Oracle database.
User Name Username for the user of the Oracle database.
Password The password that will be used to access the Oracle database.
Port The port that will be used to access the Oracle database.
connection mode Oracle SID: Oracle system identification used to uniquely identify the database on a system.

Service Name: TNS alias used to remotely connect to the database.

Application DB Schema Default application schema is ephesoft. This name can be changed as needed.

Important: Do not include special characters besides underscore “_”.

Application DB Schema Password Password that will be used to access the Application database
Report DB Schema Default report schema is report. This name can be changed as needed.
Report DB Schema Password Password that will be used to access the Report database
Report Archive DB Schema Default report archive schema is report_archive. This name can be changed as needed.
Report Archive DB Schema Password Password that will be used to access the Report Archive database.

Note: In the table above, the configurable properties are listed exactly how they display on the screen.

  1. Press y to change any details. Otherwise, press n to continue.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-324.png

Figure 15. Finalizing Oracle DB Details

  1. You have successfully configured the Oracle Database. Proceed to Run or Decline the Database Patch.

Run or Decline the Database Patch

Important: The following steps vary depending on a single or multi-server installation. Carefully read the steps below before proceeding further.

  • For single-server installation, press y to run the database patch. The database patch is mandatory for a single-server installation, or if you are installing the first server in a multi-server installation.
  • For a multi-server installation, the database patch is only required for the first server in the installation. Press n for subsequent server installations.

Important: If you run the database patch on the second or subsequent servers in a multi-server installation, you may corrupt the existing database.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-324.png

Figure 16. Database Patch Execution

Configure Authentication Mode

The following text displays:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-325.png

Figure 17. Authentication Configuration

The following text displays:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-326.png

Figure 18. Application Protocol Options

The following text displays:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-327.png

Figure 19. Apache Tomcat Server Port Number

  1. The default port number will display (8080 for HTTP).
  2. You will be prompted to change any details. Press y if any changes are needed. Otherwise, press n to continue.

Note: If you press y, you will need to re-input all the information in Configure Authentication Mode.

Configure User Connectivity Settings

The following text displays:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-328.png

Figure 20. User Connectivity Settings

The available user connection types are as follows:

  • LDAP (included with the Ephesoft Transact installer)
  • Microsoft Active Directory (MSAD)
  • Apache Tomcat (included with the Ephesoft Transact installer)

Note: Apache Tomcat is the simplest user connection type to set up, as it does not require any configuration. However, any changes to users (each time the user file is changed) will require a restart of Ephesoft Transact.

LDAP
  1. Select LDAP by typing 1 and pressing the Enter key.
  2. Provide the required details, as described in the table below.
LDAP property Description
Connection URL A valid URL to connect to an LDAP server. The connection URL should be in the following format:

ldap://<server_address>:<port_number>.

Connection Name A valid username to connect and access the LDAP server. This is the username of the user responsible for interacting with the server.
Connection Password The password for the user responsible for interacting with the server.
User Base The relative path where all 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 The relative path where all roles information will be located. This attribute defines where to look for a role corresponding to a user.
Role Name The 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 The group name for users with super admin privileges, such as access to the entire functionality of Ephesoft Transact. The super admin users can assign the user roles from the Access Manager screen in Ephesoft Transact (Home > System Configuration > Access Manager).

Note: In the table above, the configurable properties are listed exactly how they display on the screen.

  1. Press y if you need to change any details. Otherwise, press n to continue.
  2. Proceed to Install Applications.
Microsoft Active Directory (MSAD)
  1. Select MSAD by typing 2 and pressing the Enter key.
  2. Provide the required details, as described in the table below.
MSAD property Description
Connection URL A valid URL to connect to an Active Directory server. The connection URL should be in the following format:

ldap://<server_address>:<port_number>.

Connection Name A valid username to connect and access the Active Directory server. This is the username of the user responsible for interacting with the server.
Connection Password The password for the user responsible for interacting with the server.
User Base The relative path where all 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 The relative path where all roles information will be located. This attribute defines where to look for a role corresponding to a user.
Role Name The 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)
  • !(NOT)

Example: ((!cn=a*))(|cn=Ephesoft*)(&(cn=b*)))

This parameter is optional and can be left empty.

super admin group name The group name for users with super admin privileges, such as access to the entire functionality of Ephesoft Transact. The super admin users can assign the user roles from the Access Manager screen in Ephesoft Transact (Home > System Configuration > Access Manager).

Note: In the table above, the configurable properties are listed exactly how they display on the screen.

  1. Press y if you need to change any details. Otherwise, press n to continue.
  2. Proceed to Install Applications.
Apache Tomcat
  1. Select Tomcat by typing 3 and pressing the Enter key.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-330.png

Figure 21. Select Tomcat

  1. Press y if you need to change any details. Otherwise, press n to continue.
  2. Proceed to Install Applications.

Install Applications

  1. You will be prompted to install Tesseract (an OCR engine).

Note: Tesseract is optional and not recommended but has the option to support more languages. The recommended OCR engine is Nuance, which will be installed automatically in step 3 below.

    • Press n to decline installing Tesseract.
    • Press y to install Tesseract.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-331.png

Figure 22. Installing Tesseract

  1. The installer will prompt for registration information, which will assist with generating your license for Ephesoft Transact. Provide the registration details.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-331.png

Figure 23. Registration Information

    • Press y to make any changes. Otherwise, press n to continue.

The following screen will display:

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-331.png

Figure 24. Installing and Updating Applications

  1. The installer will continue to automatically install and upgrade other applications used by Ephesoft Transact such as LibreOffice, ImageMagick, Nuance, and Poco.

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-332.png

Figure 25. Installing and Updating Applications (cont.)

Important: This step may take some time depending on your server configuration. If the installation process is interrupted at any point due to internet connectivity issues, you can restart the installation process by running the ./install command again. To check the installation logs and see the installation status, you can use the following command:

tail -f /var/log/install-ephesoft.log
  1. This completes the normal installation. Continue to Service Pack Installation.

Silent Install

  1. Open the config.properties file located in the Response-Files folder.

Figure 26. vi config.properties Command

  1. Edit the values for the parameters in config.properties to reflect the required configuration for the install. See the table on configurable properties below for explanations of important parameters.

Figure 27. Edit config.properties File

Important: The upgrade may fail if any of the following settings in config.properties file are incorrect.

Configurable Property Description
input_database_patch_enable Select one of the following options depending on your server environment:

  1. For single-server upgrade, press y to run the database patch. The database patch is mandatory for a single-server upgrade, or if you are upgrading the first server in a multi-server installation.
  2. For a multi-server upgrade, the database patch is only required for the first server in the node. Press n for subsequent server upgrades.
input_upgrade_application Select y to upgrade Ephesoft Transact from an older version.
  1. Save the updated config.properties file to the same name in the Response-Files folder.
  2. Navigate to the folder with the unzipped Ephesoft Transact installer and start the silent installation process by running the following command:
./install -silentinstall -product

Figure 28. Start the Silent Installation

  1. The installer will pick up all the required details from the config.properties files.
  2. The silent install is complete. Proceed to License and Launch Ephesoft Transact 2020.1.02.

License and Launch Ephesoft Transact 2020.1.02

After installing the Ephesoft Transact service, you are ready to license and launch Ephesoft Transact. Follow the steps below:

Important: Refer to Licensing Requirements to complete the installation. Ephesoft recommends starting the service after your license is installed

  1. Start the Ephesoft Transact service by running the following command:
service ephesoft start

You can track the service start-up process by opening the catalina.out file in the /opt/Ephesoft/JavaAppServer/logs/ folder and running the following command:

tail -f catalina.out

https://ephesoft.com/docs/wp-content/uploads/2019/06/word-image-338.png

Figure 29. Launch Ephesoft Transact

  1. Open a web browser and enter the following Ephesoft Transact URL: http://<servername>:<portnumber>/dcma/home.html. The default port number is 8080. Allow time for the background configuration process to complete. The initial startup may require several minutes.

Important: If you receive an error or connection warning, you will need to open the firewall ports to connect to Ephesoft Transact.

  1. The Ephesoft Transact 2020.1.02 home page displays. Select Administrator or Operator to log in.

Figure 30. Ephesoft Transact Home Screen

  1. Enter the username and password. The default username is ephesoft, and the default password is demo.

Figure 31. Login Screen

Important: The system may require additional time to complete the initial login.

Conclusion

This completes the installation process.