Transact

⌘K
  1. Home
  2. Transact
  3. Install and Upgrade
  4. Transact 2019.2
  5. Install and Upgrade &#821...
  6. Installing on Linux Single and Multi-Server

Installing on Linux Single and Multi-Server

Introduction

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

  • Environment types — single or multi-server
  • Installation types — normal or silent

Installation Overview

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

Installation Task  General Scope of Activity 
Prerequisites  Prepare for 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.
License and Launch Ephesoft Transact 2019.2  Perform these steps to complete the install for Ephesoft Transact 2019.2.

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 and Linux distribution are supported. Refer to Platform Configuration and Third-Party Integrations for additional information.
  2. Verify that internet connectivity is available for this installation.

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. If you are installing with Oracle database, the database must be installed and configured prior to installing Ephesoft Transact.
  3. 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.

User Instructions

Download and Run the Ephesoft Transact Installer

Perform these steps to run the Ephesoft Transact 2019.2 installer.

  1. Refer to the Downloads page for information on how to obtain the Ephesoft Transact Installer.
  2. After saving the .zip file to your Linux machine, verify the MD5 Sum on the file against the MD5 Sum listed in the Partner Portal.
md5sum ./LINUX_Ephesoft_Transact_2019.2_251.zip
  1. Unzip the Ephesoft Transact installer by navigating to the folder containing the .zip file and execute the following command.
unzip LINUX_Ephesoft_Transact_2019.2_251.zip

Important: The last three digits of the ZIP file name are placeholders for the Ephesoft build number.

Figure 1. Execute the unzip command

If unzip is not installed, refer to your Linux distribution and use the listed command:

CentOS/RHEL:

sudo yum install unzip

Ubuntu:

sudo apt-get install unzip
  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 during any step of the install process, contact Ephesoft Support at tickets@ephesoft.com and provide the following files and details:

  • Your distribution and version of Linux.
  • var/log/install-ephesoft.log
  • /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, press n and proceed to Normal Install.
  • If you are performing a silent install, press 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.

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:
    1. “Do you want to run Ephesoft Application as a non-root user?”
    2. “Ephesoft Application will run as root. Do you want to change it?”
    3. “Ephesoft Application will run as <current user>. Do you want to change it?”
  • Select n for any option to proceed as a root user.
  • Select y to change the user and provide the required information, as prompted by the installer.

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. Ephesoft recommends keeping the default directory, but you can change the directory by editing the text line if needed.

Figure 7. Installation Path

  1. Press the Enter key to confirm the listed path.

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 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 default option is /opt/Ephesoft.
    1. 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. Select n to keep the default /opt/Ephesoft option.
  1. Press the Enter key to confirm the chosen folder.
  2. Confirm the server name that will be saved in the Properties file. The default server name is the OS hostname, which is automatically identified by the installer.
    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

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

hostname

This will display the current hostname of your Linux system.

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:

C:\Users\breanna.fitzgerald\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\1154245D.tmp

Figure 11. Select Database Type

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

Figure 12. Select MariaDB

    • You will be prompted to configure several properties for the database (see the table below for details on configurable properties).

Figure 13. Create New MariaDB Database

Maria DB property Description
system IP IP address of the machine on which MySQL service is running.
database username Enter root user name for MariaDB
Admin password Password that 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 name is report. This name can be changed as needed.
report archive database name Default report name is report_archive. This name can be changed as needed.
database port number The port number 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.

C:\Users\breanna.fitzgerald\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\F90850F9.tmp

Figure 14. Finalizing MariaDB Details

  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.

Figure 15. Select Oracle DB

    • 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 16. 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 Host name/IP for accessing the Oracle database.
User Name Username for the user of the Oracle database.
Password Password that will be used to access the Oracle database.
Port Port that will be used to access the Oracle database.
connection mode
  1. Oracle SID: Oracle system identification used to uniquely identify the database on a system.
  2. 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.

Figure 17. 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

The following steps vary depending on a single or multi-server installation.

  1. 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.
  2. For a multi-server installation, the database patch is only required for the first server in the installation. Press n for subsequent server installations.

Figure 18. Database Patch Execution

Configure Authentication Mode

The following text displays:

Figure 19. Authentication Configuration

The following text displays:

Figure 20. Application Protocol Options

The following text displays:

Figure 21. Apache Tomcat Server Port Number

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

Configure User Connectivity Settings

The following text displays:

Figure 22. 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 is 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.

Figure 23. 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.

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

Figure 24. Installing Tesseract

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

Figure 25. 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 26. Installing and Updating Applications

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

Figure 27. Installing and Updating Applications (cont.)

Note: 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 License and Launch Ephesoft Transact.

Silent Install

  1. Open the config.properties file located in the Response-Files folder. To do so, open a text editor and run one of the following commands:
  • vi config.properties
  • vim config.properties
  • nano config.properties

Note: You can also use WinSCP to connect to your Linux server and open the file in any UI text editor application.

  1. Edit the values for the parameters in config.properties to reflect the required configuration for the install. If using vi editor, run the i command to enter insert mode and edit the content. See the table on configurable properties below for explanations of important parameters.

Figure 28. Edit config.properties File

Important: The installation 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 Should be set to false for fresh installation.
  1. Save the updated config.properties file to the same name in the Response-Files folder. If using vi editor, press the ESC key to exit insert mode and use the :wq command to save and close the file.
  2. Navigate to the folder with the unzipped Ephesoft Transact installer and start the silent installation process by running the ./install -silentinstall -product command.

Figure 29. Start the Silent Installation

The installer will pick up all the required details from the config.properties files.

  1. The silent install is complete. Proceed to License and Launch Ephesoft Transact 2019.2.

License and Launch Ephesoft Transact 2019.2

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

Important: Ephesoft recommends restarting the service after your license is installed. To complete the installation, refer to Licensing Requirements.

  1. Start the Ephesoft Transact service by running the following command:
sudo 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

Figure 30. 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 2019.2 home page displays. Select Administrator or Operator to log in.

Figure 31. Ephesoft Transact Home Screen

  1. Enter the username and password.

Figure 32. Login Screen

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

Conclusion

This completes the installation process.

Articles